nextflow

Nextflow

概述

Nextflow 是一种工作流语言和运行时，用于构建可复现、可移植、可扩展的数据流水线。它在生物信息学领域占据主导地位，但也适用于任何数据密集型计算。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”）。
• 理解进程、通道、运算符、take／emit、publishDir、ext.args、元数据映射。

设置

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

# Install Nextflow (self-contained launcher)
curl -s https://get.nextflow.io | bash      # creates ./nextflow
sudo mv nextflow /usr/local/bin/             # put on PATH
nextflow info                                # verify

# Or via conda/bioconda (also gets a managed Java)
conda create -n nf -c bioconda -c conda-forge nextflow nf-core

# nf-core tools (Python) for creating/linting/running nf-core assets
uv pip install nf-core            # or: 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. Confirm setup works (downloads pipeline + tiny test data)
nextflow run nf-core/rnaseq -profile test,docker --outdir results

# 2. Real run: pin a revision (-r), pick a container engine, pass inputs
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            # add -resume on reruns

完整的语言内容（进程、通道、运算符、带 take／main／emit 的 DSL2 工作流、模块）请参阅 references/language.md。

核心概念一览

• 流程：运行脚本（默认使用 Bash）的工作单元。声明 input:、output:、可选的 directives（资源、容器、publishDir、tag、errorStrategy），以及 script:/shell:/exec: 代码块。每个任务都在独立的隔离工作目录（work/xx/yy…）中运行。
• 通道：连接各流程的异步队列。队列通道是可消费的流；值通道保存单个可重复使用的值。通过 channel.of、channel.fromPath、channel.fromFilePairs、channel.value 等工厂创建。
• 运算符：转换或组合通道——map、filter、collect、groupTuple、join、combine、mix、flatten、branch、multiMap、splitCsv、view、set。
• 工作流：组合各个流程。DSL2 工作流可以声明 take:（输入）、main:（逻辑）、emit:（命名输出），并通过 include 引入为子工作流。未命名的 workflow {} 是入口点。
• 模块：一个通过 include { NAME } from './path' 暴露流程或工作流的 .nf 文件（支持使用 as 起别名）。
• 配置：nextflow.config 用于设置 params、process 指令、executor、容器引擎和命名的 profiles。选择器 withName:/withLabel: 用于指定特定流程。参见 references/configuration.md。
• 元数据映射（nf-core）：将元数据映射（[ id:'sample1', single_end:false ]）与输入/输出元组中的文件一同传递的惯例，可让样本在整个流水线中保留标签。参见 references/developing.md。

nf-core tools 命令行界面

nf-core tools（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 标准检查流水线（在仓库根目录运行）
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	编写、检查并使用 nf-test 测试模块
nf-core modules patch / bump-versions	修补已安装的模块 / 更新工具版本
nf-core subworkflows install/create/lint/test	子工作流的相同生命周期管理命令

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

必备 nextflow 命令行界面

命令	用途
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 中的缓存调试说明。
• 通过配置文件/参数文件设置参数，不要硬编码路径。将 params 和配置方案保留在 nextflow.config 中。
• 每个进程使用一个容器/conda 环境；切勿依赖主机上安装的工具。
• 开发 nf-core 时：编写新模块前，先复用已有模块（nf-core modules install）；通过 ext.args 传递工具标志（不要在脚本中硬编码）；始终包含 stub: 块和 nf-test 测试；提交前运行 nf-core pipelines lint 和 prettier。
• 合理配置资源：使用 process_low/medium/high 标签，并结合动态 task.attempt 缩放使用 errorStrategy 'retry'，而不是一次申请大量资源。
• 编写向前兼容的语法：严格语法解析器将在 Nextflow 26.04 中成为默认选项。优先使用小写的 channel.of(...)、显式闭包参数（{ v -> ... }）、为所有变量使用 def，以及带 emit: 名称的输出。使用 nextflow lint 检查。

参考文件

需要深入了解时，请阅读相关文件——每个文件都可独立阅读：

• references/language.md — DSL2 语言：进程、指令、通道、运算符、工作流（take/emit）、模块、动态资源、错误处理。
• references/configuration.md — nextflow.config、作用域、profiles、withName/withLabel 选择器、执行器（本地/SLURM/云端）、缓存/-resume 内部机制、跟踪/报告、nextflow CLI。
• references/containers.md — Docker、Singularity/Apptainer、Podman、Conda、Wave 容器；选择并启用引擎；常见注意事项。
• references/running-pipelines.md — 查找/运行 nf-core 流水线、样本表、参数文件、参考基因组（iGenomes）、离线运行、机构配置、Seqera Platform。
• references/nf-core-tools.md — 完整的 nf-core CLI 参考（流水线/模块/子工作流）、标志和工作流。
• references/developing.md — 编写 nf-core 流水线和模块：模板布局、模块 main.nf/meta.yml、meta 映射、ext.args/modules.config、子工作流、资源标签、代码检查和 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/

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户提供的信息，确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一个染色体、几千个细胞）上运行流程。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请执行以下操作
输入之间的基因组版本或标识符不匹配	停止并进行统一处理（liftover、ID 映射），然后再继续。
这些说明中的函数、标志或端点在已安装版本中不存在	查看已安装版本自身的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作假设。

诚信规则

• 切勿编造结果、参数、标识符、引用或统计数据。如果某项内容无法运行或验证，请如实说明。
• 不要作出超出统计数据支持范围的生物学意义解读；报告多重检验校正情况。
• 将此处与版本相关的细节视为可能过时：请根据已安装版本的官方文档确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须事先征求同意。

相关技能

• pacsomatic：适用于从 BAM 输入开始的 nf-core/pacsomatic 肿瘤与正常样本配对工作流的操作工具包。
• bulk-rnaseq：端到端的 bulk RNA-seq 编排器——从原始 FASTQ 读段开始，依次进行 QC 和剪切（FastQC、fastp/Trim Galore）、比对和定量…
• latchbio-integration：使用 Python SDK、CLI、Latch Data 和 Registry、Nextflow、Snakemake… 在 Latch 上构建、注册、调试和运行生物信息学工作流。