KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

MAGmax

★ 37 Open GitHub ↗

From dereplication to genome enrichment: Enhancing genome recovery across metagenomic samples using MAGmax

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MAGmax
MAGmax is a dereplication tool designed to maximize the recovery of Metagenome-Assembled Genomes (MAGs) through bin Merging and reAssembly. It performs dereplication in three stages: (i) grouping bins based on average sequence identity, (ii) merging bins within each group, and (iii) reassembling the merged bins.

![MAGmax](https://github.com/user-attachments/assets/802387bf-ae34-48b5-963f-978a0e2d10d5)

## Inputs
MAGmax requires three input directories,
1. `<binsdir>`, directory containing bin files in FASTA format that need to be dereplicated. (e.g., output files from any metagenome binning tool)

2. `<readdir>`, directory containing read files in FASTQ format for each sample. 
   
3. `<mapid_dir>`, directory containing mapping files for each sample. Each file is a text file listing read IDs and the corresponding contig IDs they mapped to. These files are used to retrieve reads that map to each merged bin from the FASTQ files in `<readdir>` and to generate new bin-specific FASTQ files for reassembly.

## Outputs
By default, an output directory named `mags_<x>comp_<y>purity` will be created, where `x` and `y` correspond to the user-specified completeness and purity thresholds used to select final bins. If unspecified, MAGmax sets 50% for completeness and 95% for purity. With `-o` option, user can specify the output directory.

The output directory contains dereplicated bins, a text file listing the completeness and contamination scores for each bin as calculated by CheckM2, and memberships file listing members for each selected representative.

## Example command line call

magmax -b <binsdir> -r <readdir> -m <mapid_dir> -f fasta -t 24
    magmax -b <binsdir> -r <readdir> -m <mapid_dir> -f fasta -t 24 --anifile ani_edges // if skani output is available from (skani triangle <bindir> -E -o ani_edges)
    magmax -b <binsdir> -r <readdir> -m <mapid_dir> -f fasta -t 24 -q quality_report.tsv // if CheckM2 result is already available
    magmax -b <binsdir> -r <readdir> -m <mapid_dir> -f fasta -t 24 --split // if input bins are not already split by sample id

## Dereplication without reassembly
MAGmax provides an option to perform dereplication without reassembly using `--no-reassembly` flag. In this mode, MAGmax selects the best bin within each genomic cluster based on a quality score (defined as completeness - 5 * contamination) that also meets the user-defined completeness and contamination thresholds. When this option is enabled, only the bin directory (`-b`) is required as input.

magmax -b <binsdir> --no-reassembly -f fasta -t 24
    magmax -b <binsdir> --no-reassembly -f fasta -t 24 -q quality_report.tsv // if CheckM2 result is already available
    magmax -b <binsdir> --no-reassembly -f fasta -t 24 --split // if input bins are not already split by sample id

## Dereplication in sensitive mode
Sensitive mode selects representative genomes based on high-ANI connectivity than bin quality score. It calculates weighted degree (`Σ max(0, ANI − ANI_threshold)`) for each node and select bin with the highest value. This option favors bins that are highly similar to a larger number of neighboring bins, even if they are not the highest-quality bin in the cluster. Bin merging and reassembly steps are disabled in this mode.

magmax -b <binsdir> -f fasta -t 24 --sensitive

Benchmarking results comparing the default --no-reassembly and --sensitive modes are available in [sensitive_mode.md](https://github.com/soedinglab/MAGmax/blob/main/sensitive.md).

## Generate a custom species-level reference database
MAGmax provides a `customdb` subcommand to build a species-level non-redundant genome database by combining GTDB-Tk taxonomic classification with ANI-based dereplication. Bins confidently assigned to a known GTDB-Tk species are grouped by species and one representative is selected per species. Remaining unclassified bins are dereplicated by ANI clustering, enabling discovery of novel species. Isolate genomes can be prioritized as representatives using `--isolate-genomes`.

magmax customdb -g gtdbtk.summary.tsv -b <binsdir> -q quality_report.tsv -t 24

For a step-by-step guide, see the tutorial in [generate_customdatabase.md](https://github.com/soedinglab/MAGmax/blob/main/generate_customdatabase.md).

## Installation
### Prerequisites

- **Rust**: Follow the instructions [here](https://www.rust-lang.org/tools/install) to install Rust.
- **Conda**: You can install Conda via [Miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Anaconda](https://www.anaconda.com/products/distribution).

### Dependencies

- **CheckM2**: Install [CheckM2](https://github.com/chklovski/CheckM2), download [checkm2 database](https://zenodo.org/api/records/14897628/files/checkm2_database.tar.gz/content) and set CHECKM2DB variable correctly. CheckM2 should already be installed and accessible in your PATH, regardless of the options used to install MAGmax.

Option 1: Use conda package

conda install -c bioconda magmax
    or
    mamba install -c bioconda magmax # faster installation

Option 2: Use the pre-built executable.

# For x86_64 Linux (glibc-based systems)
    wget https://github.com/soedinglab/MAGmax/releases/download/v1.0.0/magmax-linux.tar.gz
    cd magmax-linux/bin
    chmod +x magmax
    ./magmax -h
    sudo cp magmax /usr/local/bin/ # to access globally

To use this option, in addition to CheckM2, [skani](https://github.com/bluenote-1577/skani), [SPAdes](https://github.com/ablab/spades), and [seqtk](https://github.com/lh3/seqtk), and [MEGAHIT](https://github.com/voutcn/megahit) (optional) must be installed already and available in your PATH. Alternatively, use environment.yml to create conda environment and activate it to run magmax.

conda env create -f environment.yml
    conda activate magmax_env

Option 3: Build from source

git clone https://github.com/soedinglab/MAGmax.git
    cd MAGmax
    conda env create -f environment.yml
    conda activate magmax_env
    cargo install --path .
    magmax -h

## Options
    -b, --bindir <BINDIR>
            Directory containing fasta files of bins
    -r, --readdir <READDIR>
            Directory containing read files
    -m, --mapdir <MAPDIR>
            Directory containing mapids files
    -i, --ani <ANI>
            ANI for clustering bins (%) [default: 99]
    -c, --completeness <COMPLETENESS_CUTOFF>
            Minimum completeness of bins (%) [default: 50]
    -p, --purity <PURITY_CUTOFF>
            Mininum purity (1- contamination) of bins (%) [default: 95]
    -a, --alignedfrac <ALIGNEDFRAC>
            Mininum aligned fraction of (both reference and query) genomes covered in the ANI calculation [default: 0]
    -f, --format <FORMAT>
            Bin file extension [default: fasta]
    -t, --threads <THREADS>
            Number of threads to use [default: 8]
        --no-reassembly
            Perform dereplication without bin merging and reassembly
        --sensitive
            Select representatives based on high connectivity. Bin merging and reassembly steps are disabled
        --split
            Split clusters into sample-wise bins before processing
    -q, --qual <QUAL>
            Quality file produced by CheckM2 (quality_report.tsv)
        --anifile <ANIFILE>
            ANI file produced by skani using command: skani triangle <bindir> -E -o <anifile>
        --isolate-genomes <ISOLATE_GENOMES>
            File listing isolate genomes in the input bins; these are prioritized as representatives
    -o, --outdir <OUTPUT>
            Directory of output
        --assembler <ASSEMBLER>
            Assembler choice for reassembly step (spades|megahit), spades is recommended [default: spades]
    -h, --help
            Print help
    -V, --version
            Print version

## Test run using toy data
This example test run demonstrates dereplication of bins using the provided toy dataset. In the `test/bins` directory, example bins generated with MetaBAT2 are given. In the `test/reads` directory, paired-end read files for two samples are given and in the `test/mapids` directory, mapid files mapping reads to contigs for each sample are given. Precomputed CheckM2 quality scores for the input bins are given in the `test/quality_report.tsv`. Run the following command to execute the test:

magmax -b test/bins -r test/reads -m test/mapids -t 24 -q test/quality_report.tsv

To run without reassembly,

magmax -b test/bins --no-reassembly -t 24 -q test/quality_report.tsv

To run in senstive mode,

magmax -b test/bins --sensitive --t 24 -q test/quality_report.tsv

After running MAGmax, an output folder named `mags_50comp_95purity` will be created in the `test` directory. This folder contains the following files:

- `bins_checkm2_qualities.tsv` — Table summarizing the quality metrics of the dereplicated bins.  
- `sample_ERR3405607_metabat2_results.63.fasta` — Final bin obtained after dereplication of the input bins.
- `memberships.tsv` - Text file containing list of representative bins and their member bins.

## Input specifications
1. Input contigs must have IDs prefixed with the sample ID, separated by a `C`. This is a common practice for both single- and multi-sample binning. Ensure mapping and binning are performed on contig files with these updated contig IDs.

2. Ensure that headers in the fastq files have read ID separated from sequencer details by a space or tab, not by a dot. This is important for `seqtk`, which is used by MAGmax, to fetch reads correctly.

`Correct format: @SRR25448374.1 A00214R:157:HLMVMDSXY:1:1101:19868:1016:N:0.length=151#0/1`

`Wrong format: @SRR25448374.1.A00214R:157:HLMVMDSXY:1:1101:19868:1016:N:0.length=151#0/1`

To fix, use the below bash command

sed -i -E 's/^(@[^.]+\.[^.]+)\./\1 /' read.fastq

3. Mapid files can be created using `aligner2counts` (https://github.com/soedinglab/binning_benchmarking/tree/main/util#aligner2counts) with the `only-mapids` option. An example file format is given below,

File name: `<sampleid>_mapids`
    ```
    read1_id    <sampleid>Ccontig1_id
    read2_id    <sampleid>Ccontig2_id
    read2_id    <sampleid>Ccontig4_id
    read3_id    <sampleid>Ccontig2_id
    read4_id    <sampleid>Ccontig3_id
    read4_id    <sampleid>Ccontig4_id
    ```

4. FASTQ and MAPID filenames must contain the sample ID (e.g., SRR25448374.fastq, SRR25448374_mapids). This is the default unless filenames are renamed manually.

## Notes
1. User can provide a custom quality score file with bin ID, completeness and contamination columns in same format as CheckM2 tsv output.

2. If input bins are not separated by sample IDs (e.g., when using MetaBAT2 or COMEBin on concatenated contigs), use the `--split` option to let MAGmax automatically separate bins by sample ID.
   
3. MAGmax can prioritize isolate genomes while selecting representative bin per cluster. For this, provide a list of isolate genome bins using `--isolate-genomes` option.

4. We recommend Spades for reassembly which produces bins with higher purity than bins assembled using Megahit.

MAGmax is stricter than Galah in dereplicating bins and exhibits similar computational efficiency on large dataset. For more details, see [magmax_vs_galah.md](https://github.com/soedinglab/MAGmax/blob/main/magmax_vs_galah.md).

## Citation
Arangasamy Yazhini, Johannes Söding, Enhancing genome recovery across metagenomic samples using MAGmax, Bioinformatics (2025), https://doi.org/10.1093/bioinformatics/btaf538.

## Data resource
Dataset used for this study is available in [10.5281/zenodo.19545550](https://zenodo.org/records/19545550).

MAGmax

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README