ARGenus

ARG detection with honest genus / species / replicon-context reporting from metagenomes

ARGenus detects antibiotic resistance genes (ARGs) in metagenomic reads and, for each ARG, reports the bacterial source it was found in — using the DNA that flanks the gene on the assembled contig. Unlike tools that only detect ARGs, ARGenus links each ARG to a genus (and, when the flanking is specific enough, a species) and tells you how much to trust that link.

What's new in 0.3.0

ARGs frequently sit on plasmids and other mobile elements that move between genera, so forcing a single "source genus" is often wrong. 0.3.0 replaces the single genus call with an honest 4-axis report so an ambiguous locus looks ambiguous instead of confidently wrong:

• Genus — a single genus, or multi-genus(N):A/B/C/… when several genera share the flanking within a small identity margin (a promiscuous gene), or Unknown.
• Species — a stricter, separately-thresholded call (--species-identity); multi-species(N):… / Unknown when the flanking isn't near-identical.
• Context — replicon of the matched flanking: plasmid / chromosome / ambiguous / NA, derived from PLSDB provenance of the flanking references. chromosome + single-genus is trustworthy; plasmid + multi-genus is not.
• Specificity — how gene-specific (breadth) the flanking evidence is.

Also new:

• Per-locus reassembly (--reassemble, opt-in): core/flank read split + SPAdes to recover a classifiable flanking for stalled loci.
• Per-locus exports (--emit-*): write gene / flanking sequences (assembled or as reads) for the resolved / no-flank-match / gene-not-in-DB classes.
• Pluggable read filter (--mapper strobealign|minimap2|bwa-mem2).
• Contig-only mode (--classify-contigs) to classify a pre-assembled FASTA.
• Bounded-memory extension — extension consensus is accumulated as per-position base counts, and each contig end is capped (--max-extension), so runtime and RAM no longer blow up on high-coverage/repetitive loci.

Features

• Direct ARG→genus/species linkage through flanking sequence analysis
• Honest reporting: multi-genus / multi-species / replicon context, not a forced call
• Targeted assembly: read filtering → MEGAHIT → k-mer extension (optional SPAdes reassembly)
• SNP verification: confirms resistance-conferring mutations for point-mutation ARGs
• Compact database: custom FDB format (zstd-compressed, on-demand gene blocks)
• Scales with depth: bounded extension memory; multi-threaded

Installation

From crates.io

cargo install argenus

From source

git clone https://github.com/necoli1822/ARGenus.git
cd ARGenus
cargo build --release

External tools (must be on PATH)

Required to run ARGenus on reads:

• minimap2 — alignment for ARG detection and flanking classification (always used)
• MEGAHIT — assembly of the filtered reads
• strobealign — the default read filter; not needed if you run --mapper minimap2

Only for opt-in features — not needed for a standard run:

• SPAdes — only for --reassemble
• BLAST+ (blastn, blastdbcmd) — only to build the 5,000 bp (--mode long) flanking DB; never used at run time, and unnecessary with the pre-built database below

Databases

ARGenus needs an ARG reference (.mmi or FASTA) and a flanking database (.fdb). These are not shipped with the crate (too large) — download the pre-built set or build your own.

Download the pre-built database (recommended)

The 1,000 bp PanRes database is published as a GitHub Release asset. Download, extract, and point ARGenus at the folder with -d:

# 311 MB download, ~360 MB extracted into ./db/
curl -L -o argenus-db-1kbp-v0.3.0.tar.gz \
  https://github.com/necoli1822/ARGenus/releases/download/db-1kbp-v0.3.0/argenus-db-1kbp-v0.3.0.tar.gz
tar xzf argenus-db-1kbp-v0.3.0.tar.gz       # -> db/

# -d auto-discovers everything inside the folder
argenus -d db/ -1 R1.fq.gz -2 R2.fq.gz -o results/

ARGenus ships two flanking-DB resolutions. Only the 1,000 bp database (high coverage, genus-level) is distributed for now; the 5,000 bp database (higher, species-level resolution) is much larger and will be released separately once its size is reduced. Until then you can build the 5,000 bp DB yourself (see below).

Database license: the pre-built database is derived from PanRes v1.0.0 and is licensed CC BY-NC 4.0 (non-commercial) — separate from the MIT-licensed ARGenus code. See NOTICE and License & citation.

The bundle contains:

-d/--db-dir auto-discovers the ARG reference, the flanking .fdb, and the optional plasmid_contigs.txt / contig_species.tsv inside the folder. Explicit -a/-f/--plasmid-contigs/--species-map still override what's found there.

Build your own

# Build the ARG reference (e.g. from PanRes)
argenus -b arg -x panres -o databases/

# Build a 1,000 bp flanking DB (GenBank/PLSDB)
argenus -b flank --mode short -a databases/AMR_PanRes.mmi -o databases/ -e you@email.com

# Compress an existing flanking TSV to FDB (external-sort build)
argenus -b fdb -a flanking.tsv -o databases/flanking.fdb

The two side files (plasmid_contigs.txt, contig_species.tsv) are auto-loaded from beside the .fdb if present, and enable the Context and Species axes respectively. You can also pass them explicitly with --plasmid-contigs / --species-map.

Usage

# Single sample (with a database folder — see Databases below)
argenus -d db/ -1 R1.fq.gz -2 R2.fq.gz -o results/

# ...or point at each database file explicitly
argenus -1 R1.fq.gz -2 R2.fq.gz \
    -a databases/AMR_PanRes.mmi \
    -f databases/flanking.fdb \
    -o results/

# Batch: a directory (auto-detect *_R[12].fastq.gz) or an ID-list file
argenus -l fastq_dir/ -d db/ -o results/

Results are written to results/results.tsv.

Common options

Honest-reporting options

Assembly / reassembly / exports

Run argenus --help for the complete list.

Output format (results.tsv)

Tab-delimited, one row per ARG locus:

Reading it: chromosome + single Genus + single Species = trustworthy. multi-genus(N) and/or plasmid = a promiscuous / mobile gene — the genus is not a reliable single source.

License & citation

ARGenus uses two different licenses — one for the code, one for the database:

The pre-built database is derived from the PanRes v1.0.0 resistance-gene collection (Zenodo, DOI 10.5281/zenodo.8055116, CC BY-NC 4.0), which aggregates ResFinder, ResFinderFG, CARD, MEGARes, NCBI AMRFinderPlus, ARG-ANNOT, and BacMet. See NOTICE for full attribution and the modifications ARGenus makes.

If you use ARGenus, please cite this tool (citation to be added upon publication) and the PanRes / ARGprofiler database:

Martiny H-M, et al. ARGprofiler—a pipeline for large-scale analysis of antimicrobial
resistance genes and their flanking regions in metagenomic datasets.
Bioinformatics 40(3):btae086 (2024). https://doi.org/10.1093/bioinformatics/btae086

Contact

Questions and bug reports: open an issue at https://github.com/necoli1822/ARGenus