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, 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

Quick install

A conda virtual environment is recommended for installing gmlst.

conda create -n gmlst
conda activate gmlst
conda install python=3.12
pip install gmlst

To make gmlst functional, you also need to install bioinformatics alignment tools. Currently, FASTA data supports the blastn, minimap2, nucmer, and kma backends. FASTQ data supports the kma backend. Install the ones you need based on your data types.

# Install all backend dependencies for full functionality
conda install blast minimap2 mummer4 kma

For other installation methods (Pixi, uv, source, Docker), see the Installation Guide.

Quick Start

1. Browse and download a scheme

# List cached and available schemes (downloaded schemes shown in bold)
gmlst scheme list

# Search across scheme name, organism, description, and provider
gmlst scheme search saureus
gmlst scheme search "salmonella" -t cgmlst

# Restrict to one provider
gmlst scheme list -p pubmlst

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

# Re-download with low concurrency (avoid 429 from rate-limited servers)
gmlst scheme download saureus_1 --force -x 2

2. Type one sample

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

# MLST on paired-end reads (requires kma backend)
gmlst typing mlst -s saureus_1 sample_R1.fastq.gz sample_R2.fastq.gz
# Wildcard patterns are supported for _1/_2 and _R1/_R2 naming
gmlst typing mlst -s saureus_1 sample*.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*, same allele detected at multiple genomic copies (e.g. gene duplicated on two chromosomes); does not affect ST assignment
• ~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. Use gmlst typing cgmlst with KMA for raw reads.
• FASTQ input auto-switches to KMA for both mlst and cgmlst modes.
• --max-depth — Subsample FASTQ to a maximum read depth (default 100x, FASTQ only)

Data Providers

Examples:

gmlst scheme list -p pubmlst
gmlst scheme list -p enterobase -t cgmlst
gmlst scheme list -p local
gmlst scheme search saureus
gmlst scheme show 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 custom_1 --data-dir more_novel_data

# 5. Export for downstream MST work
gmlst scheme export 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-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:

Since January 2025, PubMLST and Pasteur require authentication for data added after 31 December 2024. Obtain an API key and configure it:

# PubMLST: register at pubmlst.org → Preferences → API keys → create key
gmlst config set GMLST_PUBMLST_API_KEY your-key-here
gmlst config init     # auto-load in every new shell (run once)
source ~/.config/gmlst/env.sh   # apply now in current shell

Use gmlst config show to view all 29 configuration variables with current values and defaults:

gmlst config show                          # grouped table view
gmlst config env                           # shell-exportable format
gmlst config get GMLST_CACHE_DIR           # get a single variable
gmlst config set GMLST_CACHE_DIR /data     # write to ~/.config/gmlst/env.sh
gmlst config init                          # add source line to shell rc (run once)

Example:

export GMLST_CACHE_DIR="$HOME/.cache/gmlst"
export GMLST_TMPDIR="$PWD/.tmp/gmlst"
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

• Same-allele multicopy (23*): the same allele is detected at multiple genomic copies (e.g. housekeeping genes duplicated across two chromosomes in Vibrio). This is biologically normal and does not prevent ST assignment. The * suffix marks it for transparency; ST lookup uses the allele number without the *.
• Conflicting multicopy (1,2): different alleles are detected at different copies of the same locus (possible paralogs or mixed infection). ST is reported as - because a confident profile cannot be assigned.
• Explicit copy counting (1,1): use --count-same-copy to expand same-allele multicopy into comma notation for downstream tools that expect it.

Recommended review pattern:

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

# Targeted second pass on flagged samples (those with conflicting multicopy or ~ markers)
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/en/contributing.md for contributor workflow and docs/en/architecture.md for module boundaries and typing-path contracts.

Documentation Index

• docs/README.md for the full documentation map
• docs/en/installation.md for installation details
• docs/en/quickstart.md for a guided first run
• docs/en/commands.md for the CLI reference
• docs/en/configuration.md for configuration 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