KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #codex #typescript #developer-tools #ai-agents #deepseek-harness #claude-code #ai-agent #cli #react #mcp

EcoliTyper

★ 28 Open GitHub ↗

EcoliTyper: A species-optimized computational pipeline for comprehensive genotyping and surveillance of Escherichia coli. Perfect for clinical microbiology, outbreak investigations, and genomic research.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

### 🧬 A species‑optimized computational pipeline for comprehensive genotyping and surveillance of **_Escherichia coli_**

**Complete *E. coli* genomic analysis in minutes — not hours**

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://raw.githubusercontent.com/bbeckley-hub/EcoliTyper/main/CODE_OF_CONDUCT.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-1.3.0-blue)](https://github.com/bbeckley-hub/EcoliTyper)
[![GitHub stars](https://img.shields.io/github/stars/bbeckley-hub/EcoliTyper)](https://github.com/bbeckley-hub/EcoliTyper/stargazers)
[![Docker Pulls](https://img.shields.io/docker/pulls/bbeckleyhub/ecolityper)](https://hub.docker.com/r/bbeckleyhub/ecolityper)
[![Docker Image Size](https://img.shields.io/docker/image-size/bbeckleyhub/ecolityper/latest)](https://hub.docker.com/r/bbeckleyhub/ecolityper)
[![Docker Version](https://img.shields.io/docker/v/bbeckleyhub/ecolityper?sort=semver)](https://hub.docker.com/r/bbeckleyhub/ecolityper)
[![Article](https://img.shields.io/badge/BMC%20Bioinformatics-10.1186%2Fs12859--026--06529--6-brightgreen)](https://doi.org/10.1186/s12859-026-06529-6)

[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/bbeckley-hub/EcoliTyper/main/LICENSE)
[![GitHub Issues](https://img.shields.io/github/issues/bbeckley-hub/EcoliTyper)](https://github.com/bbeckley-hub/EcoliTyper/issues)
![Latest Release Date](https://anaconda.org/bioconda/ecolityper/badges/latest_release_relative_date.svg)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://raw.githubusercontent.com/bbeckley-hub/EcoliTyper/main/)
[![Stage](https://img.shields.io/badge/status-active-brightgreen)](https://raw.githubusercontent.com/bbeckley-hub/EcoliTyper/main/)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/ecolityper/badges/downloads.svg)](https://anaconda.org/bioconda/ecolityper)

[![Powered by 🧠](https://img.shields.io/badge/powered%20by-science%20🔬-purple)](https://github.com/bbeckley-hub/EcoliTyper)
[![Coffee](https://img.shields.io/badge/built%20with-%E2%98%95%20coffee-orange)](https://github.com/bbeckley-hub/EcoliTyper)
[![Made with ❤️](https://img.shields.io/badge/made%20with-%E2%9D%A4%EF%B8%8F-red)](https://github.com/bbeckley-hub/EcoliTyper)
[![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badges/)
[![Made for Research](https://img.shields.io/badge/made%20for-Research-0066cc.svg)](https://github.com/bbeckley-hub)

[![Documentation](https://img.shields.io/badge/docs-mkdocs-526CFE?logo=materialformkdocs)](https://bbeckley-hub.github.io/EcoliTyper)
[![RST Badge](https://img.shields.io/badge/documentation-RST-4CAF50.svg)](https://www.sphinx-doc.org/)
[![Last Commit](https://img.shields.io/github/last-commit/bbeckley-hub/EcoliTyper)](https://github.com/bbeckley-hub/EcoliTyper/commits)
[![Contributors](https://img.shields.io/github/contributors/bbeckley-hub/EcoliTyper)](https://github.com/bbeckley-hub/EcoliTyper/graphs/contributors)
[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![CI](https://img.shields.io/github/actions/workflow/status/bbeckley-hub/EcoliTyper/ci.yml?branch=main&label=CI)](https://github.com/bbeckley-hub/EcoliTyper/actions)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/bbeckley-hub/EcoliTyper/tests)
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/bbeckley-hub/EcoliTyper)

[![Conda](https://img.shields.io/badge/conda-✓-green.svg)](https://docs.conda.io/en/latest/)
[![Sample Report](https://img.shields.io/badge/🔗-Open_Sample_Report-red)](https://htmlpreview.github.io/?https://bbeckley-hub.github.io/EcoliTyper/#summary)
![Profile Views](https://komarev.com/ghpvc/?username=bbeckley-hub&label=Profile%20Views&color=0e75b6&style=flat)
[![Google Scholar](https://img.shields.io/badge/Google%20Scholar-Profile-4285F4?style=flat&logo=googlescholar&logoColor=white)](https://scholar.google.com/citations?user=CYNOsqIAAAAJ&hl=en)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Profile-0A66C2?style=flat&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/brown-beckley-190315319)

![GitHub stats](https://github-readme-stats.vercel.app/api?username=bbeckley-hub&show_icons=true&theme=radical)
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=bbeckley-hub&layout=compact&theme=radical)
[![GitHub Streak](https://streak-stats.demolab.com?user=bbeckley-hub&theme=radical&date_format=j%20M%5B%20Y%5D)](https://git.io/streak-stats)

**Perfect for clinical microbiology, outbreak investigations, and genomic research.**

</div>

---

## 🆕 What's New in v1.3.0 (July 2026)

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

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

### 🧬 1. Hybrid Sample‑Centric Reporter (NEW MODULE)

**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.

### 🎯 2. Expanded Gene‑Centric Grouping

Now you can group genome lists by **all** typing combinations:

| Group Type | Example |
|------------|---------|
| Single | ST, Serotype, Phylogroup, CHtype |
| Pairwise | ST+Serotype, ST+CHtype, Serotype+Phylogroup, Serotype+CHtype, Phylogroup+CHtype |
| Triple | ST+Serotype+Phylogroup, ST+Serotype+CHtype, ST+Phylogroup+CHtype |
| **Full Monty** | ST+Serotype+Phylogroup+CHtype |

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

### ⚙️ 3. Dynamic Threshold Flags

You now have **full control** over hit stringency:

| Tool | Flags | Default |
|------|-------|---------|
| **ABRicate** | `--abricate-minid`, `--abricate-mincov` | 80, 80 |
| **AMRfinderPlus** | `--amr-min-identity`, `--amr-min-coverage` | 0.8, 0.8 |

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

### 🧩 4. New Modules Added

| Module | What It Does |
|--------|--------------|
| `sample_centric_module` | The "Isolate Paparazzi" – interactive boxes, filters, badges |
| `gene_centric_module` | Classic gene‑centric reporter with **all** grouping combinations |

### 🐛 5. Bug Fixes

| Issue | Fix |
|-------|-----|
| Genome tags grouping horizontally | Added `.genome-group` CSS with `width: 100%` |
| Missing grouping combinations | Extended `getTypingValue()` JS function |
| SerotypeFinder crash on "No hit found" | Added type checking in `_parse_sample_results` |
| CHTyper `dictionary changed size during iteration` | Fixed `for hit_id in list(keys)` in `blaster.py` |
| HTML parsing in sample‑centric module | Strictly uses TSV summaries |
| AMR database >100 MB on GitHub | Excluded from repo; users download via `--update-amr-db` |

### 🎛️ 6. New Orchestrator Flags

| Flag | Description |
|------|-------------|
| `--skip-samplecentric` | Skip the new sample‑centric reporter |
| `--abricate-minid` | Minimum identity for ABRicate (0-100) |
| `--abricate-mincov` | Minimum coverage for ABRicate (0-100) |
| `--amr-min-identity` | Minimum identity for AMR (0-1) |
| `--amr-min-coverage` | Minimum coverage for AMR (0-1) |

### 📊 7. Scientific Credit Bars

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.**

---

## 📋 Table of Contents

- [🌟 Overview](#-overview)
- [✨ Core Features](#-core-features)
- [🛠️ Installation](#️-installation)
- [🎯 Usage Examples](#-usage-examples)
- [📊 Output Structure](#-output-structure)
- [🎨 Interactive Report Features](#-interactive-report-features)
- [⚡ Performance Optimized Architecture](#-performance-optimized-architecture)
- [📊 Sample Output](#-sample-output)
- [🔗 Integrated External Tools & Dependencies](#-integrated-external-tools--dependencies)
- [🤖 AI Integration Guide](#-ai-integration-guide)
- [🌍 EcoliDB Lineage Database](#-ecolityper-ecolidb-lineage-database)
- [⚡ Performance Benchmarks](#-performance-benchmarks)
- [📚 Citation](#-citation)
- [❓ Frequently Asked Questions](#-frequently-asked-questions)
- [🤝 Contributing](#-contributing)
- [🐛 Issue Reporting](#-issue-reporting)
- [⚠️ Limitations & Considerations](#️-limitations--considerations)
- [📜 License & Third-Party Components](#-license--third-party-components)
- [👥 Authors & Affiliations](#-authors--affiliations)
- [🙏 Acknowledgements](#-acknowledgements)
- [🔮 Future Development Roadmap](#-future-development-roadmap)
- [📞 Support & Community](#-support--community)

---

## 🌟 Overview

**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"*

### 🚀 The EcoliTyper Advantage

| Traditional Workflow 😫 | EcoliTyper Solution 🎉 |
|------------------------|-----------------------|
| 9+ independent tools required | **Single unified pipeline** |
| Manual data integration & synthesis | **Automated cross-genome pattern discovery** |
| Hours of manual curation | **Intelligent risk assessment & alerting** |
| Disconnected epidemiological context | **Integrated lineage database of high-risk clones** |
| Multiple output formats to reconcile | **Consolidated HTML report + structured data (TSV/JSON)** |
| Complex installation & dependencies | **Self-contained Conda package** |
| No point mutation tracking | **AMRfinderPlus mutation reporting** |
| No pathotype classification | **Automated pathotype prediction (STEC, EPEC, EHEC, EAEC, ETEC, DAEC, EIEC)** |
| One‑size‑fits‑all thresholds | **Dynamic AMR/ABRicate thresholds** |

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

---

## ✨ Core Features

### 🧩 Comprehensive *E. coli* Typing Suite
- **🧬 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

### 🧠 Intelligent Analytics Layer
- **🔬 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

### ⚡ Performance Optimized Architecture
- **🚀 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

---
## 📊 Sample Output

See complete interactive reports generated by EcoliTyper:

| Report | Link |
|--------|------|
| **Sample‑Centric** (isolate boxes) | [![View Sample‑Centric Report](https://img.shields.io/badge/📋-View_Report-8B5CF6?style=for-the-badge)](https://bbeckley-hub.github.io/EcoliTyper/genius_ecoli_ultimate_sample_centric_report.html) |
| **Gene‑Centric** (gene tables + grouping) | [![View Gene‑Centric Report](https://img.shields.io/badge/🧬-View_Report-2193B0?style=for-the-badge)](https://bbeckley-hub.github.io/EcoliTyper/genius_ecoli_ultimate_gene_centric_report.html#summary) |

> **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.

---

## 🛠️ Installation

### Quick Install (Conda – Recommended)

```bash
# 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
```

### 🐳 Docker (No Installation)

```bash
# 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.

### 🖥️ Singularity (HPC, no `sudo`)

```bash
# 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.

---

## 🎯 Usage Examples

### Basic Single Genome Analysis
```bash
ecolityper -i genome.fasta -o results/
```

### High‑Throughput Batch Processing
```bash
ecolityper -i "*.fasta" -o batch_results --threads 8
```

### Skip Modules for Faster Processing
```bash
ecolityper -i isolates/ -o quick_typing --skip-amrfinder --skip-visualization
```

### AMR with Custom Thresholds & Mutation Reporting
```bash
ecolityper -i "*.fna" -o results \
  --amr-min-identity 0.95 --amr-min-coverage 0.9 --skip-amr-mutations
```

### ABRicate with Custom Thresholds (New in v1.3.0)
```bash
ecolityper -i "*.fna" -o results \
  --abricate-minid 90 --abricate-mincov 85
```

### Force AMR Database Update Before Analysis
```bash
ecolityper -i "*.fna" -o results --amr-force-update
```

### Skip Sample‑Centric Reporter (New in v1.3.0)
```bash
ecolityper -i "*.fna" -o results --skip-samplecentric
```

### Standalone Database Update
```bash
ecolityper --update-amr-db          # incremental
ecolityper --force-update-amr-db    # full overwrite
```

### Clean Output Directory Before Run
```bash
ecolityper -i "*.fna" -o results --clean-output
```

### Complete Command Reference

```text
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)
```

---

## 📊 Output Structure

```
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).

---

## 🎨 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 (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

---

## 🔗 Integrated External Tools & Dependencies

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

| Tool/Database | Purpose | License |
|---------------|---------|---------|
| **MLST** | Multi‑locus sequence typing | GPL v2 |
| **ABRicate** | Mass screening for resistance/virulence | GPL v2 |
| **AMRFinderPlus** | AMR gene detection + mutations | Public Domain |
| **SerotypeFinder** | O:H antigen typing | Apache 2.0 |
| **CHTyper DB** | *fumC/fimH* typing | Free for research |
| **ezClermont** | Phylogrouping | MIT |
| **CARD, ResFinder, VFDB, etc.** | Databases (via ABRicate) | Free for research |
| **PlasmidFinder** | Plasmid replicon typing | Free for research |
| **BacMet2** | Biocide/heavy metal resistance | Free for research |

---

## 🤖 AI Integration Guide

EcoliTyper reports are structured for easy AI analysis.

### Quick Start
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”

### 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”
- For v1.3.0: upload the sample‑centric report and ask “Show me which isolates carry stx2 and eae genes”

---

## 🌍 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

| Scenario | Genomes | Time | Hardware |
|----------|---------|------|----------|
| Standard Workstation | 30 | 80‑150 min | 2 cores, 8GB RAM |
| High‑Performance Server | 30 | **41 min** | 16 cores, 16GB RAM |
| Single Genome | 1 | 1‑6 min | Variable |

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

---

## 📚 Citation

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

### 🧬 EcoliTyper – Main Citation

> 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](https://doi.org/10.1186/s12859-026-06529-6)

### 🔬 CHTyper
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](https://doi.org/10.1128/JCM.00063-18)

### 🧬 AMRFinderPlus
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](https://doi.org/10.1038/s41598-021-91456-0)

### 🛡️ CARD
McArthur AG, et al. The comprehensive antibiotic resistance database. *Antimicrob Agents Chemother*. 2013;57(7):3348-57.  
DOI: [10.1128/AAC.00419-13](https://doi.org/10.1128/AAC.00419-13)

### 🧬 ARG-ANNOT
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](https://doi.org/10.1128/AAC.01310-13)

### 🌊 MEGARes 2.0
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](https://doi.org/10.1093/nar/gkz1010)

### 🦠 VFDB
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](https://doi.org/10.1093/nar/gkr989)

### 🧬 PlasmidFinder
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](https://doi.org/10.1128/AAC.02412-14)

### 🔬 EcoH (serotyping)
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](https://doi.org/10.1099/mgen.0.000064)

### 🧪 BacMet
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](https://doi.org/10.1093/nar/gkt1252)

### 🐍 Biopython
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](https://doi.org/10.1093/bioinformatics/btp163)

### 🌐 PubMLST / BIGSdb
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](https://doi.org/10.12688/wellcomeopenres.14826.1)

### 🔍 ResFinder
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](https://doi.org/10.1099/mgen.0.000748)

### 🔧 MLST (Seemann)
Seemann T. MLST: Scan contig files against PubMLST typing schemes. [GitHub repository](https://github.com/tseemann/mlst).

### 📦 ABRicate
Seemann T. ABRicate: mass screening of contigs for antibiotic resistance genes. [GitHub repository](https://github.com/tseemann/abricate).

### ⚡ BLAST+
Camacho C, et al. BLAST+: architecture and applications. *BMC Bioinformatics*. 2009;10:421.  
DOI: [10.1186/1471-2105-10-421](https://doi.org/10.1186/1471-2105-10-421)

### 🔬 KMA
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](https://doi.org/10.1186/s12859-018-2336-6)

### 🩺 E. coli Serotyping (Joensen)
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](https://doi.org/10.1128/JCM.00008-15)

### 🌿 Clermont Phylo‑typing
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](https://doi.org/10.1111/1758-2229.12019)

---

## ❓ Frequently Asked Questions

**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.

---

## 🤝 Contributing

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.

---

## 📜 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  
  📧 brownbeckley94@gmail.com

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

---

## 🔮 Future Development Roadmap

| Quarter | Goal |
|---------|------|
| **Q3 2026** | Raw read integration (fastq → assemblies + typing) |
| **Q4 2026** | Real‑time database updates, enhanced visualisation dashboard |
| **2027+** | AI/ML predictive models, web interface, global surveillance integration |

---

## 📞 Support & Community

- **GitHub Issues**: [https://github.com/bbeckley-hub/EcoliTyper/issues](https://github.com/bbeckley-hub/EcoliTyper/issues)
- **Email**: brownbeckley94@gmail.com
- **Docker Hub**: [bbeckleyhub/ecolityper](https://hub.docker.com/r/bbeckleyhub/ecolityper)

---

## ⭐ Star us on GitHub if you find EcoliTyper useful!

*Transforming fragmented genomic surveillance into integrated public health intelligence* 🧬✨

**“From sequences to surveillance in one command”**

---

**Join the Fight Against Antimicrobial Resistance**

We invite researchers, clinicians, and public health professionals to collaborate – share regional epidemiological data, validate the database, and advance AMR surveillance together.

</div>

EcoliTyper

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README