📚 课程目录第4章 DAG生成与可视化

4. DAG生成与可视化：把规则关系画出来

上一章我们搞清楚了规则怎么写，本章就来看看Snakemake内部是怎么理解这些规则的。DAG（有向无环图）可以说是Snakemake的核心数据结构。我个人习惯在写完一套规则后，先用DAG看一眼，确认依赖关系没有画错，不然跑起来发现问题，哭都来不及。

4.1 从规则到有向无环图

Snakemake解析Snakefile后，会根据输入输出文件的依赖关系自动构建一个有向无环图。这个图的节点就是各个规则任务，边表示数据流向。比如说，规则A输出data_cleaned.tsv，规则B又依赖它来做分析，那A到B就画一条箭线。

  DAG的特点：
  无环——不允许循环依赖
有向——数据从上游流向下游
分层——可并行执行的规则在图上可以看出来

你想想看，如果你写了一个循环依赖，比如规则A需要规则B的输出，规则B又需要规则A的输出，Snakemake会在构建DAG时直接报错。我刚开始用Snakemake时就被这种错误坑过——其实只是文件名取重了，但系统以为存在循环。

4.2 生成DAG的命令：snakemake --dag

生成DAG最简单的方式就是运行：

snakemake --dag target_file

这条命令会把DAG以DOT格式输出到终端。DOT是graphviz工具使用的文本描述语言，说白了就是用文本来描述图的结构。光看文本不太直观，我们通常把它传给graphviz做可视化。

我建议你直接这样用：

snakemake --dag target | dot -Tpdf > dag.pdf

这条命令做的事：

snakemake --dag target：生成DOT格式文本
| dot -Tpdf：管道传标准输入给dot，让它输出PDF格式
> dag.pdf：把PDF保存到文件

当然也可以输出PNG、SVG等格式。我个人更常用SVG，因为矢量图放大不模糊，方便放到文档里。

小技巧：如果你只想看部分规则的子图，可以在--dag后面指定具体文件名或规则名。比如snakemake --dag results/final_report.pdf可以只看生成这个文件的子图。

4.3 深入graphviz：DOT参数与定制

你可能会问：生成的图太丑怎么办？没错，默认的DOT输出确实很朴素。Snakemake提供了几个参数来调整图的外观。

我记得第一次用--dag时，画出来的节点全是灰色方块，根本分不清谁是谁。后来发现可以这样调：

snakemake --dag --dot-style dotted target | dot -Tpng > dag.png

常用的graphviz输出格式对比如下：

格式	特点	适用场景
PDF	矢量，可缩放，支持中文	正式报告、打印
PNG	位图，大图放大模糊	快速预览、嵌入网页
SVG	矢量，支持交互	在线文档、教学材料
DOT	文本格式，可再编辑	调试、二次处理

注意：如果你遇到中文字符乱码，通常是因为graphviz没找到中文字体。可以在dot命令中指定字体：snakemake --dag | dot -Tsvg -Nfontname=SimHei > dag.svg。不过Snakemake的DAG节点名一般是文件名或规则名，很少用中文，所以问题不大。

4.4 实战：从Snakefile到DAG图

来看一个实际的例子。假设你的Snakefile长这样：

rule clean_data:
    input:
        "raw/input.csv"
    output:
        "clean/cleaned.csv"
    shell:
        "python scripts/clean.py {input} {output}"

rule analyze:
    input:
        "clean/cleaned.csv"
    output:
        "results/analysis.csv"
    shell:
        "python scripts/analyze.py {input} {output}"

rule generate_report:
    input:
        "results/analysis.csv"
    output:
        "reports/final.pdf"
    shell:
        "python scripts/report.py {input} {output}"

这时你想看整个流程的依赖图，可以这样做：

snakemake --dag reports/final.pdf | dot -Tsvg > pipeline.svg

生成的SVG图里，clean_data、analyze、generate_report三个规则依次排开，箭头从clean到analyze再到report，一目了然。

以下是本章核心流程的可视化：

这张图展示了从Snakefile到最终可视化文件的完整流程。我个人觉得，记住这个流程会让你在调试时更有方向感。

4.5 常见问题排查

实际操作中你可能会遇到这些问题：

图太大怎么办？——用--dag加具体文件名或规则名，只生成子图。
节点名太长？——graphviz自动处理换行，一般不用操心。
程序报错说dot not found？——graphviz没装，赶紧装一下：apt install graphviz或brew install graphviz。
生成的图全是灰色？——默认确实没有颜色，但你可以用--dot-style dotted等参数让节点有区分。

曾经有个坑：我遇到过明明改了Snakefile，但生成的DAG还是老样子。后来发现是管道缓存了输出，加--forceall就能强制刷新：snakemake --dag --forceall target。

说到底，DAG可视化是Snakemake调试中最实用的功能之一。你不需要学什么复杂工具，一行命令就能把规则之间的关系画出来。这比盯着Snakefile逐行分析要快得多。