规则执行与日志：snakemake命令行参数、日志输出、--dry-run预览
运行工作流，说白了就是敲命令。但怎么敲、怎么看结果、怎么在正式跑之前发现坑，这里面有不少门道。我做Snakemake这些年，见过很多人在这一步栽跟头——要么日志看不懂，要么直接跑完才发现写错规则名。今天我把常用的命令行参数和日志套路讲清楚。
基础运行：snakemake命令长什么样
最朴素的用法就是直接敲 snakemake。它会找当前目录下的 Snakefile，然后执行第一个规则。但实际项目中我很少这么干，因为通常需要指定目标文件。
snakemake -s Snakefile -c 4这条命令干了三件事：指定入口文件（-s），分配4个核心（-c），默认执行第一个规则。嗯，这里有个坑：-c 是旧版写法，新版推荐 --cores。我自己写命令习惯用长选项，清晰些。
| 参数 | 简写 | 说明 | 我的习惯 |
|---|---|---|---|
--snakefile | -s | 指定 Snakefile 路径 | 项目结构复杂时必写 |
--cores | -c | 分配 CPU 核心数 | 我通常写 --cores all |
--jobs | -j | 并行作业数（集群用） | 本地用 --cores 即可 |
--dry-run | -n | 预览执行计划 | 每次必先跑一次 |
--forcerun | -R | 强制重新运行某些规则 | 调试时用，慎用 |
小技巧：如果你在集群上跑，记得用 --cluster 或 --profile。我曾经在 SLURM 上直接 snakemake --cores 100，结果作业管理器只分配了1个节点……正确做法是用 --cluster "sbatch --ntasks=1 --cpus-per-task={threads}"。
--dry-run：不跑代码，只给你看剧本
--dry-run 是我最爱的参数，没有之一。它可以让你看到 Snakemake 计划执行哪些规则、输入文件、输出文件、通配符具体值。说白了就是预演，不跑实际命令。
snakemake -n result/processed/sample_A.bam输出大概长这样：
Building DAG of jobs...
Job stats:
job count min threads max threads
------- ----- ----------- -----------
align_to_ref 4 8 8
fastqc_raw 4 1 1
multiqc 1 2 2
total 9 1 8
[Mon Aug 12 14:23:01 2025]
rule fastqc_raw:
input: data/raw/sample_A.fastq.gz
output: result/fastqc/sample_A_fastqc.html, result/fastqc/sample_A_fastqc.zip
jobid: 2
reason: Missing output files: result/fastqc/sample_A_fastqc.html, result/fastqc/sample_A_fastqc.zip
wildcards: sample=sample_A
resources: mem_mb=1000, disk_mb=5000
[Mon Aug 12 14:23:01 2025]
rule align_to_ref:
input: result/trimmed/sample_A_trimmed.fastq.gz, reference/genome.fa
output: result/processed/sample_A.bam
jobid: 1
reason: Missing output files: result/processed/sample_A.bam
wildcards: sample=sample_A
threads: 8
resources: mem_mb=4000, disk_mb=20000
This was a dry-run (flag -n). The actual commands would have been executed.你想想看，有了这个，我就能在跑大数据前知道通配符是否匹配、文件是否存在、资源够不够。我曾经有一次通配符写成了 sample_{sample_id}，但实际文件命名是 sample_A，dry-run 直接报错说找不到匹配，省了我半小时等待。
建议：把 snakemake -n 作为 Git 提交前的必要检查步骤。我团队规范里写死了：任何人提交 Snakefile 之前必须跑一次 snakemake -n，截图放到 PR 描述里。
日志输出与调试：怎么知道哪里挂了
默认情况下，Snakemake 会把每个作业的输出打印到终端。但如果你在后台跑或集群提交，日志会丢失。这时候就需要 --logdir 或重定向。
1. 控制台日志等级
用 -v 控制啰嗦程度，我一般这么配：
snakemake --quiet 2>&1 | grep ERROR # 只看错误
snakemake --verbose # 看全部细节，调试时用2. 作业日志文件
Snakemake 会自动给每个规则生成日志文件，路径由 log 指令指定。我自己设计 Snakefile 时，每个规则都会加 log: "logs/{rule}-{wildcards}.log"。这样任何输出都能回溯。
rule fastqc_raw:
input: "data/raw/{sample}.fastq.gz"
output: "result/fastqc/{sample}_fastqc.html",
"result/fastqc/{sample}_fastqc.zip"
log: "logs/fastqc_raw-{sample}.log"
shell:
"fastqc {input} -o result/fastqc/ 2> {log}"警告：别把日志和输出文件混用一个目录。我之前犯过：把 .log 写进 output，Snakemake 以为那是产出文件，结果删除后触发重跑。日志就该放 logs/，输出放 result/，各管各的。
3. --report 生成HTML报告
Snakemake 还有一个好用的内置报告：--report report.html。它会抓取所有规则状态、日志、时间、资源使用，生成一个可以在浏览器里翻看的大报告。我每次跑完都会生成一份，方便团队成员回顾。
snakemake --report report.html核心执行流程速览
我把 Snakemake 从解析到执行的流程画了一下，每个阶段你会遇到的常见问题也标出来了。
左边列出的三类问题，--dry-run 直接就能暴露。我就是在一次质控流程里，通配符 {sample} 写成了 {sample_id}，dry-run 报告“未匹配任何通配符”，我才发现 Snakefile 和实际文件命名不一致。这要是直接跑，得等半小时才发现失败。
常用组合：我的一天怎么启动工作流
给你看看我实际项目里的操作习惯：
- 先 dry-run：
snakemake -n确认执行计划。 - 看看会不会消耗太多磁盘：
snakemake -n --detailed-summary会列出每个输出文件大小。 - 正式跑，同时后台输出日志：
nohup snakemake --cores 16 --latency-wait 10 > snakemake.log 2>&1 &--latency-wait是等待网络文件系统延迟，我在集群上必加。 - 想强制重跑某个规则：
小心：snakemake -R align_to_ref --forcerun-R会强制重跑该规则及其下游。
避坑提醒：我刚开始用 --forcerun 时，直接 snakemake -R 不带规则名，结果它把整个工作流重跑了一遍……正确的做法是 snakemake -R fastqc_raw，只重跑 fastqc_raw 规则。
日志分析小技巧
跑完工作流后，我通常会这样查看日志：
- 看有没有失败规则：
grep -i "error\|failed" snakemake.log - 看执行时间：
grep "finished job" snakemake.log会列出每个作业的耗时。 - 看资源使用：
grep "mem_mb\|disk_mb" snakemake.log
对了，Snakemake 还支持 --config 传参数，这个我们后面专门讲配置时会细说。但今天你先记住：--dry-run 是你的安全网，日志是你的回溯绳，二者配合能帮你省下大量调试时间。