Metadata-Version: 2.4
Name: lcvk
Version: 0.1.1
Summary: Li-circular van Krevelen diagram
Home-page: https://github.com/shuzhao-li-lab/Li_CVK_diagram
Author: Shuzhao Li
Author-email: shuzhao.li@gmail.com
License: BSD 3-Clause
Keywords: bioinformatics metabolic pathway visualization
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: mass2chem
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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_pathway_fa](docs/source/_static/worm_human_fa.png)

![example_pathway_alanine](docs/source/_static/alanine.png)

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

```bash
pip install -e .
```

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

## Quickstart

```python
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
