Snakemake 进阶：通配符、参数化与配置

通配符和参数化，是 Snakemake 从“写死脚本”走向“可复用流程”的拐点。我自己刚接触 Snakemake 时，就用 rule all 把每个样本的路径硬编码进去，结果项目一扩到 100 个样本，立马崩溃。后来学会通配符和 config 对象，才算真正掌握了这个工具。这一节我把这套东西给你拆开揉碎讲明白。

通配符（Wildcards）—— 规则模板的灵魂

通配符说白了就是花括号里的占位符。Snakemake 会根据你指定的 output 文件路径，反推出通配符的实际值，再代入 input 和 shell 命令。这套匹配机制叫 wildcard expansion。

核心规则：Snakemake 先确定目标文件（rule all 的输入），然后沿着依赖链反向推导通配符，有点像给变量赋值。

# 错误示范：通配符必须同时出现在 input 和 output 中
rule:
    input: "{sample}.fastq"
    output: "{sample}.bam"
    shell: "bwa mem ref.fa {input} > {output}"   # 这里缺 ref 的通配符？不对！ref 不是通配符，是固定文件

通配符名可以随意取，但同一个 rule 里不同文件中的同名通配符值 必须一致。如果 input 和 output 用不同的通配符名，Snakemake 会报错，或者你就在 output 里补上另一个通配符让它匹配。

我在项目中遇到过最经典的坑：大家喜欢把样本名写成 {sample}，但用 {batch}/{sample} 两级通配符时，必须保证 output 和 input 的结构镜像。比如：

rule bwa_mem:
    input:
        fq = "data/{batch}/{sample}.fastq",
        ref = "refs/hg38.fa"
    output:
        "results/{batch}/{sample}.bam"
    shell:
        "bwa mem {input.ref} {input.fq} > {output}"

看到没？{batch} 和 {sample} 在两个路径里同时出现，Snakemake 才能正确解析。你可以在 rule 内部通过 wildcards 对象访问这些值，比如 wildcards.sample。

参数化 —— 从配置文件到命令行选项

Snakemake 不做参数化，基本上就只能跑个 demo。参数化主要靠 config 对象：一个全局字典，可以在 Snakefile 里直接读取，也能通过 --config key=value 在命令行覆盖。

# 从外部 YAML 文件加载配置
configfile: "config.yaml"

rule run_alignment:
    input:
        fq = "data/{sample}.fastq"
    output:
        "results/{sample}.bam"
    params:
        software = config["aligner"],
        threads  = config["threads"],
        extra    = config.get("extra_params", "")
    shell:
        "{params.software} -t {params.threads} {params.extra} {input} > {output}"

你看，params 是 rule 里的一个字典，把 config 里的值拿到后，可以直接在 shell 里用 {params.xxx} 引用。这个模式比在 shell 里拼串干净得多。

注意：config 对象在 Snakemake 解析阶段就会读取，但 params 是在执行阶段才计算。这意味着你在 params 里可以用 wildcards 对象做条件判断。我曾经犯过一个错：把线程数写死在 shell 命令里，结果多节点调度时资源被浪费。用 params.threads 后，我可以在提交作业时根据样本大小动态调整。

配置管理：从硬编码到灵活可配

配置通常用一个 YAML 文件集中管理。Snakemake 支持 configfile 指令，也支持通过 --configfile 参数指定，甚至还能合并多个配置文件。下面这张表帮你快速搞懂不同配置层级的关系：

层级 方法 优先级
命令行参数--config key=value最高
显式 configfileconfigfile: "config.yaml"中等
Snakefile 内默认值config.setdefault("key", val)最低

我个人习惯把敏感参数（参考基因组路径、数据库版本）放在 config.yaml，把经常改的（线程数、内存）通过命令行覆盖。这样既保留可追溯性，又不用频繁改文件。

来看一个完整的实践片段：

# config.yaml
samples:
  - A
  - B
  - C
aligner: "bwa mem"
threads: 4

# Snakefile
configfile: "config.yaml"

rule all:
    input: expand("results/{sample}.bam", sample=config["samples"])

rule alignment:
    input:
        fq = "data/{sample}.fastq",
        ref = config["reference"]
    output:
        "results/{sample}.bam"
    params:
        aligner = config["aligner"],
        threads = config["threads"]
    shell:
        "{params.aligner} -t {params.threads} {input.ref} {input.fq} > {output}"

注意 expand() 函数：它把通配符和 config 列表组合起来，生成 rule all 的目标文件列表。没有它，Snakemake 不知道要跑哪些样本。

通配符、参数、配置 —— 三者的分工

讲到这里，你可能会问：通配符和参数化不都是让 Snakefile 变灵活吗？区别在哪？我画了张图帮你理清。

Snakemake 通配符、参数化、配置三层体系 通配符 (Wildcards) 根据输出文件名自动匹配 示例：{sample}.bam 参数化 (params) 从 config 或通配符提取 示例：params.threads 配置 (config) YAML / 命令行 / 默认值 示例：config["threads"] 解析值 提供值 Rule 执行 shell/combo/run 中引用通配符与 params 关键理解： - 通配符由 Snakemake 根据目标文件和 input/output 路径自动解析 - params 用于传递计算环境和样本相关的参数，可动态计算 - config 是全局配置层，适合管理工具版本、参考文件、运行参数

从图里能看明白：通配符负责数据命名空间（哪个样本）、config 负责全局常量（用什么工具、多少线程）、params 则作为桥梁，既可以用通配符做条件判断，又可以从 config 拿全局值。三者配合，Snakefile 才真正具备工程级复用能力。

避坑指南与个人习惯

  • 通配符不要和 Python 保留字冲突：我之前取了个 {input} 的占位符，结果 shell 里 {input} 被解析成内建对象，折腾半小时才发现。
  • 配置默认值一定要设：用 config.setdefault("parameter", default_val) 写在 Snakefile 开头，这样即使配置里没写，流程也不会崩。
  • 命令行传值注意类型：--config threads=4 传的是字符串 "4"，如果你在 Python 里需要整数，记得 int(config["threads"])。

一份可复用的 Snakemake 项目结构大概是这样的：

  • Snakefile — 主入口，包含 rule 和 configfile
  • config/ — 存放 YAML/JSON 配置文件
  • scripts/ — 被 run 调用的 Python/R 脚本
  • config.yaml — 对外暴露的参数清单

好了，这一章的核心就是让你搞清通配符、参数化和配置这三个概念怎么配合。下次写新流程时，记得先把 config.yaml 设计好，再写通配符规则，中间用 params 做转换。这样迁移到 Nextflow 时，你会发现很多概念是相通的 —— 只是名字和语法不同罢了。

← 上一章 📖 返回目录 下一章 →