📚 课程目录第2章 MetaPhlAn的安装与配置

2. MetaPhlAn的安装与配置：环境依赖与数据库获取

这部分内容看起来是简单的安装步骤，但我在项目里踩过的坑还真不少。很多人觉得装个工具不就是 pip install 嘛，结果一跑起来全是报错。MetaPhlAn 的安装不难，但有几个细节处理不好，后面会让你抓狂。

2.1 环境依赖：先搞清楚你要面对什么

MetaPhlAn 4 的核心依赖其实不多，但版本卡得比较死。我个人习惯用 Conda 环境来隔离，免得和系统里的 Python 包打架。

依赖项	版本要求	备注
Python	≥ 3.7	推荐 3.9 或 3.10
biopython	≥ 1.78	序列处理必备
numpy	≥ 1.20	科学计算
pandas	≥ 1.3	结果表格处理
h5py	≥ 3.0	数据库 HDF5 格式读取
requests	≥ 2.25	数据库下载

注意了：千万别用 Python 2.7，MetaPhlAn 4 已经完全不支持了。我曾经在一个老旧集群上忘了检查默认 Python 版本，结果折腾了半天才发现问题。

2.2 安装方法：两条路选一条

安装 MetaPhlAn 主要有两个路子。我建议新手直接走 Bioconda，省心。但如果你在受限环境里干活，源码安装也是必须掌握的本事。

2.2.1 用 Bioconda 安装（推荐）

这个方法最干净。创建一个新环境，一句命令搞定。我在项目中遇到过多次因为依赖冲突导致安装失败的情况，用 Conda 环境隔离就没再出过类似问题。

conda create -n metaphlan_env python=3.9
conda activate metaphlan_env
conda install -c bioconda metaphlan

装完后验证一下版本：

metaphlan --version

如果看到类似 Metaphlan version 4.0.x 的输出，说明安装成功了。

2.2.2 从源码安装

有时你需要在断网环境、或者想用开发版新功能，那就得走源码路径。说白了就是 git clone 后用 pip 安装。

git clone https://github.com/biobakery/MetaPhlAn.git
cd MetaPhlAn
pip install -e .

我的小建议：加上 -e 参数（可编辑模式），这样你能随时修改代码，方便调试。特别是做参数敏感性分析时，可能需要调整内部参数。

2.3 数据库获取：这一步最容易被忽视

MetaPhlAn 的核心是其参考数据库。没有数据库，工具就是空壳。数据库大约 2-3 GB，下载需要一点耐心。

2.3.1 数据库结构长啥样

数据库里存放的是物种标记基因的 bowtie2 索引文件。MetaPhlAn 4 的数据库版本是 mp4_vJun23（2023年6月版）。你想想看，几万个微生物物种，每个物种有上百个标记基因，全部压缩成索引文件，这工作量不小。

# 数据库默认路径（安装后自动创建的）
~/.conda/envs/metaphlan_env/lib/python3.9/site-packages/metaphlan/metaphlan_databases/

# 主要文件
mpa_vJun23_CHOCOPhlAnSGB_202307.fna      # 标记基因序列
mpa_vJun23_CHOCOPhlAnSGB_202307.1.bt2    # bowtie2 索引（共6个文件）
mpa_vJun23_CHOCOPhlAnSGB_202307.md5      # MD5 校验文件

2.3.2 用内置工具下载

MetaPhlAn 提供了一个专门的数据库管理脚本。我个人习惯手动指定一个存放位置，避免默认路径权限问题。

# 查看可用的数据库版本
metaphlan --database --list

# 下载最新版数据库
metaphlan --database --download mp4_vJun23 --database-dir /data/metaphlan_db/

下载过程会比较慢，尤其在国内网络环境下。我建议用代理或者提前下载好压缩包手动解压。

2.3.3 手动下载与配置（备用方案）

如果自动下载失败了怎么办？我曾经遇到过学校集群无法访问外网的情况，只能曲线救国。

# 从官方 FTP 获取
# 在自己电脑上下载好，然后 scp 到服务器
wget https://huttenhower.sph.harvard.edu/metaphlan_databases/mpa_vJun23_CHOCOPhlAnSGB_202307.tar.gz

# 上传到服务器后解压
tar -xzf mpa_vJun23_CHOCOPhlAnSGB_202307.tar.gz -C /data/metaphlan_db/

解压后需要让 MetaPhlAn 知道数据库路径。设个环境变量就行：

export METAPHLAN_DB_DIR=/data/metaphlan_db/

最好把它写到 ~/.bashrc 里，省得每次运行都要再设一遍。

2.4 安装验证：跑一个简单测试

装好了总得试试能不能用。我习惯用一个很小的测试数据集快速验证，而不是上来就跑真实样本。

# MetaPhlAn 自带测试数据
metaphlan --test

# 或者手动测试
wget https://huttenhower.sph.harvard.edu/metaphlan_databases/test/SRS014459-Stool.fasta.gz
gunzip SRS014459-Stool.fasta.gz
metaphlan SRS014459-Stool.fasta --input_type fasta --output_file test_result.txt

成功标志：输出文件里能看到物种分类表格，第一行是 #clade_name，后面跟着各分类级别的相对丰度值。如果报了各种缺失库的错误，八成是依赖没装全。

2.5 整体安装流程

我画了张流程图，把整个安装和配置过程串起来。你跟着走一遍，基本不会出大问题。

2.6 常见坑与避坑指南

数据库下载超时：我经常遇到，尤其在下午网络高峰期。解决方法就是断点续传，或者用 FTP 客户端工具先下载到本地再上传。
bowtie2 索引加载失败：检查数据库是否完整。看看对应目录下有没有 .bt2 文件，少一个都不行。
Permission denied 错误：自己建个专门放数据库的目录，设好读写权限，别放系统路径里。
版本不匹配：MetaPhlAn 版本和数据库版本要匹配。比如 MetaPhlAn 4.0.x 只能用 mp4 开头的数据库，用老的 v3 数据库会报错。

实用一招：在运行分析前，先跑一句 metaphlan --database --list 看看当前环境里数据库是否已正确加载。这步被我写进了所有分析脚本的开头，就像安全气囊一样——平时不起眼，关键时候能救命。

安装这一步其实决定了后续所有分析的成败。你想想看，数据库没配置好就跑敏感性分析，结果全是错的还找不到原因，那才叫浪费时间。做好这一步，后面就能安心做参数调优了。