GEM Autocurator
Drop a genome-scale metabolic model into your browser and get it curated.
Live: https://omidard.github.io/gem-autocurator/ · everything runs client-side;
your model is never uploaded.
Upload an SBML or COBRA-JSON model and the autocurator proposes changes across
eight stages. You approve or reject each one, and export a supervised curated
model as SBML, COBRA JSON and a COBRA Toolbox .mat struct, with a report of
what was decided.
What each stage does
- Identifier mapping: resolves every metabolite and reaction identifier
against BiGG, gives a stable BiGG-like identifier to compounds and reactions
that only KEGG / ModelSEED / MetaNetX / ChEBI / RHEA carry, and synthesises a
readable BiGG-styled identifier from the name for anything in no database at
all. Structure-based matches and name-derived guesses are different tiers and
are labelled differently; a name match is never a merge.
- Discrepancies: two identifiers in your model that denote the same
entity in the same compartment collapse to one canonical identifier. A
compartment suffix is not a discrepancy:
glc__D_c and glc__D_e are two
metabolites and stay that way. Two reactions are only ever proposed for
merging when their stoichiometry matches.
- Structural QC: dead-end metabolites and orphan reactions.
- Mass and charge: element conservation, and charge conservation judged at
the model's reference charge state, its own integer charges. This is
pH-independent by design: a balanced reaction has a fractional net charge at
any other pH, and that is expected proton buffering, not a defect.
The pH control on this stage is a protonation explorer. Move it and
metabolite charge states are titrated for inspection (Henderson-Hasselbalch
over ModelSEED pKa sites, anchored to the model's pH-7.2 charge). It never
raises a finding on its own.
- Thermodynamics and cycles: structurally blocked reactions by FVA with
every exchange opened, energy-generating-cycle detection across a currency
panel, and reaction directionality from ModelSEED's thermodynamic
reversibility and ΔrG′m. That value is ModelSEED's own
group-contribution + eQuilibrator consensus, a consensus inside one source,
not a vote across databases. All solved live by the bundled GLPK-WASM solver.
- Lab validation: the organism is auto-detected from the model id or name
(strain name, GCF/GCA accession with or without its prefix, or a BV-BRC genome
id; taxa resolved offline, accessions via the NCBI Datasets API, only the id
string is sent, never the model). Measured growth from GrowthDB and the
medium from the Media DB load into an editable condition. Every exchange
flux is tunable; rows backed by a measurement are tagged experimental and
every other row is tagged pre-set, no experimental backing. If the strain
has no measured data the tool says so rather than substituting a species
average, and you can enter your own growth rate and formulate the medium by
hand. Then FBA: predicted µmax against measurement, with a verdict,
a secretion-pattern check, and the caveat that FBA gives a theoretical maximum.
- Report and export: curated SBML, COBRA JSON, MATLAB
.mat, and a
Markdown report of every finding and every decision.
The identifier backbone
tools/build_backbone.py (the canonical builder) ingests the full MetaNetX
(MNXref) cross-reference universe, which already clusters compounds and
reactions from BiGG · KEGG · ModelSEED · ChEBI · MetaCyc · Rhea · HMDB by
structure, and keeps the clusters relevant to metabolic models. Each cluster
gets one canonical identifier: its BiGG identifier, or a stable BiGG-like one
shared by every database identifier in the cluster, frozen in
tools/backbone_freeze.json so it does not change between builds. So glc__D,
C00031, cpd00027 and CHEBI:4167 all resolve to glc__D.
| structure clusters | with a BiGG id | given a BiGG-like id | source ids mapped |
|---|
| metabolites | 47,930 | 9,908 | 38,022 | 300,033 |
| reactions | 68,294 | 20,731 | 47,563 | 223,572 |
Backbone source: MetaNetX/MNXref 4.4, built 2026-09-06. The 4 gzipped data files are 5,333,978 bytes (5.33 MB); the whole of docs/data/ is 16,551,519 bytes (16.6 MB). The validation bundle was built 2026-09-07 from GrowthDB @ be8e54c9f and Media DB @ 86c0c9e26, and carries 5,163 literature-cited records across 1,296 species, 4,540 of them with a measured growth rate.
Two caveats worth stating, because the headline numbers alone would overstate
the guarantee:
- A cluster can carry more than one primary BiGG identifier, and those are
preserved rather than merged, usually they are compartment or variant forms
(
Ht, Htm, Htg, Htex are proton transport across different membranes)
and collapsing them would corrupt any compartmentalised model. So the number
of canonical identifiers handed out is slightly larger than the number of
clusters, and two distinct primary BiGG identifiers in one structural cluster
stay distinct by design.
tests/test_id_injectivity.py asserts that no two clusters are ever handed
the same minted identifier, the invariant the whole promise rests on, and one
nothing checked until it was written. It found 1,401 minted reaction
identifiers shared by 3,031 MetaNetX clusters; the backbone rebuild fixed
that, and the assertion is now a live gate rather than a known failure.
Build inputs
| script | reads | writes |
|---|
tools/build_backbone.py | MetaNetX 4.4 TSVs from https://www.metanetx.org/ftp/4.4/ into /data/mnx_tmp | docs/data/{metabolite_map,reaction_map,bigg_met_props}.json.gz, backbone_coverage.json, tools/backbone_freeze.json |
tools/build_thermo_pka.py | the ModelSEED Biochemistry database | docs/data/{pka_table,thermo_rxn}.json |
tools/build_validation.py | GrowthDB + the Media DB | docs/data/{growthdb,media_ex,spectrum}.json |
tools/repo_facts.py | the shipped artifacts | the generated blocks in this file and THIRD_PARTY.md |
Raw upstream inputs are build-time only and stay outside the repository; each
script's header carries its download commands. tools/deprecated/build_id_maps.py
is the superseded predecessor of the backbone builder, kept as the record of an
identifier scheme that was rejected; it refuses to run.
Tests
python3 tests/run_tests.py # boot smoke + repository hygiene (~20 s)
python3 tests/run_tests.py --suite all # + model-integrity round-trips through COBRApy
See tests/README.md. The fast suite gates every push through
.github/workflows/ci.yml; it proves the page boots and the hygiene rules hold,
and deliberately proves nothing about whether a curation engine is correct.
tests/known_failures.tsv lists the assertions that are red on purpose, each
against the finding that explains why.
Stack
Pure client-side, served by GitHub Pages from docs/. SBML/JSON parsing,
identifier canonicalisation, QC, charge titration, identifier synthesis,
SBML/JSON/MAT export and the Plotly dashboard are vanilla ES modules;
GLPK-WASM does every flux-based computation. Design shared with
Flux Studio.
Licence and attribution
Original code is MIT. The published bundle is GPL-3.0, because it imports and
executes glpk.js 4.0.1 (GPL-3.0). The bundled reference data is derived from
MetaNetX, ModelSEED and BiGG and cannot be relicensed by this project, and two
of those upstream terms restrict non-academic use. See LICENSE and
THIRD_PARTY.md before redistributing or building a product on this.
Citation metadata is in CITATION.cff.
