bbeckleyhub/ecolityper repository overview

⁠🐳 EcoliTyper Docker Image

Run the complete E. coli typing pipeline with zero installation – just Docker.

⁠🧬 What is EcoliTyper?

EcoliTyper is a comprehensive bioinformatics pipeline for complete genomic characterization of Escherichia coli. It integrates nine core typing analyses into a single automated workflow:

• 🧬 MLST – Multi‑Locus Sequence Typing (Achtman scheme)
• 🔍 Serotyping – O and H antigen determination
• 🎯 CH Typing – High‑resolution fumC/fimH typing
• 🌳 Phylogrouping – Clermont scheme (8 phylogroups)
• 💊 AMRFinderPlus – NCBI AMR gene detection with mutation reporting
• 🦠 ABRicate – Resistance, virulence, and plasmid screening (9 databases)
• 🧬 Plasmid Replicon Typing – Mobile genetic element characterization
• 🧠 Pathotype Classification – STEC, EPEC, EHEC, EAEC, ETEC, DAEC, EIEC
• 📊 Interactive Reports – HTML dashboards with dynamic grouping & visualization

📖 Full documentation, examples, and Conda installation instructions are available on the GitHub repository:
👉 https://github.com/bbeckley-hub/EcoliTyper⁠

⁠📦 What’s inside this Docker image

• ✅ Full EcoliTyper pipeline (all modules)
• ✅ All dependencies pre‑installed (Conda environment, Perl, BLAST, ABRicate, etc.)
• ✅ ABRicate databases pre‑configured (abricate --setupdb already run)
• ✅ AMRFinderPlus database pre‑downloaded
• ✅ No need for Conda, no manual setup, no "read‑only filesystem" errors
• ✅ Optimized for Linux/amd64 (works on Apple Silicon via emulation)

⁠🚀 Quick Start

⁠Pull the image

docker pull bbeckleyhub/ecolityper:latest

⁠Run on a single FASTA file

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd):/data" \
  bbeckleyhub/ecolityper:latest \
  -i "/data/genome.fna" -o /data/results

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.

⁠Run on all FASTA files in the current directory

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

⁠📖 Detailed Usage

⁠Basic syntax

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd):/data" \
  bbeckleyhub/ecolityper:latest \
  [ECOLITYPER_OPTIONS]

⁠All EcoliTyper options work

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

⁠Using custom threads

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd):/data" \
  bbeckleyhub/ecolityper:latest \
  -i "/data/*.fna" -o /data/results -t 16

⁠AMR with custom thresholds & mutation reporting

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd):/data" \
  bbeckleyhub/ecolityper:latest \
  -i "/data/*.fna" -o /data/results \
  --amr-min-identity 0.95 --amr-min-coverage 0.9 --skip-amr-mutations

⁠Force AMR database update before analysis

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd):/data" \
  bbeckleyhub/ecolityper:latest \
  -i "/data/*.fna" -o /data/results --amr-force-update

⁠Standalone database update

docker run --rm bbeckleyhub/ecolityper:latest --update-amr-db          # incremental
docker run --rm bbeckleyhub/ecolityper:latest --force-update-amr-db    # full overwrite

⁠🔧 Handling File Permissions (The "Padlock" Issue)

By default, Docker runs as root inside the container. Any files written to your mounted directory will be owned by root:root.
Here's how to avoid it:

⁠✅ Recommended: Run with your user ID

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

All output files are owned by your user – no sudo needed.

⁠Alternative: Change ownership after the run

sudo chown -R $USER:$USER ./results

⁠🧪 Testing Your Docker Setup

⁠Check help message

docker run --rm bbeckleyhub/ecolityper:latest -h

⁠Verify ABRicate databases are installed

docker run --rm --entrypoint /bin/bash bbeckleyhub/ecolityper:latest -c "abricate --list | head -5"

Expected output: list of databases (ncbi, card, vfdb, etc.)

⁠🖥️ Singularity for HPC (no sudo, correct ownership)

On HPC clusters that support Singularity/Apptainer⁠, you can run EcoliTyper without sudo and output files will be owned by your user automatically.

⁠Option A: Direct pull (if network allows)

singularity pull ecolityper.sif docker://bbeckleyhub/ecolityper:latest
singularity run --writable-tmpfs -B $(pwd):/data ecolityper.sif \
  -i "/data/*.fna" -o /data/results

⁠Option B: Convert from a local Docker image

If you encounter network errors, convert an existing Docker image on a machine with Docker:

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

Transfer ecolityper.sif to your HPC and run:

singularity run --writable-tmpfs -B $(pwd):/data ecolityper.sif \
  -i "/data/*.fna" -o /data/results --threads 8

⁠Explanation of flags

⁠📁 Output Structure

After a successful run, your output directory will contain:

results/
├── abricate_results/              # Multi‑database screening (10 DBs)
├── 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
├── summary_results/               # 🧠 MAIN REPORT: genius_ecoli_ultimate_report.html
├── visualization_results/         # Publication‑ready charts (PNG, SVG, PDF)
└── ecolityper_run.log             # Detailed run log

⁠🎨 Interactive Report Features

• 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
• CSV/JSON export – all data exportable for downstream analysis
• AI‑friendly HTML structure – upload to ChatGPT, Claude, or Gemini for instant insights

⁠🔗 Integrated External Tools & Dependencies

EcoliTyper integrates several powerful open‑source tools and databases:

⁠🤖 AI Integration Guide

EcoliTyper reports are structured for easy AI analysis.

⁠Quick Start

1. Open genius_ecoli_ultimate_report.html 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"

⁠Upload the HTML file directly

• ChatGPT Plus / Claude / Gemini accept file uploads
• Ask: "From this report, create a summary table of pathotypes and their associated STs"

⁠🌍 EcoliDB Lineage Database

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.

⁠⚡ Performance Benchmarks

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

⁠📚 Citation

If you use EcoliTyper in your research, please cite the main paper:

⁠🧬 EcoliTyper – Main Citation

⁠🔬 Third‑Party Tools

When publishing results obtained with EcoliTyper, please also cite the relevant third‑party tools:

• CHTyper: Roer L, et al. J Clin Microbiol. 2018. DOI: 10.1128/JCM.00063-18⁠
• AMRFinderPlus: Feldgarden M, et al. Sci Rep. 2021. DOI: 10.1038/s41598-021-91456-0⁠
• Serotyping: Joensen KG, et al. J Clin Microbiol. 2015. DOI: 10.1128/JCM.00008-15⁠
• Clermont Phylotyping: Clermont O, et al. Environ Microbiol Rep. 2013. DOI: 10.1111/1758-2229.12019⁠

⁠❓ Frequently Asked Questions

Q: Why are output files owned by root?
A: Docker containers run as root by default. Use -u $(id -u):$(id -g) to fix this.

Q: Can I use --user with the Docker command?
A: Yes! The recommended command uses -u $(id -u):$(id -g) – it works perfectly.

Q: How large is the image?
A: Approximately 5.4 GB (includes Conda, all dependencies, and ABRicate databases).

Q: Can I run this on Windows / macOS?
A: Yes, with Docker Desktop. Mount paths must be absolute (e.g., -v /c/Users/name/data:/data on Windows Git Bash).

Q: Does it work on ARM (Apple Silicon)?
A: The image is built for linux/amd64. On Apple Silicon, Docker will use emulation (may be slower).

Q: How do I update AMR databases?
A: Run docker run --rm bbeckleyhub/ecolityper:latest --update-amr-db.

Q: Where is the main report?
A: summary_results/genius_ecoli_ultimate_report.html – open in any browser.

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

⁠📜 License & Third‑Party Components

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.

⁠👥 Authors & Affiliations

• Brown Beckley – Creator & Lead Developer
  University of Ghana Medical School & KNUST
  📧 [email protected]⁠

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

⁠🔗 Links

• GitHub repository (full documentation, Conda install, examples):
  https://github.com/bbeckley-hub/EcoliTyper⁠
• Docker Hub (image registry):
  https://hub.docker.com/r/bbeckleyhub/ecolityper⁠
• Report issues:
  https://github.com/bbeckley-hub/EcoliTyper/issues⁠