MetaPhlAn 4 + HUMAnN 4 compatibility

Microbial community profiling HUMAnN
1

HUMAnN users - I’m making a quick pinned post about MetaPhlAn 4 + HUMAnN 4 compatibility since we’re seeing a lot of posts raising similar issues. We will follow up with more detailed information in the short term, and longer-term we’re also improving our version checking at install and runtime to avoid some of these issues going forward.

Key point 1: The current HUMAnN 4 release (v4.0.0.alpha.1) should work with MetaPhlAn 4 releases up to v4.1.1. It does not support v4.2+, which introduced an API change we still need to adapt to.

Key point 2: All versions of HUMAnN work with specific MetaPhlAn marker databases, since we require compatibility between MetaPhlAn’s markers + taxonomy and HUMAnN’s pangenomes + functional annotations. To use HUMAnN 4.0.0.alpha.1, you should be working with the mpa_vOct22_CHOCOPhlAnSGB_202403 MetaPhlAn marker database. If you install (or update to) a newer marker database it will break HUMAnN 4 compatibility.

If you’re working with older versions of HUMAnN (e.g. v3.9) in MetaPhlAn 4 compatibility mode, please see the release notes for your specific version of HUMAnN for the correct MetaPhlAn software and marker versions.

Apologies to those that have been struggling with HUMAnN installation as a result of the constraints above, and thanks for raising awareness here.

2 Likes
3

Hello,

I followed the instructions (HERE) to download and install Humann4 + Metaphlan4 database, and I am getting the following ERROR:

ERROR: The MetaPhlAn taxonomic profile provided does not contain the database version vOct22_CHOCOPhlAnSGB_202403 in any of its header lines.

I downloaded the Metaphlan database using: metaphlan --install --index mpa_vOct22_CHOCOPhlAnSGB_202403

Checking the download output, I noticed I got files from mpa_vOct22_CHOCOPhlAnSGB_202403 and mpa_vJan25_CHOCOPhlAnSGB_202503 versions. See them below:

mpa_latest; mpa_vJan25_CHOCOPhlAnSGB_202503.pkl mpa_vOct22_CHOCOPhlAnSGB_202403.2.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.rev.2.bt2l
mpa_vJan25_CHOCOPhlAnSGB_202503.1.bt2l mpa_vJan25_CHOCOPhlAnSGB_202503.rev.1.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.3.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403_VINFO.csv
mpa_vJan25_CHOCOPhlAnSGB_202503.2.bt2l mpa_vJan25_CHOCOPhlAnSGB_202503.rev.2.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.4.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403_VSG.fna
mpa_vJan25_CHOCOPhlAnSGB_202503.3.bt2l mpa_vJan25_CHOCOPhlAnSGB_202503_VINFO.csv mpa_vOct22_CHOCOPhlAnSGB_202403.pkl README.txt
mpa_vJan25_CHOCOPhlAnSGB_202503.4.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.1.bt2l mpa_vOct22_CHOCOPhlAnSGB_202403.rev.1.bt2l

Any advice?

Thanks

4

It’s because “metaphlan” is using the "latest” version of the database: I worked around the problem by changing the “latest” version file:

cd .conda/envs/humann/lib/python3.12/site-packages/metaphlan/metaphlan_databases
mv -i mpa_latest mpa_latest.dist
echo mpa_vOct22_CHOCOPhlAnSGB_202403 > mpa_latest

5

Hello, fellow bioBakers! :waving_hand:

Apologies if this isn’t the right thread for my question — please let me know if I should post it separately.

I’ve recently started working on metatranscriptomics with a focus on the gut microbiota, and I’m currently running HUMAnN v4.0.0.alpha.1 with MetaPhlAn v4.1.1 (11 Mar 2024).

However, I’ve noticed something odd: in my utility_mapping subdirectory, I have the files mpa_vJan21_CHOCOPhlAnSGB_202103.tsv and vOct22_SGB_mapping.tsv, even though my MetaPhlAn database is mpa_vOct22_CHOCOPhlAnSGB_202403.

Did I miss a step during installation or database setup?

Should I manually download the corresponding mpa_vOct22_CHOCOPhlAnSGB_202403.tsv file from somewhere else?

Any guidance or clarification would be greatly appreciated!

Best,
Fran :man_technologist: