第1节：Snakemake简介与工作流基础概念

1.1 为什么需要工作流管理？

我们先抛开Snakemake具体是什么，聊聊一个现实问题：你手里的分析脚本越来越多，跑一个RNA-seq流程，先要质控、比对、定量，每一步都依赖上一步的输出。手动一个个跑？费时费力还容易出错。写一个大的shell脚本串起来？出了错得从头再来，中间哪个文件没生成你还得手动排查。

我之前维护过一个RNA-seq项目，跑了三天，最后发现比对步骤的参考基因组路径写错了。嗯，就是因为那个小错误，整个流程重跑了一遍。那时候我就想，能不能有一个工具，让它自己管理依赖、自动重试、甚至只重跑失败的那一步？

这就是工作流管理的意义。

1.2 Snakemake是什么？

Snakemake是一个用Python编写的、基于规则的工作流管理系统。说白了，你用Python语法写规则来描述每一步做什么，它会自动解析规则之间的依赖关系，然后按正确的顺序执行。

核心思想：你定义“图”（规则之间的依赖），Snakemake负责“遍历”（按顺序执行）。

让我从实际体验说起。我最初接触它时，最直观的感受是：它把流程的“逻辑”和“执行”分开了。你不用再操心哪些先跑、哪些后跑，你只需要告诉它最终想要什么文件，它自己就会往前推。

1.3 工作流的核心概念

要理解Snakemake，必须搞明白几个基本术语。

概念	说明	我的理解
规则（Rule）	定义一步操作，比如“对样本做质控”	相当于流程中的一个步骤
输入文件（Input）	规则执行前需要具备的文件	规则的“前置条件”
输出文件（Output）	规则执行后产生的文件	规则的“交付物”
通配符（Wildcard）	用于匹配不同样本的动态文件名	规则模板化的核心
Shell命令	规则中实际要运行的命令	真正干活的部分
依赖关系	由输入/输出文件自动推导的规则顺序	Snakemake的“自导航”能力

1.4 规则与依赖：一个简单的例子

写一个最简单的Snakefile，看看规则怎么定义。

rule all:
    input:
        "results/final_report.txt"

rule process_data:
    input:
        "data/raw_data.txt"
    output:
        "results/processed_data.txt"
    shell:
        "python scripts/process.py {input} > {output}"

rule generate_report:
    input:
        "results/processed_data.txt"
    output:
        "results/final_report.txt"
    shell:
        "python scripts/report.py {input} > {output}"

这里，rule all 是默认的“最终目标”。Snakemake会检查 final_report.txt 是否存在，如果不存在，它会往依赖链条回溯，发现必须先跑 generate_report，而该规则又依赖 processed_data.txt，于是继续回溯到 process_data。整个过程自动完成，你不用手动指定执行顺序。

我个人习惯：把 rule all 放在文件的最前面，它定义了工作流的最终产出。这会让依赖关系一目了然。

1.5 通配符：处理多个样本的关键

实际项目中，你不止处理一个样本。Snakemake的通配符机制就是为了解决这个问题。

rule all:
    input:
        "results/sample_1/quant.txt",
        "results/sample_2/quant.txt",
        "results/sample_3/quant.txt"

rule quant:
    input:
        "data/{sample}/reads.fastq"
    output:
        "results/{sample}/quant.txt"
    shell:
        "samtools quant -o {output} {input}"

看到 {sample} 了吗？这是一个通配符。它会自动匹配 sample_1、sample_2 等值。Snakemake会为每个样本生成一条独立的规则实例，互不干扰。

我曾经犯过一个错误：通配符写成了 {sample}，但在输入路径里写成了 {sample}/reads.fastq，输出路径里写成了 {sample}_quant.txt，两者通配符名称不一致。Snakemake会报错说你定义了未使用的通配符。一定记得通配符名字必须匹配。

1.6 Snakemake的执行流程

下面这张图展示了Snakemake执行一个工作流时的核心逻辑：从最终目标出发，反向推导出依赖图，再按拓扑顺序依次执行规则。如果某条规则失败，它会尝试重新执行，直到达到最大重试次数。

这个流程有一个关键点：如果某个规则执行失败，Snakemake会记录错误，但默认会继续尝试其他规则吗？注意，默认情况下，如果某个规则的输入文件缺失，Snakemake会立刻报错退出。但通过配置重试机制，你可以让它在失败时自动重跑，这正是本系列实战教程的核心。

1.7 几个重要的命令行参数

我们日常最常用的几个Snakemake命令。

# 运行工作流，默认寻找 Snakefile
snakemake

# 指定使用 8 个核心
snakemake --cores 8

# 查看即将执行的规则（不实际运行）
snakemake --dry-run

# 强制重新执行所有规则
snakemake --forceall

# 显示可视化DAG
snakemake --dag | dot -Tpng > dag.png

我个人习惯：每次修改规则后，先用 --dry-run 看一下执行计划，确认依赖解析正确无误，再开始实际运行。这点时间省不得。

1.8 为什么要关注失败重试？

实际生产环境中，失败是常态。网络抖动、内存不足、临时文件被清理、甚至是集群调度时资源竞争，都可能导致步骤失败。Snakemake提供了多种重试策略，包括单条规则重试、全局重试、批量重试等。后面我们会逐一深入。

举个例子，我在一个大型WGS分析项目中，100个样本并行跑，经常有1-2个因为网络IO超时而失败。没有重试机制的话，就得手动检查日志、重新提交。有了Snakemake的 --restart-times 参数，自动重试3次，几乎能覆盖所有偶发错误。

1.9 小结

这一节我们理清了工作流管理的基本思路，掌握了Snakemake的核心概念——规则、依赖、通配符，也看到了Snakemake如何自顶向下解析依赖并自动执行。这一套基础是后续深入失败重试机制的根基。记住一句话：Snakemake帮你管理流程的“逻辑图”，你只需要专注于每个步骤的“实现”。