Nextflow

Nextflow

概述

Nextflow 是用于构建可重复、可移植、可扩展数据管道的workflow语言和运行时。它在生物信息学领域占主导地位，但适用于任何数据密集型计算。nf-core 是一个社区管理的生产级 Nextflow 管道、可重用模块，以及基于 Nextflow 的 nf-core 工具。

关键概念：

• 数据流编程：管道是由通道连接的 process 任务。Nextflow 从数据依赖推断执行顺序和并行性 — 无需编写显式调度器。
• 编写一次，随处运行：相同的管道通过更改配置/配置文件（而非代码）在本地、HPC（SLURM、SGE、LSF、PBS）和云（AWS Batch、Google Batch、Azure Batch、Kubernetes）上运行。
• 可重现性：每任务容器（Docker/Singularity/Apptainer/Conda/Wave）+ -resume 缓存 + 固定的管道修订版。
• DSL2 是现代的必需语法：模块化的 process/workflow/include 定义。

此技能涵盖运行现有管道和开发自己的管道（Nextflow 语言 + nf-core 约定、使用 nf-test 测试、配置和部署）。

何时使用此技能

当用户想要以下操作时使用此技能：

• 运行 nf-core 或自定义 Nextflow 管道，或调试失败/恢复的运行。
• 编写或修改 .nf 脚本、nextflow.config、配置文件或 nextflow_schema.json。
• 编写或测试 nf-core 风格的模块/子工作流（main.nf、meta.yml、tests/、nf-test）。
• 配置执行器、容器或资源；扩展到 HPC 或云。
• 构建可重现的科学/生物信息学工作流程（即使没有提到"Nextflow"）。
• 理解 processes、channels、operators、take/emit、publishDir、ext.args、meta maps。

设置

Nextflow 需要 Bash 和 Java 17 或更新版本（支持 17–25）。用 java -version 验证。

# 安装 Nextflow（自包含启动器）
curl -s https://get.nextflow.io | bash      # 创建 ./nextflow
sudo mv nextflow /usr/local/bin/             # 放到 PATH 上
nextflow info                                # 验证

# 或通过 conda/bioconda（也获得托管 Java）
conda create -n nf -c bioconda -c conda-forge nextflow nf-core

# nf-core 工具（Python）用于创建/lint/运行 nf-core 资产
pip install nf-core            # 或: conda install -c bioconda nf-core
nf-core --version

固定引擎以确保可重现性：export NXF_VER=24.10.0（仅在需要时使用 [edge] 版本）。对于气隙/HPC，见 references/running-pipelines.md（离线模式）和 references/configuration.md。

两种工作模式

确定用户在哪条路径上 — 这会改变一切：

| 目标 | 从这里开始 |

|------|-----------|

| 运行现有管道（nf-core 或给定的 .nf） | references/running-pipelines.md |

| 开发新管道/模块/子工作流 | references/language.md + references/developing.md |

| 配置/扩展（HPC、云、容器、资源） | references/configuration.md + references/containers.md |

| 测试模块/管道 | references/testing.md |

快速开始

运行 nf-core 管道

首先始终用捆绑的 test 配置进行冒烟测试；它使用小型数据并证明您的环境工作正常。

# 1. 确认设置工作（下载管道 + 小型测试数据）
nextflow run nf-core/rnaseq -profile test,docker --outdir results

# 2. 实际运行：固定修订版 (-r)，选择容器引擎，传递输入
nextflow run nf-core/rnaseq -r 3.14.0 \
  -profile docker \
  --input samplesheet.csv \
  --genome GRCh38 \
  --outdir results \
  -resume

• -profile（单破折号）选择捆绑的配置文件；组合它们用逗号分隔，例如 test,docker。容器/基础设施配置文件（docker、singularity、conda）互斥 — 选择一个。
• --input、--genome、--outdir（双破折号）是管道参数。nf-core 管道接受样本表 CSV，而不是松散文件。
• -resume 重用上次运行的缓存结果。-r <version> 固定发布版本以确保可重现性。

使用 nf-core pipelines launch <name> 获取交互式、模式验证的方式来构建命令和 -params-file。见 references/running-pipelines.md。

编写最小管道

#!/usr/bin/env nextflow

process SAYHELLO {
    tag "$greeting"
    publishDir "results", mode: 'copy'

    input:
    val greeting

    output:
    path "${greeting}.txt"

    script:
    """
    echo '$greeting world' > ${greeting}.txt
    """
}

workflow {
    channel.of('hello', 'bonjour', 'hola') | SAYHELLO
}

nextflow run main.nf            # 重新运行时添加 -resume

完整语言（processes、channels、operators、带有 take/main/emit 的 DSL2 工作流、modules）在 references/language.md 中。

核心概念一览

• Process：运行脚本的工作单元（默认 Bash）。声明 input:、output:、可选的 directives（资源、容器、publishDir、tag、errorStrategy）和 script:/shell:/exec: 块。每个任务在自己的隔离工作目录（work/xx/yy…）中运行。
• Channel：连接进程的异步队列。队列通道是可消耗流；值通道保存单个可重用值。使用 channel.of、channel.fromPath、channel.fromFilePairs、channel.value 等工厂创建。
• Operator：转换/组合通道 — map、filter、collect、groupTuple、join、combine、mix、flatten、branch、multiMap、splitCsv、view、set。
• Workflow：组合进程。DSL2 工作流可以声明 take:（输入）、main:（逻辑）、emit:（命名输出）并作为子工作流包含。无名的 workflow {} 是入口点。
• Module：通过 include { NAME } from './path'（支持 as 别名）公开进程/工作流的 .nf 文件。
• Configuration：nextflow.config 设置 params、process 指令、executor、容器引擎和命名 profiles。选择器 withName:/withLabel: 定位特定进程。详见 references/configuration.md。
• meta map (nf-core)：在输入/输出元组中随文件一起传递元数据映射（[ id:'sample1', single_end:false ]）的约定，使样本在管道中保持标签。详见 references/developing.md。

nf-core 工具 CLI

nf-core 工具（v3+）将子命令分组在 pipelines、modules 和 subworkflows 下。（像 nf-core lint 这样的裸形式仍然可以工作但会警告 — 优先使用分组形式。）

| 命令 | 用途 |

|------|------|

| nf-core pipelines list | 列出/搜索 nf-core 管道（--json、关键词） |

| nf-core pipelines create | 从 nf-core 模板脚手架新管道 |

| nf-core pipelines launch <name> | 交互式、模式驱动的运行命令 + 参数文件 |

| nf-core pipelines download <name> | 下载管道 + 容器用于离线/HPC 使用 |

| nf-core pipelines lint | 根据 nf-core 标准对管道进行 lint（在仓库根目录运行） |

| nf-core pipelines schema build | 通过 Web GUI 构建/编辑 nextflow_schema.json |

| nf-core pipelines create-params-file <name> | 生成文档化的 YAML 参数文件 |

| nf-core pipelines bump-version / sync | 提升版本 / 与模板更新同步 |

| nf-core modules list/info/install/update/remove | 管理来自 nf-core/modules 的模块 |

| nf-core modules create / lint / test | 编写、lint 和 nf-test 模块 |

| nf-core modules patch / bump-versions | 修补已安装的模块 / 提升工具版本 |

| nf-core subworkflows install/create/lint/test | 子工作流的相同生命周期 |

完整命令参考、标志和示例：references/nf-core-tools.md。

必需 nextflow CLI

| 命令 | 用途 |

|------|------|

| nextflow run <pipeline> -profile <p> --outdir <dir> | 运行管道（路径、.nf 或 user/repo） |

| -resume | 重用之前运行的缓存结果 |

| -r <rev> | 运行特定的 git 修订版/标签/分支 |

| -params-file params.yml | 从 YAML/JSON 提供参数 |

| -c custom.config | 叠加额外配置文件 |

| -with-report -with-trace -with-timeline -with-dag flow.html | 执行报告、跟踪、时间线、DAG |

| -stub-run | 仅运行 stub: 块（干运行管道） |

| nextflow log | 检查过去的运行 |

| nextflow clean -f -before <run> | 删除旧的 work/ 数据 |

| nextflow pull / drop / list / info <repo> | 管理缓存的远程管道 |

配置、执行器、缓存内部和跟踪详情：references/configuration.md。

最佳实践（高价值习惯）

• 始终先 `test`：在真实数据之前使用 -profile test,docker（或 singularity/conda）— 快速且能发现环境问题。
• 固定一切：管道修订版（-r）、NXF_VER 和工具版本（容器）。不要为您将发表的科学运行 latest。
• 使用 `-resume` 并理解缓存：如果其输入、脚本或容器更改，任务将重新运行。详见 references/configuration.md 中的缓存调试。
• 通过 config/params-file 参数化，而非硬编码路径。将 params 和 profiles 保存在 nextflow.config 中。
• 每个进程一个容器/conda 环境；永远不要依赖主机上安装的工具。
• 对于 nf-core 开发：在编写新模块之前重用现有模块（nf-core modules install）；通过 ext.args 传递工具标志（而非在脚本中硬编码）；始终包含 stub: 块和 nf-test 测试；在提交之前运行 nf-core pipelines lint 和 prettier。
• 正确调整资源大小使用 process_low/medium/high 标签和 errorStrategy 'retry' 以及动态 task.attempt 扩展，而非一个巨大请求。
• 编写向前兼容的语法：严格语法解析器将在 Nextflow 26.04 中成为默认。优先使用小写 channel.of(...)、显式闭包参数（{ v -> ... }）、所有变量使用 def，以及 emit: 命名输出。用 nextflow lint 检查。

参考文件

需要深度时阅读相关文件 — 每个都是独立的：

• references/language.md — DSL2 语言：processes、directives、channels、operators、工作流（take/emit）、modules、动态资源、错误处理。
• references/configuration.md — nextflow.config、作用域、profiles、withName/withLabel 选择器、执行器（local/SLURM/云）、缓存/-resume 内部、跟踪/报告、nextflow CLI。
• references/containers.md — Docker、Singularity/Apptainer、Podman、Conda、Wave 容器；选择和启用引擎；常见陷阱。
• references/running-pipelines.md — 查找/运行 nf-core 管道、样本表、参数文件、参考基因组（iGenomes）、离线运行、机构配置、Seqera 平台。
• references/nf-core-tools.md — 完整 nf-core CLI 参考（pipelines/modules/subworkflows）、标志和工作流。
• references/developing.md — 编写 nf-core 管道和模块：模板布局、模块 main.nf/meta.yml、meta maps、ext.args/modules.config、子工作流、资源标签、linting 和 Harshil 对齐风格。
• references/testing.md — 模块/子工作流/管道的 nf-test：测试结构、断言、快照、标签、运行测试、CI。

官方文档：Nextflow https://www.nextflow.io/docs/latest/ · nf-core https://nf-co.re/docs/ · 培训 https://training.nextflow.io/