Nextflow Modules了解与使用

Nextflow Modules Using

Nextflow 工程项目的核心–Module，像乐高一样搭流程

总览

Nextflow 脚本可以包含来自其他脚本的定义（工作流、流程和函数）。模块是一个独立的流程定义及其对应的规范文件。模块可以在流水线中重复使用，也可以跨项目共享。通过将流程定义打包成模块，您可以避免代码重复，并受益于社区的改进。

  • Local modules
  • Registry modules
  1. Local modules

本地模块直接存储在您的项目中并进行维护。您可以使用带有相对路径的 include 关键字来包含本地模块的定义。

include { CAT } from './modules/cat'

workflow {
    data = channel.fromPath('data/*.txt')
    CAT(data)
}

上述代码片段将名为 CAT 的进程从包含脚本导入到包含脚本中。包含源 ./modules/cat 指的是相对于包含脚本路径的 ./modules/cat.nf 脚本。

  1. Registry modules

注册模块来源于 Nextflow 注册中心或兼容的模块注册中心。与本地模块类似，注册模块也存储在您的项目中，但它们的安装和管理需要使用 nextflow module 命令。

把别人编写好的 Nextflow 分析模块，像安装软件包一样搜索、安装、固定版本并直接运行

传统的 Nextflow 模块通常需要你从 GitHub 仓库获取代码，再在工作流中导入和调用。Registry Modules 则通过模块注册表来发现、安装和管理模块。

Nextflow Registry（搜索模块、查看版本和文档）
        ↓
`nextflow module` 命令（安装、管理模块版本）
        ↓
你的项目目录（保存已安装的模块代码和相关文件）
        ↓
调用模块或独立运行（集成进工作流，或者单独测试）
  • Discoverability：可发现性
  • Version management：版本管理
  • Direct execution：直接执行
  • Standard structure：标准化目录结构
对比项 nf-core local
来源 nf-core 社区模块仓库 当前 pipeline 自己编写或维护
主要用途 封装通用生物信息学工具 实现项目专用处理逻辑
跨项目复用 通常较容易 通常需要自行迁移和适配
更新方式 可通过 nf-core/tools 管理模块版本与更新 通常由项目开发者手动维护
测试与规范 通常遵循 nf-core 模块规范，配有测试 取决于项目自己的实现与规范
Nextflow 执行机制 process 被调用后正常执行 process 被调用后同样正常执行

local 不等于在本地电脑运行，nf-core 也不等于在远程服务器运行。 两者都是项目代码中的模块分类。无论放在哪个目录，最终都可以由 Nextflow 调度到你配置的计算环境执行

1. Using modules

Nextflow 模块系统允许您从集中式注册表中发现、安装和管理可重用模块。本页介绍如何在管道中使用模块。

1.1 Discovering modules

使用模块搜索命令查找可用模块module search

nextflow module search alignment
nextflow module search "quality control" -limit 10

结果包括模块名称和描述。使用 -output json 参数可获得机器可读的输出。

> nextflow module search alignment
Searching for 'alignment'...

Top 20 matching module(s):

  nf-core/clustalo/align
    Description: Align sequences using Clustal Omega

  nf-core/alignoth
    Description: Creating alignment plots from bam files

1.2 Installing modules

使用模块安装命令将模块从注册表下载到您的项目中module install：

nextflow module install nf-core/fastqc
nextflow module install nf-core/fastqc -version 0.0.0-0c7146d

从 nf-core 镜像的模块不遵循标准的语义版本控制。相反，它们使用 0.0.0-<哈希值> 格式，其中后缀是 nf-core 模块提交哈希值的一小部分。

Nextflow 将已安装的模块存储在 modules/ 目录中，并在模块旁边创建一个 .module-info 文件，以记录安装元数据，例如模块校验和和注册表 URL。会在项目目录安装一下modules的文件夹

> tree -h modules
[  96]  modules
+-- [  96]  nf-core
    +-- [ 256]  fastqc
        ├-- [ 206]  environment.yml
        ├-- [2.4K]  main.nf
        ├-- [3.6K]  meta.yml
        +-- [ 128]  tests
            ├-- [ 12K]  main.nf.test
            +-- [ 14K]  main.nf.test.snap

4 directories, 5 files

1.3 Listing installed modules

使用 module list 命令查看项目中已安装的所有模块：

nextflow module list

输出结果显示每个模块的名称、已安装版本以及是否已在本地修改。使用 -output json 参数可获得机器可读的输出结果

需要在项目目录下去运行,而不是别的项目内,相当于搜索module文件夹

> nextflow module list

Installed modules:

Module                                  Version        Status
----------------------------------------------------------------------
nf-core/fastqdl                         0.0.0-79bf96a  OK
nf-core/fastqc                          0.0.0-7574f3f  OK

1.4 Viewing module information

使用模块视图命令可以查看模块的元数据和使用模板 module view

nextflow module view nf-core/fastqc
nextflow module view nf-core/fastqc -version 0.0.0-0c7146d

具体查看参数是什么?怎么用?

> nextflow module view nf-core/fastqc

Module:      nf-core/fastqc
Version:     0.0.0-7574f3f
URL:         https://registry.nextflow.io/modules/nf-core/fastqc@0.0.0-7574f3f
Description: Run FastQC on sequenced reads
Authors:     @drpatelh, @grst, @ewels, @FelixKrueger
Maintainers: @drpatelh, @grst, @ewels, @FelixKrueger
Keywords:    quality control, qc, adapters, fastq

Tools:
  - fastqc
    Homepage: https://www.bioinformatics.babraham.ac.uk/projects/fastqc/

1.5 Including modules

可以通过名称包含从注册表安装的模块:

include { FASTQC } from 'nf-core/fastqc'

workflow {
    reads = channel.fromPath('data/*.fastq')
    reads = reads.map { fastq -> tuple([id: fastq.baseName], fastq) }
    FASTQC(reads)
}

本地模块必须通过相对路径引入：

include { FASTQC } from './modules/local/fastqc'

1.6 Running modules directly

对于临时任务或测试，可以直接运行模块，无需创建包装工作流

nextflow module run nf-core/fastqc --meta.id test_sample --reads sample1_R1.fastq.gz

如果模块尚未安装，该命令会自动下载。它接受所有标准的 Nextflow 运行选项（-profile、-resume 等）：

nextflow module run nf-core/fastqc \
    --meta.id test_sample \
    --reads sample1_R1.fastq.gz \
    -with-docker

或者本地跑main.nf

nextflow module run ./modules/local/fastqc/main.nf \
    --meta.id test_sample \
    --reads sample1_R1.fastq.gz \
    -with-docker
  1. 模块参数(Module parameters)

Nextflow 会根据模块声明的输入，推断运行模块时可以传入哪些参数。 不需要再单独定义一套参数列表。

Nextflow 会根据模块定义的输入，推断运行模块时需要哪些参数。

模块类型 输入声明位置 示例
process 模块 input: path reads
命名的 workflow 模块 take: samples: Channel<Sample>

input: 和 take: 不是两种不同的数据类型，而是属于不同层级的输入声明

nextflow module run ./rnaseq.nf \
    --samples samples.csv \
    --index genome.fa

整体思路类似，但 nextflow run 和 nextflow module run 接收参数的机制不完全一样。 关键是区分：命令行参数先交给谁，以及谁负责把数据传给 process

nextflow.enable.types = true

workflow RNASEQ {
    take:
    samples: Channel<Sample>
    index: Value<Path>
    strandedness: String?

    main:
    // ...

    emit:
    aligned: Channel<AlignedSample> = ch_aligned
}

record Sample {
    id: String
    fastq_1: Path
    fastq_2: Path
}

record AlignedSample { /* ... */ }

1.7 Removing modules

使用 module remove 命令删除已安装的模块：

nextflow module remove nf-core/fastqc
  • -keep-files：删除 .module-info 文件，但保留 modules/ 目录中的模块文件
  • -force：即使模块目录没有 .module-info 文件或有本地修改，也将其删除。

2. Developing modules

2.1 Creating a module

用 Nextflow 命令自动创建一个模块的初始文件，以及如何选择创建 process 模块还是 workflow 模块

以前你需要手动创建模块目录、编写 main.nf 等文件；现在可以让 Nextflow 先帮你搭好基本框架，再填入具体逻辑

  • process 模块：封装一个具体任务,这个模块主要负责一件事
  • workflow 模块：封装一组任务,封装一组任务

如何使用 nextflow module create 创建一个模块，以及创建后会生成哪些文件。 我们按命令、文件、命名规则三个部分理解

  1. module create
nextflow module create myorg/my-module

这是一个创建模块骨架的命令（scaffold），类似于先生成一个项目模板，再往里面编写实际代码。

这里的的myorg/my-module是模块的标识符,不是process的定义名称,也不是github的地址

  1. 生成文件
文件 作用 说明
main.nf 核心代码 编写 Nextflow 的 process 或 workflow 定义，决定任务如何执行，以及输入和输出如何声明。
meta.yml 模块规格 描述模块的元信息、输入和输出等，帮助使用者了解模块的接口。它不是实际执行分析命令的脚本。
README.md 使用说明 记录模块的用途、输入输出和使用方法，方便其他人理解和复用。
  1. 代码定义

模块在模块系统中的标识符，与 main.nf 内部定义的 process 或 workflow 名称，是两个不同的概念。

  1. 定义模块类型
nextflow module create myorg/my-workflow -kind Workflow

默认模板启用静态类型（static typing）；添加 -legacy 则创建不使用静态类型的传统风格模块。

2.2 Module strcuture

注册表模块遵循标准目录结构

modules/
└── myorg/
    └── my-module/
        ├── .module-info     # Integrity checksum
        ├── README.md        # Documentation
        ├── main.nf          # Module script
        ├── meta.yml         # Module spec
        ├── resources/       # Optional: Module resources
        └── templates/       # Optional: Process script templates
  1. main.nf

main.nf 文件包含流程定义。例如，一个简单的 FastQC 封装模块：

process FASTQC {
    tag "$meta.id"
    label 'process_medium'

    conda 'bioconda::fastqc=0.12.1'
    container 'biocontainers/fastqc:0.12.1--hdfd78af_0'

    input:
    tuple val(meta), path(reads)

    output:
    tuple val(meta), path("*.html"), emit: html
    tuple val(meta), path("*.zip") , emit: zip

    script:
    """
    fastqc $reads --threads $task.cpus
    """
}
  • 模块必须包含一个名为 main.nf 的脚本, 模块的主要代码统一放在 main.nf 中，不能把多个独立脚本都当作模块入口。
  • 模块必须定义一个 process 或一个具名 workflow
  • 模块可以定义一个入口 workflow，以覆盖 module run 的默认行为
  1. resources

Nextflow 模块中的 resources/ 资源目录。它的作用是：让模块除了 main.nf 代码之外，还可以携带数据文件、辅助脚本等资源，并在任务运行时使用它们

my-module/
├── main.nf
└── resources/
    ├── data/
    │   └── file.txt
    └── usr/
        └── bin/
            └── hello.sh
  1. meta.yml

meta.yml 文件包含模块的元数据，包括模块名称、版本、描述、作者以及输入/输出规范。注册表使用此文件来显示模块信息并生成使用模板。

  1. templates

templates/ 用来存放 process 执行时需要使用的脚本模板。

2.3 Validating a module

使用测试命令进行module测试

nextflow module validate myorg/my-module