Preprint Open the viewer Code Map collection Release v2.0.0

Project Overview

Genome-scale metabolic models are routinely solved and almost never drawn. A force-directed layout of a few thousand reactions returns a hairball: every cofactor is a hub, every hub drags its neighbours together, and the pathway structure a biochemist would recognise disappears. Curators therefore draw maps by hand, which is why so few exist.

MetaCarto reads a genome-scale model and lays it out the way a curator would. Linear pathways become straight backbones, cycles become rings and cofactors are pushed out as side branches. The output is schema-correct Escher JSON, with an SVG of every map. The layout is constructive and deterministic: no annealing, no random seed, no hand editing, and the same model always produces the same map.

What MetaCarto 2 adds

MetaCarto 2 is the current release. MetaCarto 1, the version described in the bioRxiv preprint, is frozen, and its 2,621 maps stay where they were published so existing links keep working.

• A whole model on one canvas. Each pathway keeps the drawing it has on its own map, and pathways are packed by the shape their ink actually covers rather than their bounding box. Central carbon sits in the middle, every other superclass grows around it as one region, and transport and exchange wrap the outside like a membrane.
• Nothing drawn on anything else. No map in the collection has text on a node, on an edge or on other text. A label that does not fit is moved further out. It is never hidden and never overlapped.
• Any model, not only BiGG. Compounds and cofactors are recognised from the model’s own chemistry and cross-references, not from BiGG’s id spelling. Human-GEM, Yeast-GEM and ModelSEED models all run end to end, from SBML, JSON, YAML or MATLAB.
• 99.99% of reactions drawn, up from 95.6% in MetaCarto 1.
• Cycles drawn as cycles, whatever the flux does. The TCA, urea and methionine cycles are recognised by their compounds and always drawn round. 98 of the 108 BiGG models now show a complete TCA ring.
• Draw your own map. Select by pathway, KEGG superclass, reaction, keyword, or everything within N steps of a metabolite. You get the same engine and the same quality gates.
• An editor built for automatic maps. The Escher fork can drag a reaction as a whole and select a whole pathway by double-clicking its caption. Labels stay clear of nodes as you move them.

How It Works

1. Primary-compound reduction

A reaction such as pyruvate + CoA + NAD⁺ → acetyl-CoA + CO₂ + NADH contributes one directed edge, between the substrate/product pair sharing the most molecular skeleton. Here that pair is pyruvate → acetyl-CoA. Everything else becomes a side branch. Without this reduction each reaction node has degree 4–8 and no clean orthogonal drawing exists, which is precisely why naive layouts hairball.

Cofactor-ness is applied as a tier, not a score penalty: a cofactor is never chosen while a non-cofactor alternative exists on its side. That is what stops CoA → acetyl-CoA, which shares 21 carbons, from beating pyruvate → acetyl-CoA.

2. Direction from flux

Reconstructions store reversible reactions in whichever direction the curator happened to write them, so glycolysis is often recorded partly backwards. Parsimonious FBA decides the drawn direction wherever a reaction carries flux, and antiparallel pairs are collapsed onto a single axis.

3. Cycles drawn as cycles

Rings are detected on the whole-model graph, contracted for layering, then expanded onto a circle. The circle is rotated so its entry arc faces the pathway feeding it.

4. Layered placement

Greedy feedback-arc-set, layer assignment, cluster-constrained crossing reduction, then Brandes–Köpf coordinate assignment. That last step is what produces straight vertical backbones; a barycentre assignment does not.

5. Packing a species onto one page

The canvas is planned on each pathway’s rasterised ink. Pathways cannot overlap, because placement tests collision on a grid with clearance. Small and mid-size models are packed several deterministic ways, and the tightest packing wins only if regions stay as cohesive and linked pathways stay as close as in the default.

The Generated Collection

Every model in the BiGG database is drawn and published under CC BY 4.0, as Escher JSON and SVG, at Awesome_visualization_Metabolic_Network.

Browse them in the viewer. It opens on the e_coli_core canvas, and Map ▸ Load map from library… reads the whole collection directly, with nothing to download.

Reactions are assigned to maps from the model’s own subsystem annotation, then from KEGG pathways, and only failing both from network structure. Maps are named after the metabolic function they cover, following KEGG BRITE top-level categories.

Try It

git clone --recurse-submodules https://github.com/forxhunter/MetaCarto.git

# one map per pathway, plus the whole model on one canvas
python layout_v2.py --model e_coli_core --group-function --canvas --preview

# your own model, from any format COBRApy reads
python layout_v2.py --model path/to/yeast-GEM.xml --group-function --canvas

# your own selection
python diy_map.py --model iML1515 --metabolite glu__L --radius 1 --no-boundary
python diy_map.py --model Recon3D --reaction PGI,PFK,FBA --connect 3

Every map is scored against explicit gates: orthogonality, crossings, node separation, label collisions, density and print legibility. --strict exits non-zero if a map breaks one.

Known Limitations

• 19 of 251,424 BiGG reactions have no drawable primary pair and are omitted.
• Large merged pages of around 120 reactions still cross themselves. One page in ten has more than 0.4 crossings per edge.
• About four reactions in a hundred still have an edge passing through a metabolite they have nothing to do with. Reactions that share nothing should never touch, so this is the next thing to fix.
• Whole-model canvases are for zooming, not printing. At 10,600 reactions a page, labels land well under a point however well the page is packed. The per-pathway maps are the printable artifact.
• Compartments are not drawn as envelopes, because the Escher schema has no region primitive.

Cite

MetaCarto and its maps are CC BY 4.0, so attribution is a term of the licence. If you use MetaCarto or a map it generated in a paper, figure, talk, poster, database or derived software, please cite the preprint:

Wu, T. (2026). MetaCarto: biologically faithful automatic layout for genome-scale metabolic maps. bioRxiv. https://doi.org/10.64898/2026.09.19.752882

@article{wu_metacarto_2026,
  author  = {Wu, Tianyu},
  title   = {{MetaCarto}: biologically faithful automatic layout for genome-scale metabolic maps},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.64898/2026.09.19.752882}
}

and, if you used MetaCarto 2 specifically, the software as well:

@software{Wu_MetaCarto_constructive_layout,
  author  = {Wu, Tianyu},
  license = {CC-BY-4.0},
  title   = {{MetaCarto: constructive layout synthesis for genome-scale metabolic networks}},
  url     = {https://github.com/forxhunter/MetaCarto}
}

Please also cite the underlying model from BiGG Models and, where maps are displayed, Escher.