A free, open-source cgMLST platform for Linux — assemble, type, characterise, cluster, and manage your bacterial isolates, all in your browser.
Point MLSTudio at a folder of assembled genomes (or raw reads), pick a scheme, and in a few minutes you have an interactive minimum spanning tree, an AMR profile, organism-specific typing, a persistent searchable library of every isolate you've ever run, and one-click reports — no licence cost, no cloud, no data leaving your machine.
New in 1.5 — MLSTudio is now a full suite: a persistent sample library you can re-slice into trees in memory with no re-analysis, editable metadata, custom folders, portable data bundles that move between PCs, a read→assembly pipeline (fastp → SKESA/SPAdes), and organism-specific modules (Kleborate, agr, SCCmec, mob-recon, abricate). See What's new.
Jump to the 5-minute quick start →
- What MLSTudio does
- A tour in pictures
- Installation
- 5-minute quick start
- The seven tabs
- The sample library — your persistent suite
- Metadata, folders & research search
- Never lose your data: the vault, bundles & tables
- From reads to typing: the assembly pipeline
- Organism-specific typing modules
- Reports & exports
- Command-line reference
- Troubleshooting & FAQ
- What's new in 1.5
- License & credits
MLSTudio fills the gap between calling-only tools (like chewBBACA) and visualisation-only tools (like GrapeTree), and does it without a SeqSphere-style licence fee. In one local application you get:
| 🧬 Typing | Classical 7-gene MLST and whole-genome cgMLST (PubMLST, BIGSdb-Pasteur, cgMLST.org, or your own ad-hoc scheme). |
| 🌳 Visualisation | An interactive minimum spanning tree — drag nodes, colour by metadata, threshold-driven cluster halos, pie-slice merged genotypes. |
| 💊 AMR | AMRFinderPlus resistance genes with clinical flags (MRSA, VRE, ESBL, CPE, MDR/XDR, linezolid, colistin). |
| 🦠 Characterisation | Organism modules: Kleborate (Klebsiella), agr/SCCmec/spa (S. aureus), MOB-recon (plasmids), abricate (virulence + replicons). |
| 📁 A persistent library | Every isolate you analyse is stored, searchable, and re-usable — pick any subset and rebuild a tree in memory with no re-analysis. |
| 🔒 Data safety | Assemblies are copied into a secure vault; results survive without the FASTA; export/import moves data between machines. |
| 🧩 Assembly | Go from raw reads → draft genome → typing in one flow (fastp → SKESA/SPAdes). |
| 📄 Reporting | Self-contained HTML reports, plus GraphML/Newick/TSV/distance-matrix exports. |
Everything runs locally on Linux; nothing is uploaded anywhere.
(All screenshots use the 18-isolate Enterococcus faecium VREfm ST1478 demo panel against the cgMLST.org scheme — 1,423 loci.)
The minimum spanning tree, built from your library selection. The top-right badge shows the active dataset; the strip beneath shows live cluster and AMR counts.
The sample library — every isolate you've ever analysed, searchable and filterable, with collections (custom folders), research filters, and one-click tools to build trees, export bundles, or load standard profile tables.
The setup tab, where you choose a folder, a scheme, and options (AMR, organism typing, assemble-from-reads, secure copy).
MLSTudio is a Python package plus a handful of well-known bioinformatics binaries. The recommended way is a single conda environment.
# 1. Create an environment with the external tools MLSTudio calls
conda create -n mlstudio -c conda-forge -c bioconda \
python=3.11 blast prodigal fastp ncbi-amrfinderplus
conda activate mlstudio
# 2. Install MLSTudio itself
pip install mlstudio # (from PyPI once published)
# …or from source:
git clone https://github.com/iowa69/mlstudio.git
cd mlstudio
pip install .
# 3. (once) fetch the AMRFinderPlus database
mlstudio amr-updateconda install -c bioconda mlstudioMLSTudio automatically detects these tools whether they're on your PATH or
in a separate conda env, so install only what you need:
| Feature | Install |
|---|---|
| Klebsiella typing | conda create -n klebo -c bioconda kleborate |
| S. aureus (agr/SCCmec/spa) | conda create -n satyping -c bioconda staphopia-sccmec spatyper agrvate |
| Plasmid reconstruction | conda create -n mobsuite -c bioconda mob_suite |
| Virulence + replicons | conda create -n abricate -c bioconda abricate |
| Read assembly | conda create -n skesa -c bioconda skesa and/or spades |
mlstudio --version # mlstudio 1.5.0
mlstudio --helpYou need a folder of assembled genomes in FASTA format (.fasta, .fa,
.fna, optionally gzipped). One assembly per isolate.
mlstudio gui ~/my_isolatesYour browser opens to the Setup tab. Then:
- Choose the folder — it's pre-filled from the command line; click Scan folder to confirm MLSTudio sees your assemblies.
- Pick a scheme — start typing an organism (e.g. Klebsiella), or click Browse the full catalog to pull one from PubMLST / cgMLST.org. Cached schemes show a ✓.
- Set options (all optional): tick Run AMR gene scan, Run organism-specific typing, Keep a secure copy of each assembly.
- Click ▶ Analyze. Progress streams live; when it finishes you're flipped to the MST tab.
- Explore. Drag nodes, colour by metadata, move the cluster-threshold slider, click a node to open its detail card, and hit ⤓ Download HTML report when you're happy.
Every isolate you just typed is now saved in the Library tab forever (until you delete it).
# Type a folder of assemblies
mlstudio analyze ~/my_isolates --scheme kpneumoniae_complex_cgmlst_orgio --amr --modules
# Identify an unknown assembly from your cached schemes
mlstudio detect mystery_genome.fasta
# Assemble reads first, then type
mlstudio assemble ~/my_reads --assembler skesa -o ~/assemblies
mlstudio analyze ~/assemblies --scheme saureus_cgmlst
# Build a standalone HTML report
mlstudio report ~/my_isolates --scheme saureus_cgmlst -o report.htmlMLSTudio is organised around seven tabs. Five present a run's results; the last two are your persistent library and a housekeeping page. The left sidebar swaps in contextual controls for whichever tab you're on, and a ▸ N samples · scheme badge in the top bar always tells you what dataset you're looking at.
| Tab | What it's for |
|---|---|
| 📋 Setup | Choose the input folder, the scheme, and analysis options; start a run. |
| 🌳 MST | The interactive minimum spanning tree. Drag/colour/threshold; export PNG/SVG/GraphML/Newick/distances. |
| 📊 Table | Per-isolate comparison table — ST, cgST, clusters, AMR, and every allele. Export TSV. |
| 💊 AMR | Sample × resistance-gene matrix, filterable by gene / class / method. |
| 📈 Statistics | Allele-distance distribution and cluster summary. |
| 📁 Library | Every isolate ever analysed — search, filter, group, and rebuild trees in memory. |
| 🗑 Manage | Delete samples / schemes / all local data, safely. |
Every result tab has a ⟳ Refresh control, and the Reset button (Setup) clears everything back to the welcome screen.
This is the heart of MLSTudio 1.5. Every isolate you analyse is stamped into a local library and stays there until you explicitly delete it. The library spans every run and every folder — it's your lab's growing reference set.
The killer feature: select any subset of previously-analysed isolates and click “⊞ Build MST from selected” — MLSTudio rebuilds the distance matrix and tree entirely from the stored allele profiles, in memory, with no re-analysis. Comparing isolates from three different runs last month? Tick them and build.
How to use it:
- The Library (N) tab badge shows how many isolates you have.
- ☑ All / ☐ None select every shown row; the scheme filter clears the selection (you can only build one tree from one scheme).
- Tick 2+ isolates of the same scheme and hit ⊞ Build MST from N selected → you land on the MST tab with a fresh tree.
- The built view is a first-class result: download its report, export GraphML/Newick, or Save current as project.
Click any library isolate to open its detail card. For library samples the card includes an editable ancillary-data form — record the isolation date, ward, specimen, patient age/sex, country, free-text notes, or any custom field you like, right there online. It's saved instantly and becomes available for colouring the tree and for search.
Collections (custom folders) — group isolates however you think about them (“Outbreak A”, “Ward 5 2026”, “Reference panel”). Create a folder, tick some isolates, click + Add selected, and later filter the library to just that folder (and build a tree from it).
Research filters — the collapsible 🔎 Research filters panel lets you slice the library by:
- ST or HC10 cluster
- QC verdict (PASS / WARN / FAIL)
- AMR gene present (e.g.
vanA,blaKPC) - Isolation-date range
- Any metadata field = value (e.g.
ward = ICU)
This turns your library into a searchable epidemiological database.
MLSTudio 1.5 is built so you never lose your typing data.
When you analyse an isolate (with Keep a secure copy ticked, the default), MLSTudio copies the assembly into a content-addressed vault inside its own data directory. You can then move, rename, or delete the original folder — your data is safe. A 🔒 icon marks vaulted isolates. The copy is removed only when you explicitly delete the sample.
Tick some isolates and click ⤓ Export bundle to get a single JSON file containing their allele profiles + metadata — but no FASTA. On another machine, ⤒ Import bundle loads them straight into the library. Because the tree, report, and exports all work from the stored profiles, you can share and re-visualise data without re-running anything and without shipping gigabytes of sequence.
For interoperability with chewBBACA / Ridom and for archiving, use ⤓ Profiles TSV to export a standard sample × loci table, and ⤒ Load table to import one (you pick the target scheme). A loaded table can be turned into an MST immediately — the classic “load a colleague's profile table and cluster it, no FASTA, no analysis” workflow.
Only have FASTQ reads? MLSTudio assembles them for you.
In the GUI: on the Setup tab, tick Assemble from reads first, choose SKESA (fast, default) or SPAdes (thorough), point at a folder of paired reads, and Analyze — MLSTudio runs fastp → assembler → typing in one go and stores the fresh assemblies in the vault.
On the CLI:
# Just assemble
mlstudio assemble ~/reads --assembler skesa -o ~/assemblies
# Assemble and type in one command
mlstudio analyze ~/reads --scheme efaecium_cgmlst_orgio --assemble --assembler spadesRead pairs are detected automatically (_R1/_R2, _1/_2, case-insensitive).
Intermediate files are cleaned up; only the assemblies are kept (add
--keep-intermediate to retain fastp reports and the assembler working dir).
Tick Run organism-specific typing and MLSTudio automatically runs the right tool for your organism, showing the results on each isolate's detail card and in the HTML report. Each is optional — install the tool for the organisms you work with (see Installation); a missing tool is simply skipped with a note.
| Module | Organism | Reports |
|---|---|---|
| Kleborate | Klebsiella pneumoniae complex | species, ST, virulence loci (ybt/clb/iuc/iro/rmp) + score, Kaptive K/O capsule type, ESBL/carbapenemase, hypervirulence & convergence flags |
| S. aureus | Staphylococcus aureus | agr group (AGRvate), SCCmec + mecA → MRSA/MSSA (staphopia-sccmec), spa type (spaTyper) |
| Plasmids | any | per-plasmid replicon (Inc), relaxase (MOB), MPF, predicted mobility (MOB-recon) |
| Virulence & replicons | any | virulence genes (VFDB) + plasmid replicons (PlasmidFinder), via abricate |
MLSTudio resolves each tool whether it's on your PATH (a single bioconda env)
or in a separate conda env — so the multi-env setup most labs already have
works out of the box.
- HTML report — self-contained, printable. Batch summary (ST/cgST/HC10
counts, AMR-flag prevalence, QC), HC10 cluster membership (your outbreak
groups), an isolate overview table, and a per-isolate card with typing, QC,
AMR-by-drug-class and every organism module. Download from the sidebar or
mlstudio report. - MST exports — high-DPI PNG, vector SVG, GraphML (Cytoscape desktop / Gephi), Newick (iTOL / FigTree), and the pairwise distance-matrix TSV.
- Tables — the comparison TSV (all alleles + metadata + AMR), the AMR TSV, and the standard allelic-profile TSV.
- Portable bundles — profiles + metadata as JSON (see above).
mlstudio gui [FOLDER] Launch the local web GUI.
mlstudio analyze FOLDER --scheme KEY Type a folder headlessly. Options:
--amr/--no-amr run AMRFinderPlus (default off)
--modules/--no-modules organism-specific typing (default off)
--assemble --assembler skesa|spades assemble reads first
--mlst/--no-mlst pair classical MLST with cgMLST (default on)
--fastp/--no-fastp fastp on any reads (default on)
--vault/--no-vault keep a secure copy of each assembly (default on)
-t THREADS -o OUTPUT_DIR --no-library
mlstudio assemble FOLDER Reads → draft genomes (fastp → SKESA/SPAdes).
-a skesa|spades --fastp/--no-fastp --keep-intermediate -o OUTPUT
mlstudio detect ASSEMBLY Guess the organism from cached MLST schemes.
mlstudio report FOLDER --scheme KEY Analyse + write a standalone HTML report.
mlstudio schemes list [--remote] List cached (or all) schemes.
mlstudio schemes pull KEY Download a scheme (PubMLST/BIGSdb/cgMLST.org).
mlstudio schemes pull-eskapee Pull all 7 WHO-priority cgMLST schemes.
mlstudio schemes build-adhoc ... Build a cgMLST scheme from one reference.
mlstudio amr-update Refresh the AMRFinderPlus database.
mlstudio call mlst|cgmlst ... Single-assembly smoke-test commands.
Run any command with --help for the full option list.
“No FASTA files found.” MLSTudio types assemblies. If you have reads, use
--assemble (or the GUI's Assemble from reads first).
“AMR scan was requested but amrfinder isn't installed.” Install
ncbi-amrfinderplus and run mlstudio amr-update once.
An organism module shows “not installed.” Install its tool (see the table in
Installation); MLSTudio finds it on PATH or in a sibling
conda env automatically.
A cgMLST scheme download is large. cgMLST.org schemes are hundreds of MB to a
couple of GB. It's a one-time download, cached under
~/.local/share/mlstudio/schemes/.
Where's my data stored? ~/.local/share/mlstudio/ — the scheme cache, the
library.sqlite, the vault/, saved projects/, and job snapshots. The
Manage tab lets you clean any of it. Your original FASTAs are never modified
or deleted.
Can I move my library to another computer? Yes — export the isolates as a bundle and import them on the other machine. No re-analysis needed.
Does anything leave my machine? Only scheme downloads (from PubMLST / cgMLST.org) and the AMRFinderPlus database update. Your genomes and results never leave your computer.
MLSTudio grew from a typing-and-visualisation tool into a full cgMLST platform:
- 🗄️ Persistent library / suite — rebuild trees from any stored selection, in memory, no re-analysis.
- 🏷️ Editable ancillary metadata + custom folders + a research search over dates, AMR genes, clusters and metadata.
- 🔒 Secure vault, portable bundles, and standard allelic-profile tables so your data is never lost and moves freely between machines.
- 🧩 Reads → assembly → typing (fastp → SKESA/SPAdes) in one flow.
- 🦠 Organism modules (Kleborate, agr/SCCmec/spa, MOB-recon, abricate) and broader AMR flags (linezolid, colistin).
- 📄 Reports & five export formats, headless CLI (
analyze/detect/assemble/report), on-disk job persistence, and a genuinely working Reset. - ✅ 125+ automated tests, clean
ruff/mypy, and multiple adversarial multi-agent code reviews.
See CHANGELOG.md for the full history, and USERGUIDE.md for the in-depth manual.
MIT — see LICENSE.
Developed by Giovanni Lorenzin (@iowa69).
MLSTudio stands on the shoulders of the tools it orchestrates — PubMLST, BIGSdb-Pasteur, cgMLST.org, NCBI BLAST+, Prodigal, fastp, AMRFinderPlus, Kleborate, AGRvate, staphopia-sccmec, spaTyper, MOB-suite, abricate, SKESA and SPAdes. Please cite them when you use their results.