📚 课程目录第4章 MetaPhlAn基础运行命令

4、MetaPhlAn基础运行命令：从原始序列到物种谱图

MetaPhlAn 说白了就做一件事：把你手上乱糟糟的测序 reads，变成一张物种相对丰度表格。基础调用并不复杂，但参数怎么选、输出怎么看，这里头有不少门道。我刚开始用的时候也踩过坑，今天咱们把这层窗户纸捅破。

基本调用：一杆进洞

一个完整的 MetaPhlAn 分析，其实就一行命令。但注意，它的底层依赖 Bowtie2 去做比对。

metaphlan input.fastq --input_type fastq \
  --bowtie2db /path/to/metaphlan_databases \
  --nproc 8 \
  -o profile.txt

嗯，这里有几个要点。

--input_type：明确告诉它输入是 fastq 还是 fasta。我个人习惯写成 fastq，万一写错了，它会报错，白白浪费时间。
--bowtie2db：指向数据库目录。如果不指定，MetaPhlAn 会从默认路径加载。但我建议每一次都显式写出来，防止环境变量搞鬼。
--nproc：CPU 线程数。不是越多越好。我实测过，8 核左右性能收益最高，再往上提升就有限了。
-o：输出文件路径。默认只输出表格。如果你想同时保留 Bowtie2 的中间比对结果，还得加参数。

关键参数解读：不是摆设

MetaPhlAn 4 的参数变多了。我挑几个实战中必须搞清楚的，列在下面。

参数名	作用	我的建议
`--input_type`	指定输入格式：fastq / fasta / bowtie2out	如果不是二次分析，一律用 fastq
`--bowtie2db`	数据库路径	绝对路径更保险
`--nproc`	线程数	8 左右，内存不够时降到 4
`--unclassified`	输出未分类 reads 到指定文件	建议加上，方便排错
`--no_map`	不保留 Bowtie2 比对中间文件	硬盘吃紧时用，默认不保留
`--preset`	设置分析预设（n1 / n2 / n3）	重要，见下文

我的小习惯：第一次跑样本时，我一定加上 --unclassified unclassified.fastq。为什么？如果结果异常，我可以直接看这些未分类的 reads 是什么东西——是宿主污染还是数据库缺失，一目了然。

三个预设：n1、n2、n3 到底选哪个？

MetaPhlAn 4 引入了 --preset 参数，这是它跟前代版本最大的区别。简单说：

n1（默认）：只比对 unique 标记基因。速度最快，但低丰度物种可能漏掉。
n2：放宽比对条件，加入部分多拷贝基因。灵敏度提高，但假阳性也会增加。
n3：几乎全基因集比对，灵敏度最高。适合深度测序或极度低丰度物种的捕捉。

我怎么选？
大部分情况下，n1 够用。如果你在分析低生物量样本（比如血液、组织），可以试试 n2。我曾经在肠道菌群项目中用过 n3，结果跑了一天一夜，最后丰度变化极小。所以，没有特殊需求，别轻易上 n3。

输出文件结构：一张表里藏了多少信息？

默认输出是一个 TSV 表格。咱们来拆解一下。

#clade_name        NCBI_tax_id  relative_abundance  additional_species
k__Bacteria        2            98.52342            .
k__Archaea         2157         1.47658             .
p__Bacteroidetes   976          45.12386            .
g__Bacteroides     816          22.34567            Bacteroides_vulgatus
s__Bacteroides_vulgatus  1796612  12.34512          .
...

核心字段就四个：

clade_name：物种分类名称，从界到种一步步展开。
NCBI_tax_id：NCBI 分类编号。
relative_abundance：相对丰度（百分比）。注意，它是归一化后的值。
additional_species：当一行对应多个物种时，这里列出可能匹配的物种。

注意：relative_abundance 是比例值，不是绝对丰度。不同样本之间不能直接比较丰度绝对值，只比较相对变化。我见过新手直接把不同样本的丰度值拿去做差异分析，结果全是假的。

从原始序列到物种谱图的完整流程

咱们用一张图把整个过程串起来。我个人觉得，理解这张图比记住参数更重要。

核心逻辑：从原始序列出发，经过 Bowtie2 比对到标记基因数据库，然后计算每个物种的相对丰度，最后输出两份内容相同的谱图文件（TSV 和 BIOM）。未分类的 reads 可以单独保存，用于追溯问题。

一个完整的运行示例

咱们用真实参数跑一遍。假设你有一个双端测序的数据，先合并成单个 fastq 也好，或者直接用 MetaPhlAn 的 paired-end 模式。我个人习惯先合并，因为后续操作更清爽。

cat sample_R1.fastq sample_R2.fastq > sample.fastq

metaphlan sample.fastq --input_type fastq \
  --bowtie2db /data/databases/metaphlan_v31 \
  --nproc 10 \
  --unclassified sample_unclassified.fastq \
  --preset n2 \
  -o sample_profile.txt

跑完你会看到三个输出：

sample_profile.txt：物种相对丰度表。
sample_unclassified.fastq：未能分类的 reads。
临时文件夹里还会有一堆 Bowtie2 的中间文件，不过任务结束后会被清理掉。

经验之谈：我第一次跑时忘了指定 --nproc，结果默认只用 1 核，一个样本跑了 3 小时。后来加上 8 核，半小时搞定。所以，一定要显式设置线程数。

你可能踩过的坑

嗯，说两个我自己遇到的。

数据库路径错：MetaPhlAn 报错信息很模糊，可能只说“Database not found”之类的。我曾经花了一上午，最后发现是路径末尾少了个斜杠。现在我全部写绝对路径，少很多折腾。
临时文件夹撑爆硬盘：Bowtie2 会在临时目录写大量索引缓存。如果你跑几十个样本，临时目录很容易爆。我一般跑之前先检查 /tmp 的剩余空间，不够就手动指定其他位置。

export TMPDIR=/large_disk/tmp

对，环境变量 TMPDIR 会告诉 MetaPhlAn 和 Bowtie2 把临时文件写到哪里。

好了，到这里你已经可以跑通一个完整的 MetaPhlAn 分析，并且能读懂输出文件了。这些基础操作练扎实了，后续的敏感性分析才能玩得转。