bio-epidemiological-genomics-amr-surveillance

What this skill does

## Version Compatibility

Reference examples tested with: ncbi-amrfinderplus 4.0+, resfinder 4.5+, rgi 6.0+ (CARD 3.3+), abritamr 1.0.14+, staramr 0.10+, hamronization 1.1+, tb-profiler 6.2+, mykrobe 0.13+, mob_suite 3.1+, plasmidfinder 2.1+, MobileElementFinder 1.0+, pandas 2.2+, BioPython 1.84+.

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show <package>` then `help(module.function)` to check signatures
- CLI: `<tool> --version` then `<tool> --help` to confirm flags
- AMRFinderPlus: `amrfinder --list_organisms` for the current `--organism` catalogue
- WHO Mtb catalogue: `tb-profiler list_db` and verify the bundled WHO edition
- AMR database freshness: `amrfinder -u` (NCBI ReferenceGeneCatalog) and `tb-profiler update_tbdb`

If a flag or column name does not match (`--species` vs `--organism`, `barcode_build` vs `barcode-build`), introspect the installed package rather than retrying. AMRFinderPlus, RGI, and ResFinder all renamed columns between major releases.

# AMR Surveillance

**"What antibiotic-resistance determinants are in this assembly, and what susceptibility do they imply?"** -> Combine acquired-gene detection, chromosomal point-mutation calling, mobile-element context, and curated phenotype mapping into a single per-isolate report fit for surveillance or clinical handover. Tool choice is determined by species (Mtb needs TB-Profiler, not AMRFinderPlus), reporting standard (WHO GLASS vs CARD vs in-house), and whether mobility matters (carbapenemase outbreak: yes; routine ESBL screen: less so).

- CLI: `amrfinder -n assembly.fa --organism Klebsiella_pneumoniae --plus` -- acquired + intrinsic-aware point mutations
- CLI: `tb-profiler profile -1 r1.fq.gz -2 r2.fq.gz -p sample` -- TB drug-resistance against WHO 2nd-edition catalogue
- CLI: `hamronize amrfinderplus --analysis_software_version 4.0.3 --reference_database_version 2025-02-01.1 in.tsv > out.tsv` -- normalise output across tools
- Python: `pandas` to join AMRFinderPlus + RGI + ResFinder + MOB-suite per-isolate for a single decision table

## The Single Most Important Modern Insight -- Acquired AMR detection is not species-agnostic

A pan-species AMRFinderPlus run misses chromosomal point-mutation resistance because the point-mutation panels are species-specific and activated only when `--organism` is set. Running `amrfinder -n mtb.fa` without `--organism` returns "no AMR detected" on an XDR-TB genome because AMRFinderPlus has no Mtb organism mode -- the user must switch tools (TB-Profiler or Mykrobe + WHO 2nd-edition catalogue). Similarly, *Salmonella* gyrA T83I, *Klebsiella* mgrB inactivation, and *E. coli* QRDR mutations are silent without `--organism Salmonella` / `Klebsiella_pneumoniae` / `Escherichia`. For any cross-tool surveillance pipeline, AMRFinderPlus with `--organism` MUST be paired with a species-specific second tool (TB-Profiler for Mtb; ResFinder 4.0 with `-s 'species'` for PointFinder coverage; hAMRonization to merge). Andersson et al. *Nat Rev Microbiol* 17:479 (2019) further notes that heteroresistance at 0.1-1% allele frequency is widespread and invisible to default variant callers, compounding the failure mode for any single-tool workflow.

## Algorithmic Taxonomy

| Tool | Mechanism | Inputs | Output | Strength | Fails when |
|------|-----------|--------|--------|----------|------------|
| AMRFinderPlus (Feldgarden 2021 *Sci Rep* 11:12728) | Curated HMM + BLAST against NCBI ReferenceGeneCatalog; per-gene cutoffs | assembly or protein | gene + class + element-type | Gene-family-aware (catches divergent variants); built-in species point-mutation panels | No Mtb mode; reports intrinsic genes unless `--organism` set |
| ResFinder 4.0 (Bortolaia 2020 *J Antimicrob Chemother* 75:3491) | BLAST against ResFinder DB (acquired) + PointFinder DB (chromosomal mutations) per species | assembly or reads | gene + predicted phenotype (S/I/R) | Phenotype prediction tied to CLSI/EUCAST | Requires explicit `-s 'species'` for PointFinder; default 90/60 cutoffs hide divergent variants |
| CARD-RGI (Alcock 2023 *NAR* 51:D690) | BLAST + HMM against CARD; tiers Perfect / Strict / Loose | assembly or protein | ARO ontology term, model-type (homolog / variant / overexpression / knockout / rRNA) | Mechanism-resolved (operons modelled); ARO ontology is curated | Loose tier produces many false positives; default Strict+Perfect misses real variants in non-model organisms |
| abritAMR (Sherry 2023 *Nat Commun* 14:60) | AMRFinderPlus wrapper + drug-class classifier; ISO-certified for clinical use | assembly | gene + drug class | First ISO-certified AMR pipeline; accredited reporting categories | Limited to AMRFinderPlus's underlying gene panel |
| staramr | ResFinder + PointFinder + PlasmidFinder + MLST in one pipeline | assembly | combined report | One-shot Salmonella / E. coli / Campylobacter surveillance | Default organism handling can hide point mutations; verify each component version |
| TB-Profiler (Phelan 2019 *Genome Med* 11:41) | Maps reads or assembly against H37Rv + WHO catalogue + Coll/Napier lineage barcode | reads or assembly | per-drug R/R-interim/Uncertain/S + lineage | WHO 2nd-edition catalogue integration; lineage call; heteroresistance from allele frequency | Hardcoded to MTBC; older bundled DB may predate current WHO edition |
| Mykrobe (Hunt 2019 *Wellcome Open Res* 4:191) | k-mer presence/absence against curated panel | reads | species + AMR per drug | k-mer-fast; cross-checks TB-Profiler; supports Mtb, S. aureus, Salmonella, gonorrhoea | Panel may lag WHO catalogue; check `--panel` |
| hAMRonization (PHA4GE) | Format converter to PHA4GE schema | per-tool TSV | unified TSV/JSON | Cross-tool comparison; surveillance harmonisation | Mandatory metadata fields differ per tool subparser |

## Decision Tree by Scenario

| Scenario | Recommended | Why wrong choices fail |
|----------|-------------|------------------------|
| Routine screen of an *E. coli* / *Klebsiella* / *Salmonella* assembly for acquired AMR + point mutations | AMRFinderPlus with `--organism Escherichia` / `Klebsiella_pneumoniae` / `Salmonella` + `--plus` | Without `--organism`: no PointFinder panel, fluoroquinolone QRDR mutations missed; intrinsic-gene noise in Klebsiella |
| *M. tuberculosis* drug-resistance prediction | TB-Profiler interpreted via WHO 2nd-edition catalogue, Mykrobe as cross-check on R/XDR isolates | AMRFinderPlus has no Mtb organism mode; ResFinder PointFinder lacks the full WHO catalogue; tool defaults silently call Group 3 mutations as "susceptible" |
| Predict S/I/R phenotype, not gene presence | ResFinder 4.0 OR abritAMR; document EUCAST or CLSI breakpoint year | AMRFinderPlus reports presence only; mapping presence -> phenotype needs curated rules |
| Carbapenemase outbreak: is the gene mobile? | AMRFinderPlus -> MOB-suite (`mob_recon` + `mob_typer`) -> cross-reference; long-read or hybrid assembly recommended | PlasmidFinder alone gives replicon type but not gene-plasmid linkage; short-read draft assemblies fragment plasmid contigs and lose context |
| Cross-laboratory surveillance reporting | Pass per-tool output through hAMRonization to PHA4GE schema; populate `analysis_software_version` and `reference_database_version` | Raw cross-tool comparison is meaningless (CARD ARO vs ResFinder name vs NCBI ReferenceGeneCatalog) |
| Novel-variant surveillance (emergence) | AMRFinderPlus (HMM, gene-family-aware) OR CARD-RGI with Loose-tier manual review | abricate's 80/80 defaults reject divergent family members; pure-BLAST defaults silently miss novel mcr / OXA sub-variants |
| Quantitative AMR from metagenomic reads | AMRPlusPlus / DeepARG / ARGs-OAP normalised to 16S; report "ARG abundance" NOT "resistance" | Assembly-based tools fail on short reads; reporting environmental ARG counts as "resistance" inherits the environmental-resistome critique that homolog presence is not phenotypic resistance |
| Colistin resistance in *Klebsiella* /