🔬 EnteroScope

A Tailored Computational Workflow Enabling Rapid, User-Friendly Genotyping and Epidemiological Surveillance of the Enterobacter cloacae Complex

**Complete CREC (Carbapenem‑Resistant Enterobacter cloacae) genomic analysis in minutes — not hours**

📋 Table of Contents

What's New in v1.1.0
🎯 Overview
✨ Key Features
⚡ Quick Start (CLI)
🔧 Installation (CLI)
🐳 Docker Usage
🖥️ Singularity for HPC Clusters
🔗 Integrated External Tools & Dependencies
🚀 Usage Guide (CLI)
📁 Output Structure
🔍 Analytical Modules
🔬 Validation & Accuracy
🤖 AI Integration Guide
🔮 Future Development
❓ Frequently Asked Questions
🐛 Troubleshooting
📚 Citation
🙏 Acknowledgements
👥 Authors & Contact
📄 License
📚 Third‑Party Tool Citations

🆕 What's New in v1.1.0

Release Date: 2026-07-06

We’ve upgraded EnteroScope with a fully temporary‑directory execution model (HPC‑friendly), added point mutation reporting, introduced dynamic filtering thresholds, and improved the Ultimate Reporter with a dedicated Mutations tab and grouping by MLST.

Major Enhancements

✅ HPC‑Ready Orchestrator: All modules now run inside temporary directories (/tmp by default) and are automatically cleaned up. This eliminates permission errors on clusters and keeps your working directory pristine.
✅ Point Mutation Reporting (AMRfinderPlus): AMRfinderPlus now runs with --plus by default, and the Ultimate Reporter displays a gene‑centric Mutation tab with grouping by MLST – instantly see which clones carry mutations in gyrA, parC, rpoB, or 23S rRNA.
✅ Dynamic Threshold Flags:
- --amr-min-identity and --amr-min-coverage – custom cutoffs for AMR hits (0..1).
- --skip-amr-mutations – disable point mutation reporting if you only want acquired genes.
- --amr-force-update – force a fresh AMR database download before analysis.
- --abricate-min-identity and --abricate-min-coverage – custom cutoffs for ABRicate (default 80%).
✅ Better Logging: Each module’s stdout/stderr is captured in enteroscope_run.log for full traceability.
✅ Cleaner Output: Mutation summary files (mutation_summary.html, mutation_summary.tsv, mutation_master_summary.json) are now placed inside enteroscope_amrfinder_results/ and automatically copied to the summary module.
✅ Ultimate Reporter Updates:
- Mutations tab is always shown; if no mutations are found, a friendly message appears.
- Grouping by MLST is now available on the AMR, Virulence, BACMET, Plasmids, and Mutations tabs – click a button to reorganise genome lists by sequence type.
- Sortable tables on every tab.
- Scientific quotes rotate after each module and at the end for inspiration.
✅ Docker & Singularity: The container now runs without permission errors – use --writable-tmpfs for Singularity and all outputs are owned by your user.

🎯 Overview

EnteroScope is an automated, locally‑executable pipeline designed specifically for comprehensive genomic surveillance of the Enterobacter cloacae – an opportunistic pathogen that increasingly important in healthcare‑associated infections and carbapenem resistance (CREC). It integrates six essential genotyping methods into a single, cohesive workflow.

🌍 The Problem

Emerging Threat: Enterobacter cloacae is a leading cause of neonatal sepsis and hospital outbreaks, with CREC mortality rates exceeding 40%.
Fragmented Workflows: Traditional analysis requires 5+ separate tools (MLST, AMR, virulence, plasmids) with conflicting dependencies.
Data Overload: Raw outputs lack epidemiological context and actionable insights.
Resource Barriers: Web services raise privacy concerns; local solutions are hard to install.

💡 Our Solution

EnteroScope delivers:

✅ Single‑command installation via Conda or Docker.
✅ 3‑4 hrs complete analysis (100 samples, 16 cores).
✅ 100% local execution – your data stays private.
✅ Interactive HTML reports with rotating educational facts about E. cloacae.
✅ Gene‑centric tables (scrollable, wrapped genome lists).
✅ Automatic detection of critical resistance: KPC, NDM, OXA‑48, VIM, IMP, mcr, tet(X).
✅ Point mutation reporting with grouping by MLST.

Perfect for: Clinical labs, outbreak investigations (CREC), public health surveillance, and research studies.

📊 Sample Output

See a complete interactive report generated by EnteroScope:

The report includes AMR, Virulence, BACMET, Plasmid, and Mutations tabs, each with grouping by MLST, filter buttons, sortable headers, and scrollable genome lists.

✨ Key Features

Module	Purpose	Key Outputs	Speed
FASTA QC	Assembly quality (N50, GC%, contigs)	HTML, TSV, JSON	<30 sec
MLST	Sequence typing (7 housekeeping genes)	ST, allele profile	<1 min
AMR Profiling	Resistance genes (AMRFinderPlus)	Carbapenemases, ESBLs, mcr, tet(X)	2‑3 min
ABRicate	Multi‑database (9 DBs) – virulence/plasmids	VFDB, ResFinder, CARD, PlasmidFinder	3‑4 min
BACMET2	Biocide & heavy metal resistance	qac, mer, ars, czc, etc.	1‑2 min
PlasmidFinder	Replicon typing (IncL/M, IncFII, IncHI2)	Outbreak plasmid tracking	1‑2 min
Mutations (AMRfinderPlus)	Point mutations (`gyrA`, `parC`, `rpoB`, 23S)	Gene‑centric table, grouped by ST	1‑2 min
Ultimate Reporter	Interactive HTML (gene‑centric, scrollable lists, grouping)	All results in one place	<1 min

🛡️ Enterobacter‑Specific Innovations

Intrinsic AmpC handling: Automatic flagging of ACT/MIR genes (chromosomal) with clinical interpretation.
Carbapenemase detection: Word‑boundary pattern matching for KPC, NDM, OXA‑48‑like, VIM, IMP, IMI (chromosomal).
Colistin & tigecycline resistance: mcr‑1 to mcr‑10, tet(X) variants, efflux pumps (AcrAB‑TolC, OqxAB).
Plasmid epidemiology: Highlights IncL/M (OXA‑48), IncFII (KPC), IncHI2 (NDM/mcr).
Educational facts: 20 rotating facts about E. cloacae in the report header.
Point mutation surveillance: Tracks resistance‑associated mutations in gyrA, parC, rpoB, 23S rRNA.

🚀 Performance Advantages

Low memory footprint: runs on 4 GB RAM, scales to HPC clusters.
Dynamic resource allocation (psutil).
Temporary‑directory execution – no leftover files, HPC‑friendly.

⚡ Quick Start (CLI)

Install in 60 seconds

# Conda (Recommended) Recipe submitted to Bioconda
conda create -n enteroscope -c conda-forge -c bioconda -c enteroscope -y
conda activate enteroscope

# Mamba (Faster)
mamba create -n enteroscope -c conda-forge -c bioconda -c enteroscope -y
mamba activate enteroscope

Run your first analysis

# Single genome
enteroscope -i genome.fasta -o results/

# Batch processing (100 genomes)
enteroscope -i "*.fna" -o batch_results --threads 16
# Complete in ~4 hrs! 🎉

Advanced examples

# AMR with custom identity & coverage, skip mutations
enteroscope -i "*.fna" -o results --amr-min-identity 0.95 --amr-min-coverage 0.9 --skip-amr-mutations

# ABRicate with custom thresholds
enteroscope -i "*.fna" -o results --abricate-min-identity 85 --abricate-min-coverage 85

# Force AMR database update before analysis
enteroscope -i "*.fna" -o results --amr-force-update

# Keep temporary directories for debugging
enteroscope -i "*.fna" -o results --keep-temp

🔧 Installation (CLI)

System Requirements

Resource	Minimum	Recommended	Production
CPU Cores	2	8+	16+
RAM	4 GB	8 GB	16 GB
Storage	2 GB	10 GB	50 GB+
OS	Linux, macOS, WSL2	Linux	Linux Cluster

Step‑by‑Step

# 1. Install Miniconda (if needed)
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
source ~/.bashrc

# 2. Add channels
conda config --add channels conda-forge
conda config --add channels bioconda

# 3. Create environment
conda create -n enteroscope python=3.9 enteroscope -y
conda activate enteroscope

# 4. Update databases (recommended)
abricate --setupdb
enteroscope --update-amr-db   # Only needed once

🐳 Docker Usage

Quick Start

# Pull the image
docker pull bbeckleyhub/enteroscope:latest

# Test
docker run --rm bbeckleyhub/enteroscope:latest --help

# Analyse your data
docker run --rm \
  -v $(pwd)/genomes:/data/input \
  -v $(pwd)/results:/data/output \
  bbeckleyhub/enteroscope:latest \
  -i "/data/input/*.fasta" -o /data/output -t 4

# Fix ownership (output files owned by root)
sudo chown -R $USER:$USER ./results

🖥️ Singularity for HPC Clusters

On HPC clusters that support Singularity/Apptainer, you can run EnteroScope without sudo and output files will belong to your user automatically.

Important: EnteroScope writes temporary files inside its own installation directory. Singularity mounts containers as read‑only by default, so you must add the --writable-tmpfs flag.

Option A: Direct pull (if network allows)

singularity pull enteroscope.sif docker://bbeckleyhub/enteroscope:latest
singularity run --writable-tmpfs -B $(pwd):/data enteroscope.sif -i "/data/*.fasta" -o /data/output

Option B: Convert from local Docker image (when pull fails on HPC)

On a machine with Docker:

docker pull bbeckleyhub/enteroscope:latest
docker save bbeckleyhub/enteroscope:latest -o enteroscope.tar
singularity build enteroscope.sif docker-archive://enteroscope.tar

Copy enteroscope.sif to the HPC. Then:

singularity run --writable-tmpfs -B $(pwd):/data enteroscope.sif -i "/data/*.fasta" -o /data/output

Explanation of flags

Flag	Purpose
`--writable-tmpfs`	Creates a temporary writable overlay – required for EnteroScope.
`-B $(pwd):/data`	Binds current directory to `/data` inside the container.
`-i "/data/*.fasta"`	Input pattern (quotes prevent host expansion).
`-o /data/output`	Output directory (appears as `./output` on host).

After the run, all results in ./output are owned by your HPC user – no sudo chown needed.

🔗 Integrated External Tools & Dependencies

These tools are automatically installed as Conda dependencies (see environment.yml). EnteroScope’s MIT license does not cover them; each tool is used under its own license.

Tool	Purpose	Source	License
MLST	Sequence typing	tseemann/mlst	GPL v2
ABRicate	Mass screening	tseemann/abricate	GPL v2
AMRFinderPlus	AMR gene & mutation detection	ncbi/amr	Public domain
PlasmidFinder	Replicon typing	genomicepidemiology/plasmidfinder	Apache‑2.0
BACMET2	Biocide/metal resist.	bacmet2	Academic free

🚀 Usage Guide (CLI)

Basic commands

# Single genome
enteroscope -i genome.fasta -o results/

# Batch processing with wildcards
enteroscope -i "*.fna" -o results_2025 --threads 8

# Skip modules
enteroscope -i sample.fna -o results --skip-abricate

Full options

usage: enteroscope [-h] [-i INPUT] [-o OUTPUT] [-t THREADS] [--skip-qc] [--skip-mlst] [--skip-abricate] [--skip-amr] [--skip-summary]
                   [--amr-min-identity AMR_MIN_IDENTITY] [--amr-min-coverage AMR_MIN_COVERAGE] [--skip-amr-mutations]
                   [--amr-force-update] [--abricate-min-identity ABRICATE_MIN_IDENTITY]
                   [--abricate-min-coverage ABRICATE_MIN_COVERAGE] [--update-amr-db] [--force-update-amr-db] [--keep-temp]
                   [--clean-output] [--version]

📁 Output Structure

Enteroscope_results/
├── fasta_qc_results/                # QC metrics (HTML, TSV, JSON)
├── mlst_results/                    # MLST typing (ST, allele profile)
├── enteroscope_abricate_results/    # ABRicate outputs (9 databases)
│   ├── enteroscope_card_summary_report.html
│   ├── enteroscope_vfdb_summary_report.html
│   ├── enteroscope_plasmidfinder_summary_report.html
│   └── ...
├── enteroscope_amrfinder_results/   # AMRfinderPlus results
│   ├── enteroscope_amrfinder_summary_report.html
│   ├── mutation_summary.html        # Gene-centric mutation table (for internal use)
│   ├── mutation_summary.tsv
│   └── mutation_master_summary.json
├── ENTERO_ULTIMATE_REPORTS/         # Final HTML dashboard
│   ├── enteroscope_ultimate_report.html  # Main interactive report
│   ├── enteroscope_ultimate_report.json  # Full data for AI
│   ├── amr_genes.csv
│   ├── virulence_genes.csv
│   ├── bacmet_genes.csv
│   ├── plasmid_markers.csv
│   ├── mutations.csv                     # Exported point mutation table
│   ├── enterobacter_samples.csv
│   └── mlst_distribution.csv
└── enteroscope_run.log              # Detailed log file

🔍 Analytical Modules

1. FASTA QC

Metrics: N50, N70, N90, L50, GC%, total length, contigs.
Formats: HTML (interactive), TSV, JSON.

2. MLST (Enterobacter cloacae complex)

Loci: dnaA, fusA, gyrB, leuS, pyrG, rplB, rpoB
Database: PubMLST (updated via mlst --make)

3. AMR Profiling (AMRFinderPlus)

5,000 resistance genes; critical flags: carbapenemases (KPC, NDM, OXA‑48‑like, VIM, IMP), ESBLs, mcr, tet(X)
Risk categories: Critical / High / Standard
Point mutations: gyrA (quinolone), parC (quinolone), rpoB (rifampin), 23S rRNA (linezolid)

4. ABRicate Screening

Databases: VFDB, ResFinder, CARD, PlasmidFinder, MegaRes, NCBI, ARG‑ANNOT, ECOH, EcoLi_VF
Thresholds: user‑adjustable via --abricate-min-identity and --abricate-min-coverage (default: 80%)

5. BACMET2

Biocides: qac, cepA, formA
Heavy metals: mer, ars, cop, sil, chr, cad, znt, czc

6. PlasmidFinder

Replicons: IncL/M (OXA‑48), IncFII (KPC), IncHI2 (NDM/mcr), Col‑like, etc.
Category: “Incompatibility group X” or “Colicin plasmid”

7. Mutation Detection (AMRfinderPlus)

AMRfinderPlus reports point mutations in genes like gyrA, parC, rpoB, and 23S rRNA.
EnteroScope creates a gene‑centric mutation table with grouping by MLST, shown in the Ultimate Reporter’s Mutations tab.
Mutations can be exported as CSV for further analysis.

8. Ultimate Reporter

Interactive HTML with scrollable genome lists, filter buttons, combination tables, rotating educational facts, AI‑ready JSON, and grouping by MLST on all gene‑centric tabs (AMR, Virulence, BACMET, Plasmids, Mutations).

🔬 Validation & Accuracy

Reference strain validation (100% concordance)

Strain	Expected	EnteroScope result
E. cloacae ATCC 13047	ST114	✅ ST114
E. hormaechei subsp. oharae	ST78	✅ ST78
KPC‑producing isolate	ST171, blaKPC‑2	✅ ST171, blaKPC‑2

Clinical isolate pilot (n=24)

Carbapenemase genes: 8 isolates (33%): KPC‑2 (5), NDM‑1 (2), OXA‑48 (1)
Colistin resistance (mcr‑9): 2 isolates
Dominant STs: ST171 (6), ST78 (5), ST114 (4)

🤖 AI Integration Guide

EnteroScope’s HTML reports are designed for AI analysis.

Example questions:

“Which samples carry carbapenemase genes (KPC, NDM, OXA‑48)?”
“List all isolates with mcr genes (colistin resistance).”
“What are the common plasmid replicons in ST171?”
“Show me the co‑occurrence of blaKPC and IncFII plasmids.”
“Summarise the AMR profile of sample XYZ.”
“Which isolates have gyrA mutations?”
“Show me the mutation table grouped by MLST.”

Upload the HTML or JSON file to ChatGPT, Claude, or Gemini and ask away.

🔮 Future Development

Raw read support (FASTQ → assembly → typing)
Real‑time database updates
Machine learning module for AMR phenotype prediction
Integration with local CREC outbreak databases

❓ Frequently Asked Questions

Q: Does EnteroScope detect the intrinsic IMI carbapenemase?
A: Yes. The word‑boundary pattern matching in categorize_gene() specifically handles blaIMI without false positives (e.g., not matching “fimI”).

Q: Can I use it for E. coli or Klebsiella?
A: No. Please use our dedicated tools: EcoliTyper and Kleboscope.

Q: The AMR databases are huge. Why aren’t they in the repo?
A: The databases are downloaded on‑the‑fly via the download_databases.sh script. This keeps the repository small and the installation legal.

Q: How do I disable point mutation reporting?
A: Use the --skip-amr-mutations flag.

Q: Where are mutation summary files?
A: They are inside enteroscope_amrfinder_results/ and are automatically copied to the summary module. The Ultimate Reporter’s Mutations tab displays them.

🐛 Troubleshooting

Problem	Solution
`amrfinder` not found	Run `enteroscope --update-amr-db`
`abricate` databases missing	Run `abricate --setupdb`
Permission denied (Docker)	Use `sudo chown -R $USER:$USER ./output`
Singularity “No such file or directory”	Add `--writable-tmpfs` flag
MLST fails (unknown scheme)	Run `mlst --make` to update PubMLST data
Temporary directories not cleaning up	Use `--keep-temp` to debug; normally they are auto‑removed

If problems persist, open an issue on GitHub.

📚 Citation

If you use EnteroScope in your research, please cite:

Beckley, B.(2026). EnteroScope: a species‑optimized computational pipeline for rapid and accessible Enterobacter cloacae genotyping and surveillance.

@article{beckley2026enteroscope,
  title={EnteroScope: A Tailored Computational Workflow Enabling Rapid, User-Friendly Genotyping and Epidemiological Surveillance of the Enterobacter cloacae Complex},
  author={Beckley Brown},
  journal={In preparation},
  volume={?},
  pages={??},
  year={??},
  doi={??} 
}

🙏 Acknowledgements

We thank the open‑source bioinformatics community, especially:

Torsten Seemann (MLST, ABRicate)
NCBI AMRFinderPlus team
CGE (PlasmidFinder)
BACMET2 creators
University of Ghana Medical School for support

👥 Authors & Contact

Brown Beckley (Primary developer)
📧 brownbeckley94@gmail.com
🐙 bbeckley-hub
🔗 LinkedIn

📄 License

EnteroScope pipeline code: MIT License (see LICENSE).
Third‑party tools: each under its own license (see section above).

📚 Third‑Party Tool Citations

Click to expand BibTeX citations

@software{seemann_mlst_2018,
  author = {Seemann, T.},
  title = {MLST: Scan contig files against traditional PubMLST typing schemes},
  year = {2018},
  url = {https://github.com/tseemann/mlst}
}

@article{jolley_pubmlst_2018,
  author = {Jolley, K. A. and Bray, J. E. and Maiden, M. C. J.},
  title = {Open-access bacterial population genomics: BIGSdb software, the PubMLST.org website and their applications},
  journal = {Wellcome Open Research},
  volume = {3},
  pages = {124},
  year = {2018},
  doi = {10.12688/wellcomeopenres.14826.1}
}

@software{seemann_abricate_2018,
  author = {Seemann, T.},
  title = {ABRicate: Mass screening of contigs for antimicrobial resistance and virulence genes},
  year = {2018},
  url = {https://github.com/tseemann/abricate}
}

@article{feldgarden_amrfinderplus_2019,
  author = {Feldgarden, M. et al.},
  title = {AMRFinderPlus and the Reference Gene Catalog facilitate examination of the genomic links among antimicrobial resistance, stress response, and virulence},
  journal = {Scientific Reports},
  volume = {11},
  pages = {12728},
  year = {2019},
  doi = {10.1038/s41598-021-91456-0}
}

@article{carattoli_plasmidfinder_2014,
  author = {Carattoli, A. et al.},
  title = {In silico detection and typing of plasmids using PlasmidFinder and plasmid multilocus sequence typing},
  journal = {Antimicrobial Agents and Chemotherapy},
  volume = {58},
  number = {7},
  pages = {3895-3903},
  year = {2014},
  doi = {10.1128/AAC.02412-14}
}

🚀 Ready to fight CREC?

From fragmented data to actionable insights.

EnteroScope: Precision surveillance for the Enterobacter cloacae.

⭐ If this tool helps your research, please star the repository! ⭐

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
enteroscope		enteroscope
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
cleanup.sh		cleanup.sh
enteroscope.png		enteroscope.png
environment.yml		environment.yml
meta.yaml		meta.yaml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation