Installation and first run

Install MetaPathways, try the included three-sample dataset, then use your own data. Linux x86-64 is supported. Choose one installation method below; Mamba is recommended.

1. Conda package with Mamba (preferred)

mamba create -n metapathways --override-channels --strict-channel-priority \
  -c hallamlab -c conda-forge -c bioconda metapathways=3.5.2
conda activate metapathways

This installs MP and its workflow dependencies, including MAGSplitter and Camelot. Prepare the included data, build the small reference database, and run all three samples:

metapathways prepare_test -o ~/mp-test
cd ~/mp-test
metapathways build_db --test -d MPDB
metapathways analysis_wf \
  --manifest cami-test/all.tsv -o all -d MPDB \
  --annotation_dbs swissprot_test \
  --rRNA_refdbs SILVA_SSU_test SILVA_LSU_test \
  --skip_ptools --threads 4 --memory '4 GB' --max_tasks 2
metapathways report -o all --serve --no-browser --port 8765

Open the URL printed by the report server. On a remote server, use an SSH tunnel. The 2.4 MiB input dataset is included in the package and is derived from CAMI II (Meyer et al., 2022); database preparation downloads enzyme and taxonomy support records. The test covers annotation, paired-read abundance, genome splitting, reports and exploration. Pathway inference is skipped because it requires your own Pathway Tools license.

2. Quay: Docker or Apptainer

# Docker
docker pull quay.io/hallamlab/metapathways:3.5.2

# Or Apptainer
apptainer pull metapathways.sif docker://quay.io/hallamlab/metapathways:3.5.2

The image includes the same workflow dependencies and test data. Follow the Docker three-sample test or Apptainer three-sample test to run the commands with your working directory mounted for persistent results. Licensed Pathway Tools is a separate image.

3. Local installation from GitHub

git clone https://github.com/hallamlab/MetaPathways.git
cd MetaPathways
mamba env create -f docker/conda_base.yml
mamba run -n metapathways python -m pip install .
conda activate metapathways

Then run the same three-sample commands under option 1, starting with metapathways prepare_test -o ~/mp-test. MP installs its Python workflow helpers automatically. The data comes from the installed package; the test does not depend on your checkout location.

Try your own data

Build a production reference database, then annotate an assembly:

metapathways build_db -d ~/MPDB --func swissprot -a fast
metapathways run -i /path/to/assembly.fasta -o results -d ~/MPDB --threads 8

For assemblies with reads and genome maps, follow the complete workflow. If you want PGDBs, complete the Pathway Tools installation guide before starting that workflow. The small test references are for testing only.

CAMI references

  • CAMI: Sczyrba, A., Hofmann, P., Belmann, P., et al. (2017). Critical Assessment of Metagenome Interpretation—a benchmark of metagenomics software. Nature Methods 14(11), 1063–1071. DOI: 10.1038/nmeth.4458. CAMI project website.

  • CAMI II: Meyer, F., Fritz, A., Deng, Z.-L., et al. (2022). Critical Assessment of Metagenome Interpretation: the second round of challenges. Nature Methods 19(4), 429–440. DOI: 10.1038/s41592-022-01431-4. CAMI project website.

  • Source dataset for the MP test subset: CAMI II multi-sample human microbiome dataset. Dataset DOI: 10.4126/FRL01-006425518. The bundled inputs are selected and cropped subsets of this collection; their exact transformations and file hashes are recorded in the bundle provenance.