📚 课程目录第4章数据库下载与配置

数据库下载与配置：获取Bowtie2索引、markers数据库，并合理配置环境变量

好，到了这一步，咱们已经搞定软件安装。但MetaPhlAn真正的“主力”其实不是那个python包，而是背后那两个大家伙——Bowtie2索引文件和markers数据库。我当初第一次跑MetaPhlAn时，以为装好软件就能直接跑，结果报了一堆找不到数据库的错误，那叫一个狼狈。简单说：数据库没配好，MetaPhlAn就像没装子弹的枪，干不了活。

4.1 数据库到底长什么样？

MetaPhlAn的数据库其实包含两部分：

Bowtie2索引：用来把测序reads快速比对到参考基因组上的“地图”。MetaPhlAn用的是特制的、只包含标记基因（marker genes）的索引。
markers数据库：一个序列文件，里面记录了每个物种有哪些独特的标记基因。MetaPhlAn就是靠这个来判断丰度。

这两者必须配套。我记得有次不小心混用了不同版本的索引和markers，结果比对出来的物种全是乱码。嗯，版本号一定要对应。

Tip： 官方提供了预构建好的数据库，解压即用。推荐直接用 metaphlan –install 来下载，别自己去手动拼文件，省心。

4.2 下载方式：自动 vs 手动

我个人习惯用自动安装。一条命令搞定：

metaphlan --install --bowtie2db /path/to/db

这命令会从MetaPhlAn的官方服务器拉最新的数据库包。它自己解压、放到你指定的目录。如果你网不好，或者想用内网部署，那只好手动下载了。

手动下载地址（以v3.0为例，最新版请去官网看）：

wget https://zenodo.org/record/3981518/files/mpa_v30_CHOCOPhlAn_201901_markers.fasta.bz2
wget https://zenodo.org/record/3981518/files/mpa_v30_CHOCOPhlAn_201901_bowtie2db.tar.bz2

下载后解压：

bunzip2 mpa_v30_CHOCOPhlAn_201901_markers.fasta.bz2
tar -xjf mpa_v30_CHOCOPhlAn_201901_bowtie2db.tar.bz2

注意那个tar包解出来是一组文件，它们构成Bowtie2索引，文件后缀可能是.1.bt2、.2.bt2、.3.bt2等等。

4.3 配置环境变量：告别路径噩梦

下载完只是第一步。你得告诉MetaPhlAn数据库在哪。环境变量有三个关键：

环境变量	作用	示例（设置）
`BOWTIE2_INDEXES`	Bowtie2寻找索引的默认路径	`export BOWTIE2_INDEXES=/data/db/bowtie2/`
`mpa_dir`	MetaPhlAn寻找markers数据库的路径（旧版本常用）	`export mpa_dir=/data/db/metaphlan/`
`METAPHLAN_DB_LOCATION`	新版推荐写法，直接指定数据库根目录	`export METAPHLAN_DB_LOCATION=/data/db/metaphlan/`

我个人建议统一用 METAPHLAN_DB_LOCATION，因为它最清晰。把这个写到你的 ~/.bashrc 或 ~/.zshrc 里，每次登录自动加载：

export METAPHLAN_DB_LOCATION=/home/user/databases/metaphlan

然后重载配置：

source ~/.bashrc

为什么要这么干？你想想看，如果你每次跑分析都手动敲一堆路径，不仅麻烦，还容易写错。尤其做批量样本的时候，一个路径写错，整个队列全崩。我曾经就是没设置这个变量，结果在一个集群上跑了30个样本的作业，全部因为找不到数据库报错，白白浪费了一天机时。

重点： 环境变量的值是目录路径，不是具体文件名。MetaPhlAn会自动去那个目录里找 mpa_v30_CHOCOPhlAn_201901_* 这样的文件。不要把路径写到了文件级别。

4.4 验证配置：跑一个空测试

配好了，怎么确认没问题？我的做法是跑一个最小的测试：

metaphlan --bowtie2db $METAPHLAN_DB_LOCATION --test

这个--test参数会用一个内置的小样例快速跑一遍。如果输出类似下面这样，说明数据库找到了：

Sample: test_sample.fastq.gz
Species: Bacteroides vulgatus
Relative abundance: 12.34%

如果报错说某个索引文件缺失，那八成是下载不完整或者路径指错了。嗯，先检查文件夹里到底有哪些文件：

ls -lh $METAPHLAN_DB_LOCATION

正常应该看到一堆 .bt2 结尾的文件，以及一个 .fasta 的markers文件。

⚠ 常见坑：

版本不匹配： bowtie2索引和markers数据库分别来自不同版本，导致运行崩溃。解决方案：一起从同一官网链接下载。
磁盘空间不足： 数据库解压后约 3~8 GB（看版本），临时目录不够也会报错。我用 df -h 先扫一眼。
软链接带错： 有时候为了节省空间，有人把数据库目录做成软链接，但MetaPhlAn读取时可能会follow到错误目标。我建议直接实在的目录，别搞符号链接。

4.5 数据库下载与配置流程图

下面这张SVG图帮你把流程串起来，一目了然：

4.6 多版本管理技巧

做研究时，你不可能只用一套数据库。比如旧项目需要v2.0的结果，新项目用v3.0。怎么切换？

databases/
├── metaphlan_v20/
├── metaphlan_v30/
└── metaphlan_v40/

写个简单的shell函数，方便切换：

function use_metaphlan_v20() {
    export METAPHLAN_DB_LOCATION=$HOME/databases/metaphlan_v20
    echo "Switched to MetaPhlAn v2.0 database"
}
function use_metaphlan_v30() {
    export METAPHLAN_DB_LOCATION=$HOME/databases/metaphlan_v30
    echo "Switched to MetaPhlAn v3.0 database"
}

这样你在终端里敲 use_metaphlan_v30，环境就切好了。我经常这么做，尤其是在复盘旧数据的时候，省去重复下载的麻烦。

效率贴士： 如果你在内网环境（没有外网），可以找个有网的机器把数据库下好，打成tar包传到内网。解压后配好环境变量，效果一样。注意tar包传输时用 rsync -P 避免断传，我吃过亏：一个8GB的包传了一半断掉，重来花了半小时。

4.7 总结本章关键点

数据库由Bowtie2索引 + markers序列组成，必须配套。
推荐 metaphlan –install 自动下载，省心。
设置 METAPHLAN_DB_LOCATION 环境变量，别偷懒。
用 –test 快速验证配置是否正确。
多版本管理靠切换环境变量目录。

配好数据库，MetaPhlAn才算真正装好。下一部分我们就要开始实战分析了，数据库是弹药，千万别在这步省事。嗯，我把数据库目录写在 ~/.bashrc 里后，再也没丢过样本。