Sovereign 8s.is mirror of standardgalactic/MetaCAT
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-09-01 17:49:54 +08:00
Datasets v1.0.5 2026-08-01 01:07:17 +08:00
Dependencies v1.0.5 2026-08-01 01:07:17 +08:00
Documentation v1.0.6 2026-08-07 16:02:35 +08:00
Examples v1.0.5 2026-08-01 01:07:17 +08:00
IndexBam v1.0.5 2026-08-01 01:07:17 +08:00
MetaCAT v1.0.6 2026-08-07 16:02:35 +08:00
.gitignore v1.0.5 2026-08-01 01:07:17 +08:00
LICENSE v1.0.5 2026-08-01 01:07:17 +08:00
README.md Update README.md 2026-09-01 17:49:54 +08:00

MetaCAT

Metagenome Clustering and Association Tool.

Citation

If you use MetaCAT in your research, please cite:

Liu, CC., Dong, SS., Guo, J. et al. MetaCAT enables reconstruction of high-quality microbial genomes and their association with host traits from metagenomic data. Nat Microbiol (2026). https://doi.org/10.1038/s41564-026-02472-7

Dependencies

CheckM2 CuPy FragGeneScan GTDB-Tk Hmmer Mash FastANI skani

Dependencies used for clutering sequneces

FragGeneScan, hmmpress and hmmsearch (from the Hmmer tool) are used in the seed command of MetaCAT.

MetaCAT uses built-in versions of FragGeneScan, hmmpress, and hmmsearch by default,
if you are running on a supported platform (i.e., x86_64 Linux or arm macOS).

Otherwise, you need to compile them manually and ensure they are callable by MetaCAT.

You can specify their paths using --fraggenescan, --hmmpress and --hmmsearch options.

Note that the built-in binaries are only accessible to the seed command and cannot be called by external programs.

Dependencies used for estimating cluster quality

CheckM2 is used in the checkm2 command of MetaCAT.

By default, MetaCAT uses the checkm2 from the environment.

You can specify its path using the --checkm2 option.

CheckM2 and its database must be installed manually.

For more details, please visit the CheckM2 repository.

Dependencies used for classifying clusters

GTDB-Tk is used in the gtdbtk command of MetaCAT.

By default, MetaCAT uses gtdbtk from the environment.

You can specify its path using the --gtdbtk option.

GTDB-Tk and its database must be installed manually.

For more details, please visit the GTDB-Tk repository.

Dependencies used for selecting representatives

Mash or FastANI or Skani is used in the representative command of MetaCAT.

By default, MetaCAT uses the built-in Mash binary
if you are running on a supported platform (i.e., x86_64 Linux or arm macOS).

Otherwise, you need to compile Mash manually and ensure it is callable by MetaCAT.

You can specify its path using the --mash option.

Note that the built-in binaries are only accessible to the representative command and cannot be called by external programs.

Additionally, we provide FastANI and Skani as alternatives (--engine fastANI|skani) in representative command.

To use FastANI or Skani, you need to compile it manually.

MetaCAT uses FastANI or Skani from the environment by default.

You can specify its path using the --fastani or --skani option.

Install MetaCAT and dependencies

If only the core modules of MetaCAT (e.g., clustering) are required, installing MetaCAT alone is sufficient.

CheckM2, GTDB-Tk, and their dependencies may require specific Python versions.

The following installation includes MetaCAT and all required dependencies, and has been tested with Python 3.12.

  • MetaCAT will be installed in ./metacat
  • CheckM2 will be installed in ./checkm2
  • GTDB-Tk will be installed in ./gtdbtk
  • Binary dependencies (CheckM2 & GTDB-Tk) will be installed in ./metacat/bin

You may adjust the installation paths as needed.

Install MetaCAT

python3 -m venv metacat
source metacat/bin/activate
pip3 install https://github.com/liu-congcong/MetaCAT/releases/download/v1.0.6/metacat-1.0.6-py3-none-any.whl
deactivate

If CheckM2, GTDB-Tk, and their dependencies are already available in the system PATH, the following steps can be skipped.

Install dependencies used by CheckM2 and GTDB-Tk

All dependencies will be installed or linked into "metacat/bin/".

for i in diamond FastTree FastTreeMP guppy hmmalign hmmsearch pplacer prodigal skani
do
wget "https://raw.githubusercontent.com/liu-congcong/MetaCAT/main/Dependencies/${i}"
mv ${i} metacat/bin/
chmod 755 metacat/bin/${i}
done

Install CheckM2

python3 -m venv checkm2
source checkm2/bin/activate
pip3 install setuptools wheel pandas numpy scipy requests tqdm lightgbm scikit-learn==1.6.1 tensorflow==2.17
git clone --recursive https://github.com/liu-congcong/CheckM2.git checkm2-src
cd checkm2-src
python3 setup.py install
cd ..
rm -rf checkm2-src
deactivate

Download CheckM2's database from Zenodo

wget "https://zenodo.org/records/14897628/files/checkm2_database.tar.gz"
tar xvf checkm2_database.tar.gz
rm checkm2_database.tar.gz
mv CheckM2_database/uniref100.KO.1.dmnd checkm2/
rm -rf CheckM2_database
checkm2/bin/checkm2 database --setdblocation checkm2/uniref100.KO.1.dmnd
ln -s $(pwd)/checkm2/bin/checkm2 metacat/bin/checkm2

Install GTDB-Tk

Note that GTDB-Tk is frequently updated and may not be compatible with earlier database releases.

Therefore, each GTDB-Tk version should be used with its corresponding database to ensure compatibility.

python3 -m venv gtdbtk
source gtdbtk/bin/activate
pip3 install gtdbtk==2.7.1
deactivate

Download GTDB-Tk's database from GTDB-Tk

wget https://data.gtdb.ecogenomic.org/releases/release232/232.0/auxillary_files/gtdbtk_package/full_package/gtdbtk_r232_data.tar.gz
tar xvf gtdbtk_r232_data.tar.gz
rm gtdbtk_r232_data.tar.gz
mv release232 gtdbtk/
echo "export GTDBTK_DATA_PATH=\"$(pwd)/gtdbtk/release232\"" >> ~/.bashrc
source ~/.bashrc
ln -s $(pwd)/gtdbtk/bin/gtdbtk metacat/bin/gtdbtk

GPU version for MetaCAT

To enable the GPU for MetaCAT, you need to install CuPy.

pip3 install cupy-cudaXXX

Documentation

HERE.

Examples

HERE.

Datasets for Review

HERE.

Updates

v1.0.0

The first release.

v1.0.1

Added the --bam-suffix option to the coverage command.

Added the --fasta-suffix option to the cluster2mapping command.

Added the --input-suffix option to the indexBam command.

Added the --fasta-suffix option to the representative command.

Added the --bam-suffix and --mapping-suffix options to the abundance command.

Added the --input-suffix option to the variant command.

Added the --input-suffix option to the checkm2 command.

Added the --input-suffix option to the gtdbtk command.

v1.0.2

Fixed a bug in the checkm2 command that occurred when handling a large number of input files.

v1.0.3

Fixed a bug that could potentially cause a segmentation fault.

Added support for skani.

Rewrote indexBam.

v1.0.4

Added support for GTDB-Tk v2.7.1.

Minor bug fixes.

v1.0.5

Improved the performance of indexBam.

Added the --no-index option to the coverage command.

Added the --no-mapping option to the cluster command.

Renamed --no-fasta-clusters to --no-fasta in the cluster command.

Removed mapping file generation from the representative command.

Removed the --mapping option from the abundance command.

Removed the --mapping option from the variant command.

Added the --temp option to the checkm2 command.

Added the --temp option to the seed command.

Added the --temp option to the gtdbtk command.

v1.0.6

Renamed the first column header in the abundance file from Abundance to Classification.