"The 'Wait, You Can Do THAT?' Release"

We've been busy. Like, "forgot to eat lunch" busy. Here's what we've cooked up:

Before: You had a gene‑centric view (one gene, all genomes). Great for epidemiology, but if you wanted to see everything one single isolate carries, you had to play hide‑and‑seek across multiple tables. Thanks our ESKAPE tools......... We ported so many ideas all around!!!!!

Now: Each isolate gets its own interactive box with:

• 🏷️ Typing badges (ST, Serotype, Phylogroup, CHtype)
• 📊 Separate tables per database (AMRfinder, ResFinder, CARD, VFDB, PlasmidFinder, BacMet2, etc.) – horizontally scrollable
• 🔍 Filters – search by sample name or filter by database
• 📈 Full gene hit details (coverage, identity, contig, accession, etc.)

Why it's a game‑changer: You can finally answer "What the heck is in this one isolate?" without opening a million files.

Now you can group genome lists by all typing combinations:

Fixed: Groups now stack vertically (not horizontally). No more squinting at a single line of 47 groups.

You now have full control over hit stringency:

Why: Clinical investigations may need 95% identity and 90% coverage, while environmental surveys might use lower thresholds. You decide.

All HTML reports now include proper tool credit bars with citations for:

• Biopython, FastANI (QC)
• PubMLST, Torsten Seemann (MLST)
• CGE SerotypeFinder, Flemming Scheutz (Serotyping)
• CGE CHTyper, Henrik Hasman (CH Typing)
• EzClermont, Clermont et al. (Phylogrouping)
• NCBI AMRFinderPlus, ABRicate, CARD, ResFinder, etc. (AMR)
• VFDB (Virulence)
• PlasmidFinder, EcoH (Plasmids)
• BacMet2 (Bacmet)

We stand on the shoulders of giants – and we want you to know it.

• 🌟 Overview
• ✨ Core Features
• 🛠️ Installation
• 🎯 Usage Examples
• 📊 Output Structure
• 🎨 Interactive Report Features
• ⚡ Performance Optimized Architecture
• 📊 Sample Output
• 🔗 Integrated External Tools & Dependencies
• 🤖 AI Integration Guide
• 🌍 EcoliDB Lineage Database
• ⚡ Performance Benchmarks
• 📚 Citation
• ❓ Frequently Asked Questions
• 🤝 Contributing
• 🐛 Issue Reporting
• ⚠️ Limitations & Considerations
• 📜 License & Third-Party Components
• 👥 Authors & Affiliations
• 🙏 Acknowledgements
• 🔮 Future Development Roadmap
• 📞 Support & Community

EcoliTyper is a revolutionary bioinformatics pipeline that eliminates workflow fragmentation in E. coli genomic surveillance. By integrating nine core analyses into a single automated workflow, EcoliTyper transforms disconnected genomic data into coherent biological narratives with actionable public health intelligence.

"From fragmented analysis to integrated insight in one command"

Key Achievement: Processes 30 E. coli genomes in ~41 minutes on 16 CPU cores with perfect concordance against reference tools.

• 🧬 Multi-Locus Sequence Typing (MLST) – Achtman scheme with PubMLST database
• 🔍 In silico Serotyping – O and H antigen determination via SerotypeFinder (≥90% coverage/identity)
• 🎯 CH Typing – High-resolution fumC/fimH typing for fine‑scale discrimination
• 🌳 Clermont Phylogrouping – Evolutionary context with 2013 scheme (8 phylogroups)
• 💊 Antimicrobial Resistance Profiling – Dual screening via ABRicate (9 databases) & NCBI AMRFinderPlus
• 🦠 Virulence Factor Detection – Comprehensive pathogenicity assessment
• 📊 Plasmid Replicon Typing – Mobile genetic element characterization
• 🔬 Point Mutation Detection – AMRfinderPlus mutation reporting (gyrA, parC, rpoB, 23S, etc.)
• 📈 Pathotype Classification – Automatic STEC, EPEC, EHEC, EAEC, ETEC, DAEC, EIEC prediction
• 🖼️ Visualisation – Publication‑ready charts (distribution plots, stacked combinations, database statistics)
• 🆕 Hybrid Sample‑Centric Reporter – Interactive isolate boxes with typing badges and filters
• 🎯 Expanded Gene‑Centric Grouping – All pairwise/triple/full typing combinations

• 🔬 Cross‑genome pattern discovery – Automated gene frequency analysis & distribution mapping
• ⚠️ Rule‑based clinical risk assessment – Hierarchical alerting (CARBAPENEMASE > ESBL > COLISTIN‑RES)
• 🌍 Integrated lineage database – Manually curated reference of high‑risk clones (ST131, ST1193, etc.)
• 📈 Population‑level insights – Immediate epidemiological overview of resistance cassettes & virulence profiles

• 🚀 Sequential module execution – Clean terminal output with per‑module headers
• 🎛️ Dynamic resource allocation – Automatic scaling with genome complexity
• ⚖️ Temporary directory isolation – All modules run in /tmp, automatically cleaned up
• 🔄 Robust error handling – Graceful recovery with checkpointing & automated cleanup
• 🐳 Docker & Singularity support – Run without installation, HPC‑friendly

See complete interactive reports generated by EcoliTyper:

Report	Link
Sample‑Centric (isolate boxes)
Gene‑Centric (gene tables + grouping)

Note: Reports may take a few seconds to load. For best experience, download the HTML files and open locally.

Both reports include phylogrouping, Achtman MLST, CH typing, pathotypes, serotypes, Wzi antigens, AMR, virulence, plasmids, biocides, heavy metals, and mutations. The gene‑centric report adds dynamic grouping by ST, phylogroup, CH type, serotype, pathotype, and combinations.

# Create and activate environment
conda create -n ecolityper -c conda-forge -c bioconda ecolityper -y
conda activate ecolityper

# First‑time setup (Conda only)
abricate --setupdb
ecolityper --update-amr-db

# Pull the latest image
docker pull bbeckleyhub/ecolityper:latest

# Run a single genome (files owned by your user – no padlock!)
docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd):/data" \
  bbeckleyhub/ecolityper:latest \
  -i "/data/genome.fna" -o /data/results

# Batch processing
docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd):/data" \
  bbeckleyhub/ecolityper:latest \
  -i "/data/*.fna" -o /data/results --threads 8

Why -u $(id -u):$(id -g)?
It ensures that all output files are owned by your host user – no sudo chown needed, no padlock icons.

# Build or pull the SIF image
singularity pull ecolityper.sif docker://bbeckleyhub/ecolityper:latest

# Run (add `--writable-tmpfs` if `/tmp` is read‑only)
singularity run --writable-tmpfs -B $(pwd):/data ecolityper.sif \
  -i "/data/*.fna" -o /data/output --threads 8

All result files are owned by your HPC user automatically.

ecolityper -i genome.fasta -o results/

ecolityper -i "*.fasta" -o batch_results --threads 8

ecolityper -i isolates/ -o quick_typing --skip-amrfinder --skip-visualization

ecolityper -i "*.fna" -o results \
  --amr-min-identity 0.95 --amr-min-coverage 0.9 --skip-amr-mutations

ecolityper -i "*.fna" -o results \
  --abricate-minid 90 --abricate-mincov 85

ecolityper -i "*.fna" -o results --amr-force-update

ecolityper -i "*.fna" -o results --skip-samplecentric

ecolityper --update-amr-db          # incremental
ecolityper --force-update-amr-db    # full overwrite

ecolityper -i "*.fna" -o results --clean-output

usage: ecolityper -i INPUT -o OUTPUT [options]

Required:
  -i INPUT               Input FASTA file(s) - glob patterns like "*.fna"
  -o OUTPUT              Output directory for all results

Options:
  -t THREADS             Number of threads (default: 2)
  --keep-temp            Do not delete temporary directories (for debugging)
  --update-amr-db        Update AMRfinderPlus database (incremental) and exit
  --force-update-amr-db  Force complete AMR database update and exit

AMRfinderPlus Options:
  --amr-min-identity FLOAT  Minimum identity for AMR hits (0..1)
  --amr-min-coverage FLOAT  Minimum coverage for AMR hits (0..1)
  --skip-amr-mutations      Disable point mutation reporting (enabled by default)
  --amr-force-update        Force update AMR database before analysis

ABRicate Options (New in v1.3.0):
  --abricate-minid INT   Minimum identity for ABRicate hits (0-100, default: 80)
  --abricate-mincov INT  Minimum coverage for ABRicate hits (0-100, default: 80)

Skip Options:
  --skip-fasta-qc        Skip FASTA QC analysis
  --skip-amrfinder       Skip AMRfinderPlus analysis
  --skip-abricate        Skip ABRicate analysis
  --skip-mlst            Skip MLST analysis
  --skip-serotyping      Skip serotyping analysis
  --skip-chtyper         Skip CH typing analysis
  --skip-phylogrouping   Skip phylogrouping analysis
  --skip-lineage         Skip lineage reference generation
  --skip-summary         Skip summary report generation
  --skip-visualization   Skip visualization generation
  --skip-samplecentric   Skip sample-centric hybrid reporter (New in v1.3.0)

Supported FASTA formats: .fna, .fasta, .fa, .fsa

Analysis Modules:
  • FASTA QC (Sequence Quality Control & Statistics)
  • MLST (Multi-Locus Sequence Typing)
  • Serotyping (O and H antigen determination)
  • CH Typing (FumC and FimH typing)
  • Phylogrouping (ezClermont algorithm)
  • ABRicate (Resistance/Virulence/Plasmid screening) – with dynamic thresholds
  • AMRfinderPlus (NCBI AMR gene detection) – with optional thresholds and mutation reporting
  • Sample-Centric Reporter (Interactive isolate boxes) – New in v1.3.0
  • Lineage reference database
  • Summary Reports (HTML summary reports)
  • Visualizations (Charts and visualizations)

results/
├── abricate_results/              # Multi‑database screening (CARD, ResFinder, VFDB, etc.)
├── amrfinder_results/             # NCBI AMRFinderPlus + mutation reports
├── chtyper_results/               # High‑resolution CH typing (FumC:FimH)
├── mlst_results/                  # Multi‑Locus Sequence Typing
├── phylogrouping_results/         # Clermont phylogrouping
├── serotyping_results/            # O:H antigen determination
├── lineage_results/               # EcoliDB lineage reference
├── GENIUS_ECOLI_ULTIMATE_GENE_CENTRIC_REPORTS/               # 🧠 MAIN GENE‑CENTRIC REPORT: genius_ecoli_ultimate_gene_centric_report.html
├── GENIUS_ECOLI_ULTIMATE_SAMPLE_CENTRIC_REPORTS/        # 🆕 SAMPLE‑CENTRIC REPORT:  genius_ecoli_ultimate_sample_centric_report.html interactive isolate boxes (v1.3.0)
└── visualization_results/         # Publication‑ready charts (PNG, SVG, PDF)

Two main reports: GENIUS_ECOLI_ULTIMATE_GENE_CENTRIC_REPORTS/genius_ecoli_ultimate_gene_centric_report.html (gene‑centric) and GENIUS_ECOLI_ULTIMATE_SAMPLE_CENTRIC_REPORTS/genius_ecoli_ultimate_sample_centric_report.html (sample‑centric).

• Sample Overview – MLST, serotype, phylogroup, CH type, pathotype
• AMR & Virulence gene tables – gene‑centric, with genome tags and dynamic grouping
• Mutation tab – all point mutations with grouping by typing
• Pathotype Analysis – prevalence and sample details with EHEC detection
• Plasmid & Bacmet2 – biocide/heavy metal resistance
• Dynamic grouping – reorganise genome lists by MLST, serotype, phylogroup, CH type, or combinations (now supports all pairwise/triple/full combinations in v1.3.0)
• 🆕 Sample‑centric isolate boxes – interactive per‑isolate boxes with full hit details, filters, and typing badges (v1.3.0)
• CSV/JSON export – all data exportable for downstream analysis
• AI‑friendly HTML structure – upload to ChatGPT, Claude, or Gemini for instant insights

EcoliTyper integrates several powerful open‑source tools and databases. They are automatically installed via Conda.

EcoliTyper reports are structured for easy AI analysis.

1. Open either genius_ecoli_ultimate_gene_centric_report.html (gene‑centric) or the new genius_ecoli_ultimate_sample_centric_report.html (sample‑centric) in your browser
2. Select any text (table, paragraph, or entire section)
3. Right‑click → “Ask AI” (or use your AI extension)
4. Ask questions like:
   • “What is the clinical significance of ST95?”
   • “Which samples carry ESBL genes?”
   • “Summarise the resistance profile of sample XYZ”
   • “Show me all isolates with both ESBL and colistin resistance”

• ChatGPT Plus / Claude / Gemini accept file uploads
• Ask: “From this report, create a summary table of pathotypes and their associated STs”
• For v1.3.0: upload the sample‑centric report and ask “Show me which isolates carry stx2 and eae genes”

EcoliTyper includes EcoliDB, a manually curated reference of high‑risk E. coli clones (ST131, ST1193, ST95, etc.) with pathotype, serotype, phylogroup, and risk level. The database is automatically generated as lineage_results/ecoli_comprehensive_reference.html.

Validation: 100% concordance with standalone tools (mlst, SerotypeFinder, ezClermont).

If you use EcoliTyper in your research, please cite the main paper and the relevant third‑party tools:

Beckley B, Amarh V. EcoliTyper: a species‑optimized computational pipeline for comprehensive genotyping and surveillance of Escherichia coli. BMC Bioinformatics. 2026.
DOI: 10.1186/s12859-026-06529-6

Roer L, et al. CHTyper, a Web Tool for Subtyping of Extraintestinal Pathogenic Escherichia coli Based on the fumC and fimH Alleles. J Clin Microbiol. 2018;56(4):e00063-18.
DOI: 10.1128/JCM.00063-18

Feldgarden M, et al. AMRFinderPlus and the Reference Gene Catalog facilitate examination of the genomic links among antimicrobial resistance, stress response, and virulence. Sci Rep. 2021;11(1):12728.
DOI: 10.1038/s41598-021-91456-0

McArthur AG, et al. The comprehensive antibiotic resistance database. Antimicrob Agents Chemother. 2013;57(7):3348-57.
DOI: 10.1128/AAC.00419-13

Gupta SK, et al. ARG-ANNOT, a new bioinformatic tool to discover antibiotic resistance genes in bacterial genomes. Antimicrob Agents Chemother. 2014;58(1):212-20.
DOI: 10.1128/AAC.01310-13

Doster E, et al. MEGARes 2.0: a database for classification of antimicrobial drug, biocide and metal resistance determinants in metagenomic sequence data. Nucleic Acids Res. 2020;48(D1):D561-D569.
DOI: 10.1093/nar/gkz1010

Chen L, et al. VFDB 2012 update: toward the genetic diversity and molecular evolution of bacterial virulence factors. Nucleic Acids Res. 2012;40(D1):D641-5.
DOI: 10.1093/nar/gkr989

Carattoli A, et al. In silico detection and typing of plasmids using PlasmidFinder and plasmid multilocus sequence typing. Antimicrob Agents Chemother. 2014;58(7):3895-903.
DOI: 10.1128/AAC.02412-14

Ingle DJ, et al. In silico serotyping of E. coli from short read data identifies limited novel O‑loci but extensive diversity of O:H serotype combinations within and between pathogenic lineages. Microb Genom. 2016;2(7):e000064.
DOI: 10.1099/mgen.0.000064

Pal C, et al. BacMet: antibacterial biocide and metal resistance genes database. Nucleic Acids Res. 2014;42(D1):D737-43.
DOI: 10.1093/nar/gkt1252

Cock PJ, et al. Biopython: freely available Python tools for computational molecular biology and bioinformatics. Bioinformatics. 2009;25(11):1422-3.
DOI: 10.1093/bioinformatics/btp163

Jolley KA, et al. Open‑access bacterial population genomics: BIGSdb software, the PubMLST.org website and their applications. Wellcome Open Res. 2018;3:124.
DOI: 10.12688/wellcomeopenres.14826.1

Florensa AF, et al. ResFinder – an open online resource for identification of antimicrobial resistance genes in next‑generation sequencing data and prediction of phenotypes from genotypes. Microb Genom. 2022;8(1):000748.
DOI: 10.1099/mgen.0.000748

Seemann T. MLST: Scan contig files against PubMLST typing schemes. GitHub repository.

Seemann T. ABRicate: mass screening of contigs for antibiotic resistance genes. GitHub repository.

Camacho C, et al. BLAST+: architecture and applications. BMC Bioinformatics. 2009;10:421.
DOI: 10.1186/1471-2105-10-421

Clausen PTLC, et al. Rapid and precise alignment of raw reads against redundant databases with KMA. BMC Bioinformatics. 2018;19:307.
DOI: 10.1186/s12859-018-2336-6

Joensen KG, et al. Rapid and easy in silico serotyping of Escherichia coli using whole genome sequencing (WGS) data. J Clin Microbiol. 2015;53(8):2410-2426.
DOI: 10.1128/JCM.00008-15

Clermont O, et al. The Clermont Escherichia coli phylo‑typing method revisited: improvement of specificity and detection of new phylo‑groups. Environ Microbiol Rep. 2013;5(1):58-65.
DOI: 10.1111/1758-2229.12019

Q: What makes EcoliTyper different?
A: Single‑command integration of 9 analyses (MLST, serotyping, CH typing, phylogrouping, AMR, virulence, plasmids, mutations, pathotype) + cross‑genome patterns + dynamic grouping + curated lineage database + new sample‑centric reporting (v1.3.0).

Q: What's the difference between gene‑centric and sample‑centric reports?
A: Gene‑centric shows each gene with all genomes that carry it – great for epidemiology and outbreak tracking. Sample‑centric (new in v1.3.0) shows each isolate as an interactive box with all its genes – perfect for clinical interpretation and individual isolate inspection.

Q: Can I use it for other bacteria?
A: No – optimised for E. coli only. But we have StaphScope for S. aureus and other ESCAPE AMR modules coming soon.

Q: How much disk space is needed?
A: ~5–10 GB for Conda + databases, plus ~10–50 MB per genome for results.

Q: How accurate is it?
A: 100% concordance with standalone reference tools (mlst, SerotypeFinder, ezClermont, AMRFinderPlus) on validated strains.

Q: How long does it take?
A: 1–6 min per genome (2 cores) or ~41 min for 30 genomes (16 cores).

Q: Can I run only some modules?
A: Yes – use skip flags like --skip-amrfinder, --skip-visualization, --skip-samplecentric.

Q: How do I adjust AMR/ABRicate stringency?
A: Use --amr-min-identity, --amr-min-coverage (AMR) and --abricate-minid, --abricate-mincov (ABRicate) – new in v1.3.0.

Q: Where are the main reports?
A: Gene‑centric: GENIUS_ECOLI_ULTIMATE_GENE_CENTRIC_REPORTS/genius_ecoli_ultimate_gene_centric_report.html.
Sample‑centric (new): GENIUS_ECOLI_ULTIMATE_SAMPLE_CENTRIC_REPORTS/genius_ecoli_ultimate_sample_centric_report.html.

Q: Can I use the HTML report with ChatGPT/Claude?
A: Yes – upload either HTML file and ask questions about your data.

Q: What if I find a novel ST or missing lineage?
A: Report it via GitHub issues – we actively maintain the database.

Q: How do I update AMR databases?
A: Run ecolityper --update-amr-db (incremental) or --force-update-amr-db (full).

Q: Where can I get help or report bugs?
A: GitHub Issues or email brownbeckley94@gmail.com.

We welcome contributions!

1. Fork the repo
2. Create a feature branch
3. Commit your changes
4. Push and open a Pull Request

Areas: database expansion, new typing schemes, performance, visualisations, documentation.

EcoliTyper core code is MIT licensed. Third‑party tools (MLST, ABRicate, AMRFinderPlus, SerotypeFinder, etc.) are subject to their own licenses (GPL, Apache, Public Domain, etc.). By using EcoliTyper you agree to comply with those licenses.

• Brown Beckley – Creator & Lead Developer
  University of Ghana Medical School & KNUST
  📧 brownbeckley94@gmail.com

• Dr. Vincent Amarh – Lead Advisor
  University of Ghana Medical School

• GitHub Issues: https://github.com/bbeckley-hub/EcoliTyper/issues
• Email: brownbeckley94@gmail.com
• Docker Hub: bbeckleyhub/ecolityper