MetaPhlAn 基本用法：运行命令与文件格式

各位同学，今天我们来啃最核心的部分——MetaPhlAn 到底怎么跑起来。说实话，这工具背后是挺复杂的 Bowtie2 比对加 marker 基因筛选流程，但命令行暴露给用户的接口相当清爽。我个人印象最深的是，第一次跑 metaphlan 命令时只用了 5 分钟就出了结果，当时心里还嘀咕：是不是漏了啥重要参数？后来发现，这工具的默认值确实很懂事。但真要把它用顺，你必须掌握三样东西：输入文件长什么样、一条命令怎么写、输出结果怎么看。下面我们一个一个拆。

输入文件格式：FASTQ 和 BAM，你选哪个？

MetaPhlAn 支持的原始输入其实就两大类：

  1. FASTQ 文件——最常见的形式。单端、双端都支持。
  2. BAM 文件——如果你手里已经有比对好的 BAM，可以直接喂给 MetaPhlAn 做 profiling。

我自己的经验是：如果是从头分析宏基因组，我通常直接给 FASTQ，让 MetaPhlAn 内部调用 Bowtie2 去比对。但如果你在做一个大型队列，已经用其他流程（比如 BWA 或 Kraken2 的中间产物）生成了 BAM，完全可以用 --input_type bam 选项跳过比对步骤。能省不少时间。

嗯，这里要注意一个易错点：如果你给的是 BAM，MetaPhlAn 会假定这个 BAM 已经是对着它的 marker 数据库比出来的。如果你给了个用其他参考基因组比出来的 BAM，那结果就是错的。我曾经被一个同事问为什么跑出来全是大肠杆菌，后来发现他的 BAM 是用人类基因组比的……

下表帮你快速对比两种情况：

输入类型 常用场景 命令行选项 我建议什么时候用
FASTQ（单端） 新测序数据，第一次分析 默认即可，无需额外参数 大多数首次分析的场景
FASTQ（双端） 双端测序，需要使用配对信息提高准确度 输入两个文件，用空格隔开 如果你有双端数据，用这个
BAM 已有比对好的 BAM，想跳过比对 --input_type bam 大型队列节省计算资源

FASTQ 双端输入的命令示例：

metaphlan sample_R1.fastq.gz sample_R2.fastq.gz \
  --bowtie2db /path/to/db_v31/ \
  --input_type fastq \
  -o profile.txt

注意，双端文件的顺序是 先 R1 再 R2。我见过有人颠倒了，结果 MetaPhlAn 直接报错……

BAM 输入就简单多了，一行搞定：

metaphlan sample.bam \
  --input_type bam \
  -o profile.txt
小技巧： 如果你对 BAM 的来源不放心，可以用 --bowtie2db 参数手动指定你的 marker 数据库路径，然后加一个 --ignore_viruses 等过滤选项，相当于双重校验。

运行 metaphlan 命令：一条命令走通全流程

MetaPhlAn 的命令行设计得相对直观。核心参数就三个：输入文件、数据库路径、输出文件。其他都是可选的优化项。

完整流程的典型命令模板：

metaphlan sample.fastq.gz \
  --bowtie2db /data/db_v31/ \
  --bowtie2out sample.bowtie2.bz2 \
  --nproc 8 \
  --input_type fastq \
  -o sample_profile.txt

我来解释一下这条命令背后的逻辑：

  • --bowtie2db 指向 MetaPhlAn 的 marker 数据库目录。这个目录包含 Bowtie2 的索引文件。如果没有下载，先去 官网 或使用 metaphlan_installer.py 下载。
  • --bowtie2out 是我个人非常推荐的参数。它会把 Bowtie2 的中间比对结果存为一个 .bz2 文件。为啥有用？如果第一次只跑 profiling，发现效果不错想加几个参数重新 run 分析时，可以直接拿这个 .bz2 文件重新跑，不需要重新比对。我记得有一次我调试参数整整迭代了 5 轮，如果没有这个中间文件，5 次比对下来够喝一壶的。
  • --nproc 设置 CPU 核心数。建议根据你的服务器情况调整，不要贪多。
  • -o 指定输出文件路径。没太大讲究，但建议用 .txt 作为后缀。

为什么要加 --bowtie2out？这个参数在大型项目里很常用，我们还可以用它来做一些高级操作，比如只保留特异性的 marker 比对结果。但那是后面章节的内容了。

还有一个小坑：输入文件如果是压缩的（.gz 或 .bz2），MetaPhlAn 能直接读取，不需要手动解压。但你用管道的时候要小心，比如把数据流接入标准输入时，必须加 --input_type fastq，否则会报错。

输出文件格式：profile 到底包含啥？

跑完之后，你会得到一个 .txt 文件。这个文件看似平淡无奇，但里面的每一行信息量都很大。标准 profile 文件的结构如下：

#SampleID       metaphlan
clade_name      NCBI_tax_id     relative_abundance     additional_species
k__Bacteria     2       100.0   0
k__Bacteria|p__Firmicutes  2|1239  45.2    0
k__Bacteria|p__Bacteroidetes       2|976   30.1    0
k__Bacteria|p__Firmicutes|c__Clostridia  2|1239|186801   12.3    0
s__Escherichia_coli    2|1224|562 5.6     1

列的含义很容易记住：

  • 第1列 clade_name：进化枝名称。从界到种，用 | 分隔。举个例子，k__Bacteria|p__Firmicutes|c__Clostridia 表示在门的层级上检出厚壁菌门，纲层级是梭菌纲。层级越深，信息越细。
  • 第2列 NCBI_tax_id：对应的 NCBI 分类 ID。可以用来和其他数据库做交叉引用。
  • 第3列 relative_abundance：相对丰度。单位是百分比，总和为 100%（如果只看界层级，但多层级时每层各自加总为 100%）。这是我关注最多的一个指标。
  • 第4列 additional_species：如果为 1，表示这个 clade 是由多个物种合并估计的。通常是菌株级别的一些处理。

我刚开始看这个文件时，有一个疑惑：为什么 p__Firmicutes 的丰度是 45.2%，但它的子类 c__Clostridia 只有 12.3%？其实这很简单，因为 c__Clostridia 只是 p__Firmicutes 下面的一个纲，还有别的纲（比如 Bacilli）加在一起才凑成 45.2%。也就是说，这个文件是按层级展开的。

另外，MetaPhlAn 默认只输出相对丰度大于 0.01% 的分类群。所以如果你发现某些物种没出现，可以先检查一下丰度是否低于阈值。

理解 .bowtie2out 文件与重跑策略

我之前提到过 --bowtie2out 参数。这个中间文件是压缩格式的 BZ2，专门给 MetaPhlAn 自己用的。如果后续你想调整参数（比如修改 --min_abundance 或 --avoid_disguise），可以不必再跑一遍 Bowtie2，直接用 --input_type bowtie2out 加载这个文件重新跑 profiling。

命令如下：

metaphlan sample.bowtie2.bz2 \
  --input_type bowtie2out \
  --nproc 1 \
  -o new_profile.txt

为什么这个很实用？我举两个真实案例：

  • 案例一：第一次跑完后发现我忘了加 --min_abundance 1.0，结果一堆低丰度的噪音物种都在里面。有了 .bowtie2out，只需要几十秒重新过滤一次，不需要重新比对。
  • 案例二：某个样本非常稀有，第一次 8 个线程跑了一小时。后来想试试不同的 --stat_avg 参数，直接用中间文件改，10 秒出结果。
我的建议： 除非你磁盘空间特别紧张，否则 永远 加上 --bowtie2out 参数。这种增量式的优化策略在你反复调试参数时能帮你节省大量时间。我曾见过一个团队跑 100 个样本的队列，每次调整参数都重新从头运行，白白浪费了上百个 CPU 核小时。

运行 MetaPhlAn 的典型流程

下面的 SVG 图画出了 MetaPhlAn 最核心的数据流：从 FASTQ 到 profile，以及通过 --bowtie2out 实现的重跑路径。

MetaPhlAn 核心数据流 MetaPhlAn 运行流程与重跑策略 原始 FASTQ 单端 / 双端 / BAM Bowtie2 比对 Marker 数据库 中间文件 sample.bowtie2.bz2 Profiling 分析 分类 & 丰度计算 重跑 (--input_type bowtie2out) Profile 文件 sample_profile.txt 重跑路径的优势 修改 --min_abundance、--avoid_disguise 等参数时，不需要重新比对 可直接从 .bowtie2out 中间文件开始，节省 80% 以上的计算时间

上图展示了 MetaPhlAn 分析的两个阶段：比对阶段（Bowtie2 + marker 数据库）和 分析阶段（Profiling）。虚线部分就是利用 --bowtie2out 文件实现的快速重跑路径。我个人觉得这个设计非常巧妙，它把计算密集型的比对和轻量级的 profiling 完全解耦了。

避坑指南：三个常见的跑错场景

我曾经踩过的坑：
  1. 双端文件顺序不对——MetaPhlAn 要求先 R1 后 R2，否则报错。加上 --input_type fastq 能明确告诉工具。
  2. 数据库路径写错——--bowtie2db 指向的是目录，不是具体文件。如果目录下没有 Bowtie2 索引（通常以 .1.bt2 结尾），MetaPhlAn 会提示找不到 index。
  3. BAM 的比对参考不是 marker 数据库——如果 BAM 是用其他参考比出来的，结果毫无意义。建议最开始时加 --verbose 参数查看日志里的比对来源信息。

快速参考：常用命令行参数清单

参数 作用 我的使用频率
--bowtie2db 指定 marker 数据库目录 每次必用
--bowtie2out 保存中间比对结果 极力推荐
--nproc CPU 线程数 常用
--input_type 指定输入类型（fastq/bam/bowtie2out） 取决于输入来源
--min_abundance 最小相对丰度阈值（百分比） 经常调优
--stat_avg 计算平均丰度的方法 较少改
-o 输出 profile 文件路径 每次必用

最后强调一句：如果你只是想快速看个大概，直接跑默认参数完全没问题。但一旦你发现结果不对劲，或者想优化某些指标，请一定记住 --bowtie2out 这个参数。我前面说了，这个参数能让你迭代的节奏快 10 倍。

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