4、参数文件管理：params与args的区别、默认参数设置

参数文件管理这个话题，说实话是 Nextflow 工程化里最容易被忽视但又最关键的一环。我见过太多人把参数扔在主脚本里，或者写一个长长的 --input 列表。项目一复杂，维护起来就头疼了。

本章我们聊清楚两件事：params 和 args 到底怎么分工，以及默认参数到底该怎么设。搞懂这些，你的 pipeline 才是真的可配置、可复用。

4.1 params 与 args：本质区别

很多初学者会把 params 和 args 搞混，其实它们根本不在一个层面上。

举个例子你就明白了。如果我在命令行写：

nextflow run main.nf --bam /data/sample.bam --outdir ./results

这时 args 是 ["--bam","/data/sample.bam","--outdir","./results"]。但 Nextflow 会自动把 --bam 解析成 params.bam，所以你在脚本里直接 params.bam 就能拿到值。

4.2 默认参数设置：从哪里开始？

默认参数不该写在 main.nf 里。为什么呢？因为一旦你开始用 nextflow.config 和配置文件，那默认值就会变得分散，很难追踪。我推荐下面这个三层策略：

1. 模块级默认：放在 modules/ 里的模块脚本中，用 params 声明最低安全值。
2. 工作流级默认：在 main.nf 的开头统一设置所有必填参数的默认值。
3. 环境级默认：在 nextflow.config 里根据 profile 覆盖特定环境的参数。

你会问：「为什么不在 nextflow.config 里写死？」嗯，我第一次迁移 pipeline 时也这么想。后来发现 config 文件里堆了上千行参数，根本看不出哪些是真正的默认值，哪些是临时调试值。

4.2.1 main.nf 中的典型写法

// main.nf
params.sample_id = "NA12878"
params.bam = "${projectDir}/data/${params.sample_id}.bam"
params.outdir = "./results"
params.genome = "hg38"
params.threads = 4
params.verbose = false

workflow {
    // 检查必填参数
    if (!file(params.bam).exists()) {
        error "BAM 文件不存在: ${params.bam}"
    }
    // ...
}

4.2.2 参数文件：结构化的默认配置

当参数多了（超过 20 个），我建议你把它们放到独立的配置文件中。Nextflow 支持 YAML、JSON、TOML 和 properties 格式。

// params.yaml
sample_id: "NA12878"
genome: "hg38"
threads: 4
outdir: "./results"
verbose: false

tools:
  gatk: "/usr/local/bin/gatk"
  bcftools: "/usr/local/bin/bcftools"

然后在 nextflow.config 里加载：

// nextflow.config
params {
  loadConfig("${projectDir}/conf/params.yaml")
}

profiles {
  prod {
    params {
      threads = 32
      outdir = "/data/prod/results"
    }
  }
  dev {
    params {
      verbose = true
      outdir = "./dev_results"
    }
  }
}

4.3 参数合并优先级

搞清优先级，才能预测 pipeline 的实际行为。不夸张地说，我踩过的坑里 80% 都和参数优先级有关。

你看到没？命令行参数永远说了算。所以我在设计中会故意把 main.nf 的默认值设得保守（比如线程数为 1），让用户有意识地在 config 或命令行里指定更合适的值。

4.4 参数文件的结构与版本控制

嗯，既然参数文件算外部配置，那自然要进 Git。但怎么进？我推荐这个结构：

project/
├── conf/
│   ├── params.yaml          # 生产环境默认参数
│   ├── params.dev.yaml      # 开发环境参数
│   ├── params.test.yaml     # 测试环境参数
│   └── profiles/            # 按 profile 拆分配置
│       ├── prod.config
│       ├── dev.config
│       └── test.config
├── modules/
│   ├── QC/
│   │   └── main.nf          # 含模块级 params 默认
│   └── variant_calling/
│       └── main.nf
├── main.nf
└── nextflow.config

这样当你 clone 仓库时，所有参数配置都一目了然。有人改了参数，Git diff 直接能看到变化。

4.5 模块参数与全局参数：命名空间冲突

Nextflow 没有真正的模块级私有参数，所以 params 是全局平的。两个模块如果都定义了 params.threads，后加载的会覆盖先加载的。

解决办法我推荐用前缀：

// modules/QC/main.nf
params.qc_threads = 2
params.qc_min_quality = 30

// modules/variant_calling/main.nf
params.vc_threads = 4
params.vc_min_dp = 10

虽然看着啰嗦，但可读性和安全性都好很多。

4.6 参数文件的运行时选择

运行 pipeline 时，你可以灵活选择参数文件：

# 使用默认参数文件
nextflow run main.nf

# 使用自定义参数文件
nextflow run main.nf -params-file conf/params.dev.yaml

# 使用参数文件 + 命令行覆盖
nextflow run main.nf -params-file conf/params.dev.yaml --threads 8

# 使用多个参数文件（后面的覆盖前面的）
nextflow run main.nf -params-file conf/base.yaml -params-file conf/override.yaml

我一般在 CICD 里这样用：

# .gitlab-ci.yml
run-pipeline:
  script: |
    nextflow run main.nf \
      -params-file conf/params.${CI_ENVIRONMENT_NAME}.yaml \
      --outdir s3://${BUCKET}/results/${CI_COMMIT_SHA}

这样每个环境有独立参数，CICD 自动选择，干净利落。

4.7 参数定义文档化

最后一个建议，每个参数都要有同名的 params.__doc__ 说明。虽然不是强制，但我强烈推荐：

// main.nf
params.genome_index = "/data/references/hg38/star"
params.genome_index__doc = "STAR 基因组索引路径，必须包含 SA、SAindex 等文件"

params.threads = 1
params.threads__doc = "并行线程数，根据节点 CPU 核数设置，建议不超过 32"

params.outdir = "./results"
params.outdir__doc = "输出目录，支持绝对路径和 S3 路径"

这样无论谁接手你的 pipeline，跑一下 nextflow config 就能看到每个参数的用途。