Circular van Krevelen diagram for visualizing metabolic pathways

Emerging biochemical data require effective pathway visualization, but traditional metabolic maps rely on manual layouts that fall behind new scientific discoveries. lcvk implements a circularized van Krevelen diagram: metabolites are placed by chemical formula, using elemental ratios (H:C mapped to the angular axis, NOPS:C or a related ratio mapped to the radial axis) instead of a hand-drawn layout. Because the coordinates come from chemical principles rather than manual placement, pathway diagrams are automated and consistent across datasets, models, and labs.

Preprint is released: https://www.biorxiv.org/content/10.1101/2025.05.31.657198v1

This is the repo for the lcvk package, which includes code, example data and notebook templates.

Version 0.1 is proof of principle.

Example applications include

• Visualization of metabolic pathways and maps.
• Summurizing differential abundance in metabolomic data.
• Display of isotopic labeling patterns.
• Extension of metabolic knowledge by new reactions.

Install

pip install -e .

Requires Python >= 3.7 and numpy, scipy, matplotlib, mass2chem (see requirements.txt).

Quickstart

import lcvk

# list_cpds: [{'id': ..., 'name': ..., 'neutral_formula': 'C6H12O6'}, ...]
# list_edges: [(source_id, target_id), ...]
lcvk.plot_lcvk_pathway(
    list_cpds, list_edges,
    formula='neutral_formula', cpd_name='name',
    title='My pathway', outfile='pathway.pdf',
)

See notebooks/ for complete worked examples (metabolic pathways, differential metabolomics, isotope labeling).

Citation

Shuzhao Li. Circular van Krevelen diagram for visualizing metabolic pathways. bioRxiv (2025). https://doi.org/10.1101/2025.05.31.657198