1. 理解HUMAnN的数据库组成才知道要下载什么1.1 HUMAnN是干什么的做宏基因组分析的朋友对HUMAnN这个名字一定不陌生。它是目前做微生物群落功能分析最主流的工具之一输入的是宏基因组测序数据通常是双端FASTQ输出的是基因家族丰度表和代谢通路丰度表简单说就是把“样本里有哪些微生物”和“这些微生物在干什么”这两层信息一次搞定。HUMAnN的全称是HMP Unified Metabolic Analysis Network最早由哈佛大学Curtis Huttenhower团队开发现在已经是3.x版本在Nature Biotechnology等期刊上有配套的方法学文章。它和MetaPhlAn配合使用MetaPhlAn先用标记基因鉴定物种组成HUMAnN再基于物种组成把测序 reads 比对到参考物种的泛基因组上从而计算基因家族和通路的丰度。这个流程设计得很巧妙但代价就是它依赖的数据库非常大、非常多而且分散托管在多个境外服务器上。我见过很多刚接触宏基因组的同学HUMAnN装好了conda环境也建好了结果卡在数据库下载这一步一卡就是好几天。这不是技术能力问题纯粹是网络环境和数据库体积造成的现实困难。所以围绕这个事写一篇完整的实操记录帮大家把数据库部署这条路走通我觉得比重复那些官方文档更有价值。1.2 三件套ChocoPhlAn、UniRef、MetaPhlAnHUMAnN 3.x运行时会用到三类数据库缺一不可。第一类是核苷酸数据库也就是ChocoPhlAn。这是一个大规模的全基因组泛基因组数据库里面存储了几千个微生物物种的参考基因组序列HUMAnN会把清洁后的reads先用Bowtie2比对到ChocoPhlAn上快速确定哪些基因组可能出现在样本里。ChocoPhlAn分为full和democratic两个版本full版本包含所有物种基因组解压后体积轻松超过20GBdemocratic版本只保留质量足够高的基因组体积小很多适合快速测试。第二类是蛋白数据库默认是UniRef。UniRef是UniProt数据库按序列相似度聚类后生成的非冗余蛋白数据库HUMAnN把ChocoPhlAn比对后未匹配上的reads翻译成蛋白序列再用DIAMOND比对到UniRef上做敏感搜索。UniRef有UniRef90和UniRef50两个常用档次UniRef90更完整但体积大UniRef50是精简版速度更快。DIAMOND索引构建完的UniRef90数据库体积非常可观所以很多人会直接选用UniRef50。第三类是MetaPhlAn的标记基因数据库。HUMAnN计算物种丰度时依赖MetaPhlAn的结果因此这台机器上必须有一份MetaPhlAn数据库。它体积不大百兆级别新版本可能到几个GB但版本必须和环境中安装的MetaPhlAn软件匹配否则会直接报错。这三类数据库搞清楚了你就明白为什么网上的求助帖总在问“下载哪个”“放哪个目录”了。因为HUMAnN对数据库目录结构有严格要求放错位置它不会自动帮你找。1.3 官方下载机制为什么在国内经常失败HUMAnN官方推荐用humann_databases命令来下载数据库这个命令本身很好用可以指定数据库类型、版本和安装目录它会自动处理下载和解压。但问题在于它默认从国外服务器拉取数据而且服务器分布在不同地方ChocoPhlAn历史版本托管在SourceForge新版本和UniRef相关数据在Zenodo上MetaPhlAn数据库又在另一个地方。这些服务器在国内的直连速度非常不稳定。我实测过很多次小文件还能勉强下载一旦到了几个GB的大文件阶段经常是下载了百分之六七十就断掉。humann_databases的断点续传能力很弱一旦中断可能要从头再来。更让人抓狂的是有时候表面看下载完成了解压时才发现压缩包损坏校验码对不上又得重新下载。这时候一个稳定快速的国内备份下载源就显得特别重要。刘永鑫博士在GitHub上维护的HUMAnN数据库备份仓库解决的就是这个问题他把常用的HUMAnN数据库压缩包上传到了国内可快速访问的存储位置并在仓库里整理了下载方式、校验信息和安装说明。我做宏基因组这几年至少帮实验室和合作课题组部署过十几次HUMAnN环境每次遇到数据库下载问题最后都是用这个备份源搞定的。下面把我的完整操作流程写出来。2. 部署前准备环境安装与空间确认2.1 用conda安装HUMAnN数据库只是“弹药”HUMAnN本体得先装好。我习惯用conda管理生物信息软件特别是HUMAnN这种依赖大量Perl模块和外部工具的程序conda能一次性把依赖关系理清楚。建议用mamba代替conda速度会快很多。# 如果还没有mamba先装一下 conda install -n base -c conda-forge mamba -y # 创建独立环境避免污染base mamba create -n humann -c bioconda -c conda-forge humann -y # 激活环境 conda activate humann # 验证安装 humann --version国内用户创建环境时建议先在用户目录下配置好.condarc把默认channel换成清华或中科大镜像。这一步虽然不是必须的但能大幅缩短依赖解析和下载时间。注意HUMAnN环境里会自带MetaPhlAn安装时要注意版本对应关系HUMAnN 3.6以后的版本通常搭配MetaPhlAn 4使用HUMAnN 3.5以前则用MetaPhlAn 3。用metaphlan --version检查一下即可。安装完成后不要急着下载数据库。先跑一条humann_test看看核心功能是否正常这个命令会生成一套模拟测试数据并在临时目录里跑一遍完整流程能提前暴露很多环境问题。我遇到过有人在数据库上花了两天时间最后发现是bowtie2和HUMAnN版本不兼容白白浪费了时间。2.2 磁盘空间与下载工具数据库部署前先检查磁盘空间。很多人忽略这一步等下载到一半才发现空间不足然后到处删文件非常狼狈。用df -h看一眼目标分区剩余空间我建议至少预留80GB再开始部署完整的ChocoPhlAn和UniRef90组合。如果只跑UniRef50配合ChocoPhlAn的democratic版本30GB也够用。# 查看磁盘空间 df -h # 查看当前目录占用 du -sh /path/to/your/data下载工具方面我强烈推荐用aria2c替代wget。原因很简单aria2c支持多线程下载和断点续传对几个GB的大文件非常友好。国内网络环境再怎么波动至少断线后不用从头再来。# 安装aria2 mamba install -c conda-forge aria2 -y如果备份源提供的是网盘链接也可以用网盘客户端下载速度通常也不错。关键是要把压缩包完整下下来不要开着浏览器下载页面就去干别的大文件下载中途浏览器崩溃的情况太多了。2.3 从哪里获取备份源备份源的获取方式其实就是打开GitHub搜索刘永鑫博士YongxinLiu在仓库列表里找到HUMAnN数据库备份相关的仓库。仓库的README里通常会把每一个数据库压缩包、对应的原始版本、MD5校验值、推荐下载方式都列清楚。这里有个细节要说一下刘永鑫博士的备份仓库并不是把数据库文件直接放在GitHub上因为GitHub单个文件有100MB限制几个GB的数据库没法直接托管。他的方式是提供国内可访问的网盘链接或者在仓库的Release页面挂上百度网盘等下载地址也整理了一份下载清单方便按需取用。我之前下载的时候直接在命令行用wget配合aria2拉下来的速度稳定在几MB每秒比国外源不知道快到哪里去了。拿到下载地址后要确认版本信息。备份仓库一般会标注数据库对应的版本号和适用HUMAnN版本范围比如ChocoPhlAn v201901b 是HUMAnN 3.x的经典搭配。对照自己环境里的humann --version选择合适的版本不要一味求新。3. 备份源下载与数据库放置全流程3.1 下载前先梳理目标目录结构HUMAnN对数据库目录有一套约定俗成的规范。默认情况下它会在用户主目录下找humann_databases文件夹但你也可以用参数指定其他位置。我建议在项目数据盘建一个统一的数据库目录比如/data/db/humann_databases这样重装系统、迁移服务器都不会丢。标准的目录结构长这样humann_databases/ ├── chocophlan/ │ └── chocophlan_plus_democratic_v201901b/ # 解压后的目录 ├── uniref/ │ └── uniref90_201901b/ # 解压后的目录 └── metaphlan_database/ └── mpa_vJan21_CHOCOPhlAnSGB_202103/ # MetaPhlAn 4数据库注意HUMAnN查找数据库时会去上一级目录扫描识别前缀是否为chocophlan、uniref、metaphlan然后在内部再找具体版本目录。所以外层目录名一定要用chocophlan、uniref、metaphlan_database不能写成ChocoPhlAn或者随意起名。这个坑我踩过一次大小写不对直接导致HUMAnN识别不到数据库。3.2 下载与校验实操拿到备份源的下载链接后用aria2c拉取。比如下载ChocoPhlAn全库压缩包cd /data/db/ # 假设下载链接是https://example.com/chocophlan.tar.gz aria2c -x 8 -s 8 -d /data/db/ https://example.com/chocophlan.tar.gz参数含义说一下-x 8表示每个服务器最多开8个连接-s 8表示拆成8个分片并发下载对提升单线程受限的场景很有帮助。如果下载地址是网盘链接可能需要先手动在浏览器里获取直链再扔给aria2c。下载完成后一定要做两件事一是和备份源提供的MD5或SHA256校验值比对确认文件完整二是用file或tar -tzf检查压缩包是否是有效的gzip归档。常见的问题是某些网盘会在下载失败时返回一个HTML错误页面但你给文件命名成了.tar.gz看起来像压缩包实际打开全是HTML代码解压时怎么都报错。# 计算MD5 md5sum chocophlan.tar.gz # 检查压缩包完整性 tar -tzf chocophlan.tar.gz | head3.3 解压放置目录规范校验没问题后开始解压。我这里以ChocoPhlAn和UniRef90为例mkdir -p /data/db/humann_databases/chocophlan mkdir -p /data/db/humann_databases/uniref mkdir -p /data/db/humann_databases/metaphlan_database # 解压ChocoPhlAn注意解压到哪里 tar -xzf chocophlan.tar.gz -C /data/db/humann_databases/chocophlan/ # 解压UniRef tar -xzf uniref90.tar.gz -C /data/db/humann_databases/uniref/ # 解压MetaPhlAn数据库 tar -xzf metaphlan_database.tar.gz -C /data/db/humann_databases/metaphlan_database/解压后检查一下目录名称是否和HUMAnN预期匹配。比如ChocoPhlAn解压后通常会得到一个chocophlan_plus_*开头的文件夹UniRef解压后可能是uniref90_201901b*MetaPhlAn数据库解压后是mpa_v*开头的文件夹。这些目录名里的版本号HUMAnN在启动时会通过--nucleotide-database和--protein-database参数去扫描目录名中的版本标识不会造成识别问题但前缀必须正确。有一点要特别提醒不要手动修改这些版本目录的名字。有的同学想让目录名简洁一点把chocophlan_plus_democratic_v201901b改成了v201901b结果HUMAnN识别的时候根据前缀判断不出这是ChocoPhlAn数据库直接报错。官方和备份源给的目录名是经过设计的没必要动。3.4 验证数据库是否被正确识别数据库放好以后怎么知道HUMAnN认不认最直接的方法是运行HUMAnN的数据库检查命令。HUMAnN 3.x提供了humann_databases工具虽然它是用来下载数据库的但它也内置了数据库定位逻辑。实测更有效的方法是直接跑一次humann_test或者用真实样本跑一个极小测试。humann_test是官方自带的冒烟测试会在临时目录自动生成数据并分析如果数据库路径配置正确它会在日志中打印出实际使用的数据库路径。humann_test如果日志中出现类似ChocoPhlAn database: /data/db/humann_databases/chocophlan/chocophlan_plus_democratic_v201901b这样的输出说明路径没问题。如果显示找不到数据库多半是环境变量或者运行参数没对上。还有一种常见情况是MetaPhlAn数据库的问题。HUMAnN运行时会调用MetaPhlAn做物种注释而MetaPhlAn默认会找它自己安装目录下的数据库或者通过--metaphlan-options--bowtie2db /path/to/mpa_db指定。如果你在备份源里下载了MetaPhlAn数据库安装后可以直接通过环境变量或者参数指过去# 设置MetaPhlAn数据库路径环境变量 export METAPHLAN_DB_DIR/data/db/humann_databases/metaphlan_database或者更稳妥一点在运行HUMAnN时显式指定humann --input sample.fastq.gz \ --output output_dir \ --nucleotide-database /data/db/humann_databases/chocophlan \ --protein-database /data/db/humann_databases/uniref \ --metaphlan-options--bowtie2db /data/db/humann_databases/metaphlan_database到这里数据库部署就算完成了。下面说说第一次完整分析的实操过程。4. 跑通第一次HUMAnN分析4.1 用小测试数据验证全链路我强烈建议在跑真实数据前先用humann_test做一次全链路验证。这个命令会生成模拟的paired-end reads然后调用外壳程序完成质量过滤、物种注释、比对、翻译、功能注释、丰度计算这一整套流程并自动检查是否正常运行。conda activate humann humann_test第一次跑的时候不要急日志会逐条显示每步调用的工具和参数。如果数据库目录设置有问题通常会在这个阶段暴露出来。看到所有SUCCESS标识后再用自己的一对小样本正式跑一下确认输出文件符合预期就可以放心提交大批量任务了。我曾经在给一台新服务器部署环境时跳过humann_test直接跑正式数据结果半夜任务中断第二天排查才发现是MetaPhlAn数据库版本和HUMAnN自带的MetaPhlAn不相容。多做一步验证能省下至少一整天的失眠时间。4.2 正式分析常用参数HUMAnN最核心的参数有三个输入文件、输出目录、数据库路径。实际使用中我通常会加以下配置humann \ --input reads_1.fastq.gz \ --output humann_out \ --threads 16 \ --nucleotide-database /data/db/humann_databases/chocophlan \ --protein-database /data/db/humann_databases/uniref \ --metaphlan-options--bowtie2db /data/db/humann_databases/metaphlan_database \ --remove-temp-output其中--threads控制线程数--remove-temp-output可以在运行结束后删除中间临时文件释放磁盘空间。HUMAnN运行过程中会产生大量中间文件特别是比对产生的sam/bam文件体积甚至比原始数据还大不加这个参数很容易把数据盘塞满。输入文件可以是双端文件HUMAnN支持直接传入两个fastq.gz文件名它会自动识别成双端数据。官方也推荐输入未经过拼接的清洁reads质量过滤建议在前面的流程里用fastp或Trimmomatic先做掉HUMAnN内部虽然也能过滤但把脏活累活留给专门的工具更高效。4.3 数据库选择策略数据库不是越大越好关键看你的研究需求。如果你的样本来自肠道菌群或土壤物种多样性高建议用ChocoPhlAn全库加UniRef90宁可慢一点也要减少漏检。如果只是做快速筛选、大批量样本的功能概览用ChocoPhlAn的democratic版本加UniRef50就足够分析速度快很多对内存的要求也低。内存方面我自己跑16线程的HUMAnNChocoPhlAn全库加UniRef90峰值内存经常在30GB到50GB之间。如果服务器内存只有16GB建议换用UniRef50并把线程数降到8否则容易OOM中断。备份源提供了多个版本的压缩包下载前先想清楚自己的硬件条件再选比下载完发现跑不动要好得多。如果只做物种组成分析其实可以不着急下载UniRef数据库。HUMAnN在物种注释阶段只依赖MetaPhlAn数据库功能注释阶段才需要UniRef。备份源把数据库拆分成独立压缩包就是为了方便按需下载。用不上可以先不下需要时再补装省硬盘也省时间。5. 常见问题与排错手册5.1 高频问题速查表下面这张表是我在实际部署和帮助别人解决问题时遇到频率最高的一批问题附带原因和解决方案。现象根本原因解决办法下载到一半断掉境外源不稳定、无断点续传换用备份源本地用aria2c下载解压提示gzip文件损坏下载不完整或网盘返回错误页重新下载下完先md5sum校验提示找不到chocophlan数据库目录名前缀错了或路径没传对检查外层目录名必须是chocophlan提示找不到uniref数据库解压目录放了多余层级确认uniref压缩包直接解压到uniref/下MetaPhlAn版本不对HUMAnN内置MetaPhlAn和数据库不匹配用metaphlan --version确认下载匹配版本运行中途OOM数据库太大/线程太多换UniRef50减少threads内存加swap磁盘写满中间文件未清理加--remove-temp-output及时清理Humann时报Perl模块缺失conda环境不完整重新安装humann确保环境无报错输入文件识别成单端文件命名不规范双端文件要成对命名HUMAnN自动识别有时会失败5.2 最容易被忽略的几个坑第一个坑是压缩包没解压直接跑。有人把压缩包扔在目录里就运行HUMAnNHUMAnN扫描数据库时会去找解压后的文件夹找不到就用默认的结果跑到一半报错。所以数据库放到位后先ls看一眼确保里面是文件夹而不是.tar.gz文件。第二个坑是下载了“错误版本”的MetaPhlAn数据库。MetaPhlAn v31和v4数据库格式不一样HUMAnN调用MetaPhlAn的方式也有差异。如果你备份源里选的是MetaPhlAn 4数据库但conda环境里给你装的是MetaPhlAn 3.x版本运行时会直接失败。解决办法是明确指定MetaPhlAn的数据库路径版本或者干脆用conda把metaphlan版本固定为和备份源对应的版本。第三个坑是把数据库放在/root或者其他没有权限读取的目录。很多生信流程会用普通用户跑如果你用sudo解压数据库到root家目录换用户后没有读取权限HUMAnN就会报权限错误。建议统一把数据库放在/data/db这种公共数据分区并给目录加上普通用户可读权限。第四个坑是镜像下载时连接数过多被限速。aria2c的-x参数不是越大越好有时候你开16个连接下载反而触发网盘限速速度还不如4个连接。实测国内网盘直链用4到8个连接比较稳具体可以自己试一两个连接数对比。5.3 备份源使用心得备份源帮我们解决了下载慢的问题但使用时有几个细节值得注意。第一备份源仓库里的数据库版本是定时更新的不是实时同步官方最新版本。如果你需要最新的ChocoPhlAn版本先看看备份源有没有同步没有的话也能先用官方源慢慢拉或者找作者反馈。对绝大多数分析来说v201901b及以上版本已经够用不用执着于最新。第二下载备份源的数据库时最好把MD5校验值一起保存下来。数据库文件太大一旦在传输或存储过程中损坏跑分析时往往不会立刻报错而是中途出现莫名其妙的比对失败。提前校验能排除这个变量。第三如果你想在实验室多台服务器上部署不需要每台都下载一遍。在一台机器上下载、校验、解压然后用rsync同步到其他节点rsync -avP /data/db/humann_databases/ userserver2:/data/db/humann_databases/内网传输速度一般能到几百MB每秒比重新下载快一两个量级。第四把HUMAnN和数据库路径写进你的流程文档、README或者批处理脚本模板里。很多项目过几个月再回来看当时配置的路径早就忘了留下记录能省很多重新排查的时间。我一般会在项目的config.yaml或批处理脚本头部统一维护这些路径变量避免散落在命令行里。6. 写在最后的一些经验数据库部署这件事看起来简单实际坑不少。我自己第一次部署HUMAnN时光在数据库下载上就折腾了将近三天当时还用的是官方源断断续续下载的压缩包解压失败了好几次。后来接触到刘永鑫博士的备份源整个流程从一个星期缩短到半小时确实帮了大忙。结合这几年的使用经验我觉得最值得分享的是一条工作习惯所有大型公共数据库首次配置完成后顺手在本地备一份原始压缩包。放移动硬盘也好、内网存储也好这不占多少空间却能让你在未来某一天重装服务器、迁移环境时不用重新面对下载难题。数据库压缩包就是你的“离线安装光盘”有备无患。另外如果你们实验室有多个成员经常做宏基因组分析可以考虑统一规划一个公共数据库目录维护一份简单的部署文档。我一个人维护过好几台服务器的生信环境感触最深的就是环境配置最大的成本不是装软件而是踩坑和排查。把这次踩坑的经验写成文档后来的人照着做半小时就能部署完这比什么技术分享都有价值。