gmlst

gmlst is a fast Python 3.12 CLI for bacterial genome typing with classical MLST, large cgMLST and wgMLST schemes, and scheme-free discovery workflows. It supports assembled genomes and raw reads, several alignment backends, multiple public data providers, custom local schemes, offline cache reuse, and local MST visualization from one command-line interface.

English | 简体中文

Features

• 🧬 Broad typing support: run gmlst typing mlst, gmlst typing cgmlst, and gmlst typing tgmlst from the same CLI.
• ⚡ Multiple backends: use BLAST+, KMA, minimap2, MUMmer4, with built-in exact-hash pre-resolution for cgMLST workflows.
• 🧫 FASTA and FASTQ input: type assembled genomes and paired-end raw reads with backend-aware handling.
• 🗂️ Multiple providers: work with PubMLST, Pasteur BIGSdb, Enterobase, cgmlst.org, and local custom schemes.
• 🧠 Smart cgMLST modes: choose standard, chew-fast, chew-ultrafast, chew-bsr, or chew-balanced depending on speed and evidence needs.
• 🆕 Novel allele workflow: detect novel alleles, extract novel profiles, and build custom laboratory databases.
• 🔍 Scheme-free typing: run tgmlst for de novo allele discovery without a preselected public scheme.
• 📦 Rich outputs: export tsv, json, pretty, and GrapeTree-compatible tables.
• 🌐 Local visualization: launch a Flask + Vue web app with gmlst visual web to inspect MST results locally.
• 💾 Cache-first operation: downloaded schemes and built indexes are reused for offline or repeated runs.
• 🧵 Batch processing: use sample-level workers and backend threads for high-throughput workflows.
• 🧬 CDS-aware calling: cgMLST workflows can use Pyrodigal for CDS prediction and chewBBACA-compatible classification paths.

Installation

Option 1, pixi, recommended

Pixi installs Python, external bioinformatics tools, and the editable package in one environment.

curl -fsSL https://pixi.sh/install.sh | bash
git clone https://github.com/indexofire/gmlst.git
cd gmlst
pixi install
pixi run gmlst --version

Option 2, pip

Use this if you already manage your own Python and system tools.

python3 -m venv .venv
source .venv/bin/activate
pip install gmlst

# Install external tools separately, for example with conda or mamba
conda install -c bioconda blast minimap2 mummer4 mmseqs2 prodigal kma kmc samtools

Option 3, from source

git clone https://github.com/indexofire/gmlst.git
cd gmlst
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
gmlst --help

Option 4, Docker

All tools pre-installed, no Python or conda setup needed.

docker pull indexofire/gmlst:latest

# Type a sample
docker run --rm -v $(pwd):/data indexofire/gmlst:latest \
  typing mlst -s saureus_1 /data/sample.fasta

# Web visualization
docker run --rm -p 8787:8787 -v $(pwd):/data indexofire/gmlst:latest \
  visual web --host 0.0.0.0 --port 8787

External tools managed by pixi

• blast >=2.14
• minimap2 >=2.26
• mummer4 >=4.0
• mmseqs2 >=15
• prodigal >=2.6
• kma >=1.6.8
• kmc >=3.2.4
• samtools >=1.23.1

Python package requirements

• click
• flask
• requests
• rich
• xxhash
• pyyaml
• pyrodigal

Quick Start

1. Browse and download a scheme

# List cached and available schemes
gmlst scheme list

# Restrict to one provider
gmlst scheme list -p pubmlst

# Download a scheme to the local cache
gmlst scheme download -s saureus_1

2. Type one sample

# MLST on an assembled genome
gmlst typing mlst -s saureus_1 sample.fasta

# MLST on paired-end reads
gmlst typing mlst -s saureus_1 -b minimap2 sample_R1.fastq.gz sample_R2.fastq.gz

# cgMLST on an assembly
gmlst typing cgmlst -s vparahaemolyticus_3 --cgmlst-mode chew-fast sample.fna

3. Batch processing

# Write TSV output for many assemblies
gmlst typing mlst -s saureus_1 --max-workers 8 samples/*.fasta -o results.tsv

# Save machine-readable JSON for downstream novel extraction
gmlst typing mlst -s saureus_1 --format json samples/*.fasta -o results.json

4. Understand the output

Default output is TSV, compatible with the familiar tseemann/mlst style.

FILE            SCHEME      ST  arcC  aroE  glpF  gmk  pta  tpi  yqiL
sample1.fasta   saureus_1   1   1     1     1     1    1    1    1
sample2.fasta   saureus_1   -   1     ~2    3?    -    1    1    1

• plain allele number, exact known allele match
• ~23, non-exact high-coverage call, typically a closest or novel-style locus depending on identity
• 15?, partial locus hit with insufficient coverage
• -, locus not found

Use --format pretty for human-readable terminal output and --format json for downstream automation.

Alignment Backends

Backend notes

• typing mlst and typing cgmlst auto-detect common paired FASTQ naming patterns such as _R1/_R2, _1/_2, and .1/.2.
• typing cgmlst uses minimap2 by default for FASTA assemblies.
• For FASTQ cgMLST, the CLI follows a KMA-first policy and treats chew-style cgMLST modes as FASTA-oriented compatibility options.
• GMLST_MINIMAP2_KMER_ENGINE=python|kmc|auto controls the minimap2 k-mer support scorer.

Data Providers

Examples:

gmlst scheme list -p pubmlst
gmlst scheme list -p enterobase -t cgmlst
gmlst scheme list -p local
gmlst scheme show -s saureus_1

Novel Data Workflow

Build a local custom scheme from novel calls collected during routine typing.

# 1. Type samples and save JSON
gmlst typing mlst -s saureus_1 --format json *.fasta -o typing_results.json

# 2. Extract novel alleles and novel profiles
gmlst utils extract -i typing_results.json --novel-allele --novel-profile --data-dir novel_data

# 3. Create a local custom scheme
gmlst scheme create -t mlst -s saureus_1 --data-dir novel_data --desc "Lab collection 2024"

# 4. Add more novel data later
gmlst scheme update-custom -s custom_1 --data-dir more_novel_data

# 5. Export for downstream MST work
gmlst scheme export -s custom_1 --format grapetree -o custom_1_grapetree.tsv

TSV fallback is also supported when you only have tabular typing output and the original sample files are available:

gmlst utils extract -i typing_results.tsv -s saureus_1 --novel-allele --novel-profile \
  --samples-dir ./samples --data-dir novel_data

cgMLST Modes

gmlst typing cgmlst supports several calling modes for different speed and evidence trade-offs.

Examples:

gmlst typing cgmlst -s vparahaemolyticus_3 --cgmlst-mode standard sample.fna
gmlst typing cgmlst -s vparahaemolyticus_3 --cgmlst-mode chew-fast sample.fna
gmlst typing cgmlst -s vparahaemolyticus_3 --cgmlst-mode chew-ultrafast sample.fna
gmlst typing cgmlst -s vparahaemolyticus_3 --cgmlst-mode chew-bsr sample.fna
gmlst typing cgmlst -s vparahaemolyticus_3 --cgmlst-mode chew-balanced sample.fna

Scheme-free Typing (tgmlst)

Use tgmlst when you want scheme-free allele discovery and optional scheme reuse.

# Run scheme-free typing
gmlst typing tgmlst sample.fna --stats

# Save a discovered scheme for reuse
gmlst typing tgmlst sample.fna --save-scheme tgmlst_scheme.json

# Reuse a previously saved scheme
gmlst typing tgmlst another_sample.fna --load-scheme tgmlst_scheme.json --format json

Useful options include --hash-strategy, --summary-report, --error-report, and --fail-on-error.

Visualization

Launch the local web application to build an MST from cgMLST or exported GrapeTree-style profiles.

gmlst visual web --open-browser

Or bind to a custom address:

gmlst visual web --host 0.0.0.0 --port 8787

The web UI accepts TSV data, builds a minimum spanning tree, and serves a local Flask API with a Vue frontend.

Configuration

Key environment variables:

Example:

export GMLST_CACHE_DIR="$HOME/.cache/gmlst"
export GMLST_TMPDIR="$PWD/.tmp/gmlst"
export GMLST_MINIMAP2_KMER_ENGINE=auto
export GMLST_PUBMLST_BASE_URL="https://rest.pubmlst.org/db"
export GMLST_PASTEUR_BASE_URL="https://bigsdb.pasteur.fr/api/db"

Private BIGSdb example:

export GMLST_PRIVATE_BIGSDB_URL="http://127.0.0.1:9000/api/db"
export GMLST_PRIVATE_BIGSDB_NAME="labdb"
export GMLST_PRIVATE_BIGSDB_LABEL="Lab BIGSdb"
gmlst scheme list -p labdb

Output Format Details

The default TSV format uses compact markers per locus.

JSON output is the best choice when you want structured fields such as per-locus call metadata and novel_sequence extraction data.

Multicopy Loci Notes

• Conflicting multicopy calls are reported with comma notation such as 1,2.
• When conflicting multicopy loci are present, ST is reported as - to avoid overconfident profile assignment.
• Same-allele copy counting such as 1,1 is optional and currently exposed through --count-same-copy for blastn workflows.

Recommended review pattern:

# Fast first pass
gmlst typing mlst -s vparahaemolyticus_1 *.fna -o pass1.tsv

# Targeted second pass on flagged samples
gmlst typing mlst -s vparahaemolyticus_1 -b blastn --count-same-copy flagged_sample.fna

Development

Set up the development environment:

pixi install
pixi run install-dev

Common tasks:

pixi run lint
pixi run format-check
pixi run test
pixi run check

Direct Ruff commands also work:

pixi run ruff check .
pixi run ruff format .

See docs/contributing.md for contributor workflow and docs/architecture.md for module boundaries and typing-path contracts.

Documentation Index

• docs/README.md for the full documentation map
• docs/installation.md for installation details
• docs/quickstart.md for a guided first run
• docs/commands.md for the CLI reference
• README_ZH.md for the Chinese root guide

License

Released under the MIT License.

Acknowledgments

• Inspired by tseemann/mlst
• Uses public scheme data from PubMLST