lcvk 0.1.1__tar.gz

lcvk-0.1.1/LICENSE

@@ -0,0 +1,7 @@
+# Licensed under the BSD 3-Clause License.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

lcvk-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include requirements.txt

lcvk-0.1.1/PKG-INFO

@@ -0,0 +1,85 @@
+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

lcvk-0.1.1/README.md

@@ -0,0 +1,47 @@
+# 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

lcvk-0.1.1/lcvk/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.1"
+
+from .metModels import *
+from .polarPlot import *
+from .recipes import *

lcvk-0.1.1/lcvk/main.py

@@ -0,0 +1,23 @@
+import json
+import numpy as np
+
+from .metModels import *
+from .polarPlot import *
+
+def run_demo(infile='../data/example_network_32.json'):
+    net32 = json.load(open(infile))
+    list_cpds, list_edges = net32['nodes'], net32['edges']
+    plot_lcvk_pathway(list_cpds, list_edges,
+                    formula='neutral_formula', cpd_name='name',
+                      ydata='ratio_NOPS', 
+                      min_theta=0.1*np.pi, max_theta=1.9*np.pi,
+                      min_radius=0, max_radius=2.5,
+                      padding=0.1, optimization=False,
+                      optimization_spacer=0.3,
+                      fontsize=5, rotation=30, show_names=True, show_formula=False, 
+                      width=9, height=9,   # inch
+                      title='Hello chemistry', outfile='demo_lcvk_plot.pdf', dpi=300
+                      )
+
+if __name__ == '__main__':
+    run_demo()

lcvk-0.1.1/lcvk/metModels.py

@@ -0,0 +1,169 @@
+#
+# Handling metabolic models, metabolties, reactions, pathways
+#
+
+__all__ = ['json_convert_azmuth_mummichog', 'get_pathways_from_gem']
+
+# modified from mummichog 2
+def json_convert_azmuth_mummichog(jmodel):
+    '''
+    The jmodel was parsed from one of the Genome scale metabolic models. 
+    All compound identifiers and other identifiers are expected to be contained within the model.
+    >>> jmodel.keys()
+        dict_keys(['id', 'list_of_reactions', 'list_of_compounds', 'list_of_pathways', 'meta_data'])
+    >>> jmodel['list_of_compounds'][772]
+    {'id': 'ebastineoh', 'name': 'Hydroxylated Ebastine', 'identifiers': {'inchi': 'InChI=1S/C32H39NO3/c1-32(2,24-34)28-17-15-25(16-18-28)30(35)14-9-21-33-22-19-29(20-23-33)36-31(26-10-5-3-6-11-26)27-12-7-4-8-13-27/h3-8,10-13,15-18,29,31,34H,9,14,19-24H2,1-2H3'}, 'neutral_formula': '', 'charge': 0, 'charged_formula': 'C32H39NO3', 'neutral_mono_mass': 0.0, 'SMILES': '', 'inchi': ''}
+    >>> jmodel['list_of_pathways'][2]
+    {'id': 'group3', 'name': 'Aminoacyl-tRNA biosynthesis', 
+    'list_of_reactions': ['HMR_5130', 'HMR_5131', 'HMR_5132', 'HMR_5133', 'HMR_5134', 'HMR_5135', 
+            'HMR_5136', 'HMR_5137', 'HMR_5138', 'HMR_5139', 'HMR_5140', 'HMR_5141', 'HMR_5142', 'HMR_5143', 
+            'HMR_5144', 'HMR_5145', 'HMR_5146', 'HMR_5147', 'HMR_5148', 'HMR_5149', 'HMR_5150']}
+    >>> 
+    >>> jmodel['list_of_reactions'][22]
+    {'id': '24_25DHVITD3tm', 'reactants': ['2425dhvitd3'], 'products': ['2425dhvitd3']}
+
+    >>> mfn['metabolic_pathways'][51]
+    {'cpds': ['C00024', 'C00027', 'strdnccoa', 'C00100', 'C01944', 'q10h2', 'dmhptcoa', 'etfrd', 'C03035', 'etfox', 'dmnoncoa', 'arachdcoa', 'dcsptn1coa', 'ptdcacoa', 'C00412', 'od2coa', 'hdcoa', 'C02593', 'dlnlcgcoa', 'vacccoa', 'C00010', 'C00016', 'adrncoa', 'C00154', 'lneldccoa', 'lnlccoa', 'c226coa', 'lnlncacoa', 'C00399', 'odecoa', 'hpdcacoa', 'C01352', 'eicostetcoa', 'tmndnccoa', 'arachcoa'], 
+    'rxns': ['FAOXC2242046m', 'FAOXC200180m', 'FAOXC204', 'FAOXC160', 'FAOXC16080m', 'FAOXC180', 'FAOXC80', 'FAOXC140', 'FAOXC1811601m', 'FAOXC1811603m', 'FAOXC150m', 'FAOXC18480m', 'FAOXC1811602m', 'FAOXC16180m', 'FAOXC170m', 'FAOXC18280m', 'FAOXC182806m', 'FAOXC183803m', 'FAOXC2252053m', 'FAOXC2031836m', 'FAOXC11', 'FAOXC204184m', 'FAOXC226205m', 'FAOXC226', 'ETFQO', 'ETF'], 
+    'ecs': ['1.3.99.3', '1.5.5.1'], 'id': 'mfn1v10path136', 'name': 'Fatty acid oxidation'}
+    >>> mfn['metabolic_rxns'][2]
+    {'reactants': ['C06611'], 'id': 'R05233', 'source': 'kegg_dre', 'ecs': ['1.1.1.1'], 'products': ['C06613'], 'cpds': ['C06611', 'C06613'], 'pathway': '3-Chloroacrylic acid degradation'}
+    >>>    
+    mfn['cpd2pathways'] = {
+         'C06125': ['Glycosphingolipid metabolism', 'Glycosphingolipid biosynthesis - ganglioseries'], ...
+         }
+    >>> mfn['cpd_edges'][:5]
+[   ['C00106', 'C00526'], ['C05977', 'CE6326'], ['C00043', 'G00174'], ['C00199', 'C00231'], ['C00014', 'C00655']]
+    '''
+    new = {}
+    new['id'] = jmodel['id']
+    new['version'] = jmodel['meta_data']['version']
+    cpdDict,  dict_cpds_def = {}, {}
+    for cpd in jmodel['list_of_compounds']:
+        cpdDict[cpd['id']] = cpd   # no mcg conversion here
+        dict_cpds_def[cpd['id']] = cpd['name']
+    new['Compounds'] = cpdDict
+    new['dict_cpds_def'] = dict_cpds_def
+    new['metabolic_rxns'] = jmodel['list_of_reactions']
+
+    # bunch of indexing
+    dict_rxns, rxn2edges, edge2rxn, edge2enzyme = {}, {}, {}, {}
+    cpd_edges = []
+    for rxn in jmodel['list_of_reactions']:
+        dict_rxns[rxn['id']] = rxn
+        _edges = []
+        for cpd1 in rxn['reactants']:
+            for cpd2 in rxn['products']:
+                k = [cpd1, cpd2]
+                cpd_edges.append(k)
+                _edges.append(k)
+                edge2rxn[','.join(sorted(k))] = rxn['id']
+                # enzymes not in current test model and not tested ------------------ watch out for this, could be rxn['ecs']
+                if 'enzymes' in rxn:
+                    for e in rxn['enzymes']:
+                        edge2enzyme[','.join(sorted(k))] = e
+                        
+        rxn2edges[rxn['id']] = _edges
+        
+    new['cpd_edges'] = cpd_edges
+    new['edge2rxn'] = edge2rxn
+    new['rxn2edges'] = rxn2edges
+    new['edge2enzyme'] = edge2enzyme
+    # now do pathways
+    metabolic_pathways = []
+    for P in jmodel['list_of_pathways']:
+        _p = {}
+        _p['id'] = P['id']
+        _p['name'] = P['name']
+        _p['rxns'] = P['list_of_reactions']
+        cpds, ecs, edges = [], [], []
+        for ii in P['list_of_reactions']:
+            rxn = dict_rxns[ii]
+            cpds += rxn['reactants'] + rxn['products']
+            edges += rxn2edges[ii]
+            # enzymes not in current test model and not tested ------------------ watch out for this, could be rxn['ecs']
+            if 'enzymes' in rxn:
+                ecs += rxn['enzymes']
+        _p['cpds'] = list(set(cpds))
+        _p['edges'] = edges
+        _p['ecs'] = list(set(ecs))
+        metabolic_pathways.append(_p)
+
+    cpd2pathways = {}
+    for _p in metabolic_pathways:
+        for cpd in _p['cpds']:
+            if cpd in cpd2pathways:
+                cpd2pathways[cpd].append(_p['name'])
+            else:
+                cpd2pathways[cpd] = [_p['name']]
+
+    new['metabolic_pathways'] = metabolic_pathways
+    new['cpd2pathways'] = cpd2pathways
+
+    return new
+
+
+def get_pathways_from_gem(jmodel):
+    '''
+    Extract and index pathways from a JSON style, 
+    concise genome scale metabolic models as in mummichog style.
+    '''
+    new = {}
+    new['id'] = jmodel['id']
+    new['version'] = jmodel['meta_data']['version']
+    cpdDict,  dict_cpds_def = {}, {}
+    for cpd in jmodel['list_of_compounds']:
+        if 'neutral_mono_mass' in cpd:
+            cpd['neutral_formula_mass'] = cpd['neutral_mono_mass']
+        if 'neutral_formula_mass' in cpd and cpd['neutral_formula_mass']:
+            cpdDict[cpd['id']] = cpd    # convert_compound_azimuth_mummichog(cpd, hmdb_dict, kegg_dict)
+            dict_cpds_def[cpd['id']] = cpd['name']
+    new['Compounds'] = cpdDict
+    new['dict_cpds_def'] = dict_cpds_def
+    new['metabolic_rxns'] = jmodel['list_of_reactions']
+
+    # bunch of indexing
+    dict_rxns, edge2rxn, rxn2edges, edge2enzyme = {}, {}, {}, {}
+    cpd_edges = []
+    for rxn in jmodel['list_of_reactions']:
+        dict_rxns[rxn['id']] = rxn
+        _edges = []
+        for cpd1 in rxn['reactants']:
+            for cpd2 in rxn['products']:
+                k = [cpd1, cpd2]
+                cpd_edges.append( tuple(k) )  # tuple to support set
+                edge2rxn[','.join(sorted(k))] = rxn['id']
+                _edges.append( tuple(k))
+                enzymes = rxn.get('ecs', []) or rxn.get('enzymes', [])
+                for e in enzymes:
+                    edge2enzyme[','.join(sorted(k))] = e
+
+        rxn2edges[rxn['id']] = _edges
+
+    new['cpd_edges'] = cpd_edges
+    new['edge2rxn'] = edge2rxn
+    new['edge2enzyme'] = edge2enzyme
+    # now do pathways
+    metabolic_pathways = []
+    for P in jmodel['list_of_pathways']:
+        _p = {}
+        _p['id'] = P['id']
+        _p['name'] = P['name']
+        _p['rxns'] = P['list_of_reactions']
+        _p['edges'] = []
+        cpds, ecs, genes = [], [], []
+        for ii in P['list_of_reactions']:
+            rxn = dict_rxns[ii]
+            _p['edges'] += rxn2edges[rxn['id']]
+            cpds += rxn['reactants'] + rxn['products']
+            enzymes = rxn.get('ecs', []) or rxn.get('enzymes', [])
+            ecs += enzymes
+            if 'genes' in rxn:
+                genes += rxn['genes']
+        _p['cpds'] = list(set(cpds))
+        _p['ecs'] = list(set(ecs))
+        _p['genes'] = list(set(genes))
+        metabolic_pathways.append(_p)
+
+    return metabolic_pathways
+

lcvk-0.1.1/lcvk/polarPlot.py

@@ -0,0 +1,497 @@
+'''
+Core plotting functions for the circular van Krevelen (LCVK) diagram.
+
+Metabolites are laid out from their chemical formula rather than a manual
+layout: the H:C ratio is mapped to the angular (theta) axis via
+project_hc_data_radial/standardize_data, and a second ratio (NOPS:C by
+default; see get_chnops_ratios/get_lcvk_ratios) is mapped to the radial axis.
+
+Reference: Li S. Circular van Krevelen diagram for visualizing metabolic
+pathways. bioRxiv (2025). https://doi.org/10.1101/2025.05.31.657198
+'''
+import logging
+
+import matplotlib.pyplot as plt
+import numpy as np
+from mass2chem.formula import parse_chemformula_dict
+
+# used for optimization # import networkx as nx
+from scipy.cluster.hierarchy import linkage, fcluster
+from scipy.spatial.distance import pdist
+from scipy.spatial.distance import euclidean
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    'get_chnops_ratios', 'get_isotopic_chnops_ratios', 'get_lcvk_ratios',
+    'project_hc_data_radial', 'standardize_data', 'clean_pathway_name',
+    'calculate_clean_network', 'get_pathway_coordinates', 'generate_landmarks',
+    'plot_lcvk_pathway', 'assign_new_values', 'part_twins', 'optimize_list_coordinates',
+    'populate_cpd_coordinates', 'plot_lcvk_cartesian_pathway', 'nx_fruchterman_reingold',
+]
+
+
+def get_chnops_ratios(f):
+    '''
+    f: formula
+    Returns H/C, O/C, N/C and weighted NOPS/C ratios
+    '''
+    _d = parse_chemformula_dict(f)
+    if 'C' in _d:
+        hc = _d['H']/_d['C']
+        nc, oc, pc, sc  = _d.get('N', 0), _d.get('O', 0), _d.get('P', 0), _d.get('S', 0)
+        nops_c = (nc*14 + oc*16 + pc*31 + sc*32) /(_d['C'] * 12)
+        oc, nc = oc/_d['C'], nc/_d['C']
+        return hc, oc, nc, nops_c
+    else:
+        return [0] * 4
+
+def get_isotopic_chnops_ratios(f):
+    '''To implement'''
+    raise NotImplementedError
+
+def get_lcvk_ratios(f, ccs_offset):
+    '''
+    Returns H/C, NOPS coefficient, (weighted NOPS/C), CCS offset (CCS deviation from all isomers in pathway).
+    ccs_deviation to be calculated elsewhere, as delta to average CCS of all isomers in model.
+    '''
+    hc, oc, nc, nops_c = get_chnops_ratios(f)
+    return hc, oc, nc, nops_c, ccs_offset
+
+def project_hc_data_radial(hcList, 
+                           min_theta=0.1*np.pi, max_theta=1.9*np.pi, 
+                           # min_hc=0.5, max_hc=2.5,
+                           ):
+    '''
+    Convert H:C ratios to radial theta angles. 
+    Use standardize_data for fixed H/C scale.
+    '''
+    _low, _high = min(hcList), max(hcList)
+    range = _high - _low
+    if range==0:
+        return hcList
+    else:
+        _slope = (max_theta - min_theta)/range
+        return [_slope*(x-_low) + min_theta for x in hcList]
+
+def standardize_data(hcList, range_degrees=1.8):
+    '''
+    Test using fixed scale. Use at risk. 
+    Theta ranges 0.1*pi to 1.9*pi. H:C btw 0.5 and 2.5.
+    Therefore HC = 2.5703939893 * x + 0.3
+    '''
+    return [2.827433388230814 * (x-0.5) + 0.314159265359 for x in hcList]
+
+def clean_pathway_name(name):
+    return name.replace('/', '_')
+
+def calculate_clean_network(list_cpds, list_edges, formula='neutral_formula', max_H_C_allowed=5):
+    pathway_nodes, pathway_edges = [], []
+    for cpd in list_cpds:
+        if formula in cpd and 'C' in cpd[formula] and 'H' in cpd[formula]:
+            hc, oc, nc, nops_c, ccs_offset = get_lcvk_ratios(cpd[formula], 0)
+            if hc <= max_H_C_allowed:
+                pathway_nodes.append(
+                    {
+                        **cpd,
+                        'ratio_H_C': hc,
+                        'ratio_O_C': oc,
+                        'ratio_N_C': nc,
+                        'ratio_NOPS': nops_c,
+                        'ccs_offset': ccs_offset,
+                        'centrality': None, # future use
+                    }
+                )
+    valid_cpd_ids = [x['id'] for x in pathway_nodes]
+    for edge in list_edges:
+        if edge[0] in valid_cpd_ids and edge[1] in valid_cpd_ids:
+            pathway_edges.append(tuple(edge))
+            
+    return pathway_nodes, set(pathway_edges)
+
+def get_pathway_coordinates(pathway, cpdDict, formula='neutral_formula'):
+    '''
+    Input a pathway in mummichog style.
+    formula : neutral_formula, charged_formula
+    Return coordinates {cpd: (hc, nops_c, ccs_offset), ...}
+
+    Maybe add ccs_offset or other offset methods later.
+    '''
+    cpds = []
+    for C in pathway['cpds']:
+        if C in cpdDict and cpdDict[C][formula]:
+            try:
+                f = cpdDict[C][formula]
+                if 'C' in f and 'H' in f:
+                    hc, oc, nc, nops_c, ccs_offset = get_lcvk_ratios(f, 0) # not using ccs_offset for now
+                    cpds.append(
+                        {
+                            'id': cpdDict[C]['id'],
+                            'name': cpdDict[C]['name'],
+                            formula: f,
+                            'ratio_H_C': hc,
+                            'ratio_O_C': oc,
+                            'ratio_N_C': nc,
+                            'ratio_NOPS': nops_c,
+                            'ccs_offset': ccs_offset,
+                            'centrality': None, # future use
+                        }
+                    )
+                else:
+                    logger.warning("Compound %s has malformed formula: %s", C, f)
+            except KeyError:
+                logger.warning("Compound %s missing from cpdDict or formula field", C)
+    return cpds
+
+def generate_landmarks(hcList, yList):
+    '''returns the geo center and the max of input coordinates'''
+    # Not used now, since there's usually conversion btw Cartesian and Polar
+    return (np.mean(hcList), np.mean(yList)), (max(hcList), max(yList))
+
+#
+# Main function for Li-cvK diagram
+#
+def plot_lcvk_pathway(list_cpds, list_edges,
+                    formula='neutral_formula', cpd_name='name',
+                      ydata='ratio_NOPS', 
+                      show_names=True, show_formula=False, 
+                      flexible_theta=True,
+                      show_landmarks=False, 
+                      max_H_C_allowed=5, 
+                      min_theta=0.1*np.pi, max_theta=1.9*np.pi,
+                      min_radius=0, max_radius=2.5,
+                      padding=0.1, optimization=False,
+                      optimization_spacer=0.3, optimization_iter=3,
+                      fontsize=5, rotation=30, 
+                      width=15, height=15,   # inch
+                      yLabel_off=False,
+                      # marker and edge parameters 
+                      marker='o', facecolors='blue', linewidths=.2, edgecolors='m', s=48, 
+                      alpha=0.5, edge_alpha=0.1, 
+                      title='', outfile='lcvk_plot.pdf', dpi=300
+                      ):
+    '''
+    formula='neutral_formula' is recommended; 'charged_formula' also accepted.
+    cpd_name can use 'id'
+    '''
+    pathway_nodes, pathway_edges = calculate_clean_network(list_cpds, list_edges, formula, 
+                                                           max_H_C_allowed)
+    hcList = [x['ratio_H_C'] for x in pathway_nodes]
+    cartesian_mean_x, cartesian_min_x, cartesian_max_x = np.mean(hcList), min(hcList), max(1, max(hcList))
+    hcList = project_hc_data_radial(hcList)
+    if flexible_theta:
+        min_theta, max_theta = min(hcList), max(hcList)
+    # tick labels; showing original data before polar projection 
+    xlabels = [ 0.8, 1.0, 1.2, 1.4, 1.6, 1.8, 2, 2.2, 2.4]
+    xlabels = [x for x in xlabels if cartesian_min_x < x < cartesian_max_x]
+    if not xlabels:  # data falling out of range, forcing 
+        xlabels = [1.0, 1.1]
+    xticks = project_hc_data_radial(xlabels)
+    
+    ylabels = {'ratio_NOPS': 'NOPS:C', 'ratio_O_C': 'O:C', 'ratio_H_C': 'H:C'} # proper text for axis labels
+    yList = [min(max(x[ydata], min_radius), max_radius) 
+             for x in pathway_nodes]
+    formulas = [x[formula] for x in pathway_nodes]
+    names = [x[cpd_name] for x in pathway_nodes]
+    
+    # optionally optimize text labels here, to avoid too much overlap in cpd names
+    if optimization:
+        hcList, yList = optimize_list_coordinates(hcList, yList, 
+                                              distance_cut=0.1, xspacer=optimization_spacer, 
+                                              rspacer=optimization_spacer, 
+                                              optimization_iter=optimization_iter,
+                                              )
+    
+    layout = dict((x['id'], (hcList[ii], yList[ii])) for ii,x in enumerate(pathway_nodes))
+    
+    fig = plt.figure(figsize=(width, height))
+    ax = fig.subplots(subplot_kw={'projection': 'polar'})
+    ax.set_theta_zero_location('S')
+    ax.set_theta_direction(-1)
+    ax.set_thetalim((min_theta-padding, max_theta+padding))
+    
+    ax.scatter(hcList, yList, marker=marker, facecolors=facecolors, 
+                linewidths=linewidths, edgecolors=edgecolors, s=s, alpha=alpha,
+                )
+    
+    if show_landmarks: # show landmarks if desired
+        center_x, center_r, min_x, max_r = np.mean(hcList), np.mean(yList), min(hcList), max(yList)
+        ax.scatter([center_x, min_x], [center_r, max_r], marker='X', facecolors='w', 
+                    linewidths=.5, edgecolors='r', s=128)
+        # labels need to be original H:C values
+        ax.text(5.7, max_r+.5, f"H:C marks\n{cartesian_min_x:.2f}, {cartesian_mean_x:.2f}", color='r', alpha=.5)
+        # ax.text(center_x, center_r-padding, f"({cartesian_mean_x:.2f}, {center_r:.2f})", color='r', alpha=0.5)
+        # ax.text(min_x, max_r-padding, f"({cartesian_min_x:.2f}, {max_r:.2f})", color='r', alpha=0.5)
+        
+    for ii, f in enumerate(formulas):
+        L = names[ii]
+        if show_names:
+            ax.text(hcList[ii] + .2*padding, yList[ii] - .2*padding, L, color='k',
+                 fontsize=fontsize, rotation=rotation, alpha=0.9)
+        if show_formula:
+            L = f + ', \n' + names[ii]
+            ax.text(hcList[ii] + .2*padding, yList[ii] - .2*padding, L, color='k',
+                 fontsize=fontsize, rotation=rotation, alpha=0.9)
+        
+    for edge in pathway_edges: # cleaned edges to use
+        ax.annotate("",
+            xy=layout[edge[0]], xycoords='data',
+            xytext=layout[edge[1]], textcoords='data',
+            arrowprops=dict(arrowstyle="->", color="0.5", alpha=edge_alpha,
+                            shrinkA=5, shrinkB=5,
+                            patchA=None, patchB=None,
+                            connectionstyle="arc3,rad=-0.3",
+                            ),
+            )
+    ax.set_rorigin(-1)
+    for p in ax.spines.values():
+        # inner, polar, start, end
+        p.set_color('r')
+        p.set_linewidth(0.1)
+        
+    median_y = np.median(yList)
+    ax.set_rgrids([median_y])
+    ax.grid(color='r', linewidth=0.05)
+    # if xticks:
+    ax.set_xticks(xticks)
+    ax.set_xticklabels([str(x) for x in xlabels])
+    ax.text(1.5, max(yList) + .5, "H:C", ) # 
+    if not yLabel_off:
+        ax.text(1.97*np.pi, 1.6, ylabels[ydata], rotation=283)
+    
+    ax.set_title(title)
+    plt.savefig(outfile, dpi=dpi)
+    plt.close(fig)
+
+
+def assign_new_values(hcList, yList, cluttered, distance_min=0.05, iter=5,
+                      xweight=0.02, rweight=0.01):
+    '''
+    cluttered : e.g. [18, 47, 49, 57, 69, 71, 73, 74, 93]
+    add random moves to clustered, and replace values in hcList, yList
+    distance_min : target min euclidean distance btw any two nodes
+    '''
+    new = sorted([(hcList[ii], yList[ii], ii) for ii in cluttered])
+    
+    for ii in range(iter):
+        replacements = [new[0]]
+        for x in new[1:]:
+            if euclidean(x[:2], replacements[-1][:2]) > distance_min:
+                replacements.append(x)
+            else:
+                replacements.append(
+                    (x[0]+ xweight*np.random.random_sample(), 
+                     x[1]+rweight*np.random.random_sample(), x[2])
+                )
+        new = sorted(replacements)
+            
+    for x in replacements:
+        hcList[x[2]] = x[0]
+        yList[x[2]] = x[1]
+    return hcList, yList
+
+def part_twins(hcList, yList, threshod=0.01, xspacer=0.01, rspacer=0.01):
+    '''
+    Separate nodes of identical coordinates
+    '''
+    def _match_(LL, y, threshod): 
+        _r_ = False
+        for x in LL:
+            if euclidean(x, y) < threshod:
+                _r_ = True
+        return _r_
+        
+    LL = list(zip(hcList, yList))
+    new = [LL[0]]
+    for pair in LL[1:]:
+        if _match_(new, pair, threshod):
+            new.append((pair[0]+xspacer, pair[1]+rspacer))
+        else:
+            new.append(pair)
+    return [x[0] for x in new], [x[1] for x in new]
+
+def optimize_list_coordinates(hcList, yList, 
+                              clustersize=2,
+                              distance_cut=0.1, 
+                              optimization_iter=5,
+                              xspacer=0.01, rspacer=0.01):
+    '''
+    add spacer to cluttered nodes
+    Example cluster:
+        3.5241459360629888 0.26
+        3.5241459360629888 0.26
+        3.5241459360629888 0.26
+        3.4270902040763933 0.2826086956521739
+        3.4776400644860788 0.2708333333333333
+        3.5241459360629888 0.26
+        3.4270902040763933 0.2826086956521739
+        3.4776400644860788 0.2708333333333333
+        3.5241459360629888 0.26
+    
+    '''
+    YM = pdist(list(zip(hcList, yList)), 'euclidean')
+    ZM = linkage(YM, method='complete')
+    metClus = fcluster(ZM, distance_cut, criterion='distance')
+    # Compile clusters
+    metClusDict = {}
+    for ii in range(len(metClus)):
+        if metClus[ii] in metClusDict:
+            metClusDict[ metClus[ii] ].append(ii)
+        else:
+            metClusDict[ metClus[ii] ] = [ii]
+
+    # print("number of clusters: ", len(metClusDict.keys()))
+    for k,v in metClusDict.items():
+        if len(v) >= clustersize:
+            hcList, yList = assign_new_values(hcList, yList, v, 
+                                              distance_min=0.05,
+                                              iter=optimization_iter)
+            
+    hcList, yList = part_twins(hcList, yList, threshod=0.1, xspacer=xspacer, rspacer=rspacer)
+    return hcList, yList
+   
+
+def populate_cpd_coordinates(cpdDict, formula='neutral_formula'):
+    # full cpds
+    allcpds = []
+    for C in cpdDict.values():
+        if C[formula]:
+            try:
+                f = C[formula]
+                if 'C' in f and 'H' in f:
+                    hc, oc, nc, nops_c, ccs_offset = get_lcvk_ratios(f, 0) #
+                    allcpds.append(
+                        {
+                            'id': C['id'],
+                            'name': C['name'],
+                            formula: f,
+                            'ratio_H_C': hc,
+                            'ratio_O_C': oc,
+                            'ratio_N_C': nc,
+                            'ratio_NOPS': nops_c,
+                            'ccs_offset': ccs_offset,
+                            'centrality': None, # future use
+                        }
+                    )
+                else:
+                    logger.warning("Compound %s has malformed formula: %s", C, f)
+            except KeyError:
+                logger.warning("Compound %s missing 'id' or formula field", C)
+                
+    return allcpds
+
+
+def plot_lcvk_cartesian_pathway(pathway_nodes, pathway_edges,
+                                ydata='ratio_NOPS',
+                                show_names=True, show_formula=False, 
+                                fontsize=5, rotation=30, padding=0.01,
+                                width=8, height=8,   # inch
+                                ylim=None, # or max value of yaxis
+                                title='', outfile='cartesian_vk_plot.pdf', dpi=300
+                                ):
+    hcList = [x['ratio_H_C'] for x in pathway_nodes]
+    yList = [x[ydata] for x in pathway_nodes]
+    formulas = [x['neutral_formula'] for x in pathway_nodes]
+    names = [x['name'] for x in pathway_nodes]
+    ylabels = {'ratio_NOPS': 'NOPS:C', 'ratio_O_C': 'O:C', 'ratio_H_C': 'H:C'} # proper text for axis labels
+    
+    layout = dict((x['id'], (hcList[ii], yList[ii])) for ii,x in enumerate(pathway_nodes))
+    
+    _nodes = [x['id'] for x in pathway_nodes]
+    #sizes = [len(fdict[x[0]]) * 3 for x in kv_list_gem]
+    
+    text_offset = padding
+    plt.figure(figsize=(width, height))
+    ax = plt.subplot()
+    ax.scatter(hcList, yList, marker='o', facecolors='blue', 
+               linewidths=.2, edgecolors='m', s=48, alpha=0.5,
+                )
+    for ii, f in enumerate(formulas):
+        L = names[ii]
+        if show_names:
+            ax.text(hcList[ii] + text_offset/2, yList[ii] + text_offset, L, 
+                 fontsize=fontsize, rotation=rotation, alpha=0.5)
+        if show_formula:
+            L = f + ', \n' + names[ii]
+            ax.text(hcList[ii] + text_offset/2, yList[ii] + text_offset, L, 
+                    fontsize=fontsize, rotation=rotation, alpha=0.5)
+        
+    for edge in pathway_edges:
+        if edge[0] in _nodes and edge[1] in _nodes:
+            ax.annotate("",
+                xy=layout[edge[0]], xycoords='data',
+                xytext=layout[edge[1]], textcoords='data',
+                arrowprops=dict(arrowstyle="->", color="0.5", alpha=0.2,
+                                shrinkA=5, shrinkB=5,
+                                patchA=None, patchB=None,
+                                connectionstyle="arc3,rad=-0.3",
+                                ),
+                )
+        
+    ax.set_xlabel("H:C ratio")
+    if ylim:
+        ax.set_ylim((0, ylim))
+    ax.set_ylabel(ylabels[ydata])
+    ax.set_title(title)
+    plt.savefig(outfile, dpi=dpi)
+    plt.close()
+
+
+# experimenting
+def nx_fruchterman_reingold(pathway_edges, posDict,
+    k=0.05, fixed=None, iterations=5, threshold=0.0001, dim=2, 
+):
+    '''
+    Modified from networkx._fruchterman_reingold
+    '''
+    import networkx as nx
+    
+    G = nx.from_edgelist(pathway_edges)
+    A = nx.to_scipy_sparse_array(G)
+    nnodes = len(G)
+
+    pos = np.zeros((len(G), dim)) 
+    for i, n in enumerate(G):
+        if n in posDict:
+            pos[i] = np.asarray(posDict[n])
+
+    # the initial "temperature"  is about .1 of domain area (=1x1)
+    # this is the largest step allowed in the dynamics.
+    # We need to calculate this in case our fixed positions force our domain
+    # to be much bigger than 1x1
+    t = 0.001
+    # simple cooling scheme.
+    # linearly step down by dt on each iteration so last iteration is size dt.
+    dt = t / (iterations + 1)
+    delta = np.zeros((pos.shape[0], pos.shape[0], pos.shape[1]), dtype=A.dtype)
+    # the inscrutable (but fast) version
+    # this is still O(V^2)
+    # could use multilevel methods to speed this up significantly
+    for iteration in range(iterations):
+        
+        print(pos[0])
+        
+        # matrix of difference between points
+        delta = pos[:, np.newaxis, :] - pos[np.newaxis, :, :]
+        # distance between points
+        distance = np.linalg.norm(delta, axis=-1)
+        # enforce minimum distance of 0.01
+        np.clip(distance, 0.01, None, out=distance)
+        # displacement "force"
+        displacement = np.einsum(
+            "ijk,ij->ik", delta, (k * k / distance**2 - A * distance / k)
+        )
+        # update positions
+        length = np.linalg.norm(displacement, axis=-1)
+        length = np.where(length < 0.01, 0.1, length)
+        delta_pos = np.einsum("ij,i->ij", displacement, t / length)
+        if fixed is not None:
+            # don't change positions of fixed nodes
+            delta_pos[fixed] = 0.0
+        pos += delta_pos
+        # cool temperature
+        t -= dt
+        if (np.linalg.norm(delta_pos) / nnodes) < threshold:
+            break
+    return pos
+

lcvk-0.1.1/lcvk/recipes.py

@@ -0,0 +1,204 @@
+#
+# Misc. receipes; likely of bad taste
+#
+import os
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from .polarPlot import standardize_data
+
+__all__ = [
+    'differential_metabolites', 'plot_lcvk_global_metabolites',
+    'plot_lcvk_global_metabolites_colored', 'plot_lcvk_pathway_batch',
+]
+
+def differential_metabolites(list_cpds):
+    '''
+    Coloring differential metabolites from metabolomics data
+    '''
+    raise NotImplementedError
+
+
+
+def plot_lcvk_global_metabolites(allcpds):
+    '''Illustration only'''
+    YMAX = 2.5
+    theta_limit = (0.1*np.pi, 1.9*np.pi)
+    theta_offset = 0.05         # so that nodes do not sit on border lines
+    hcList = [max(min(x['ratio_H_C'], 2.5), 0.5) for x in allcpds]
+    hcList = standardize_data(hcList)
+
+    # ticks reverse function of standardize_data
+    xlabels = [ 0.8, 1.1, 1.4, 1.7, 2, 2.3]
+    xticks = standardize_data(xlabels)
+
+    yList = [min(x['ratio_NOPS'] + x['ccs_offset'], YMAX) 
+            for x in allcpds]
+
+    fig = plt.figure(figsize=(12, 12))
+    ax = fig.subplots(subplot_kw={'projection': 'polar',  } 
+    )
+    c = ax.scatter(hcList, yList, marker='o', facecolors='w', 
+                    linewidths=.3, edgecolors='k', 
+                    s=16,
+    )
+    ax.set_theta_zero_location('S')
+    ax.set_theta_direction(-1)
+    ax.set_thetalim((theta_limit[0]-theta_offset, theta_limit[1]+theta_offset))
+    ax.set_ylim(0, YMAX + 0.1)
+    ax.set_xticks(xticks)
+    ax.set_xticklabels([str(x) for x in xlabels])
+
+    ax.set_rgrids([0.5, 1.5])
+    ax.grid(color='r', linewidth=0.1)
+    for p in ax.spines.values():
+        # inner, polar, start, end
+        p.set_color('r')
+        p.set_linewidth(0.2)
+
+    ax.set_rorigin(-1)
+    ax.text(1.7, YMAX + .45, "H:C", )
+    ax.text(1.96*np.pi, 1.6, "NOPS:C", rotation=285)
+    ax.set_title("Global metabolites")
+    plt.savefig('gem_mar2025_ratio_NOPS.pdf', dpi=300)
+    plt.close(fig)
+
+
+def plot_lcvk_global_metabolites_colored(allcpds, collections, colors_collections,
+                        outfile='gem_mar2025_ratio_NOPS_colorExamples.pdf'):
+    '''
+    Illustration only.
+    collections: list of index lists into allcpds/hcList/yList, one per highlighted group.
+    colors_collections: matplotlib color name for each group in collections.
+    '''
+    YMAX = 2.5
+    theta_limit = (0.1*np.pi, 1.9*np.pi)
+    theta_offset = 0.05         # so that nodes do not sit on border lines
+    hcList = [max(min(x['ratio_H_C'], 2.5), 0.5) for x in allcpds]
+    hcList = standardize_data(hcList)
+
+    # ticks reverse function of standardize_data
+    xlabels = [ 0.8, 1.1, 1.4, 1.7, 2, 2.3]
+    xticks = standardize_data(xlabels)
+
+    yList = [min(x['ratio_NOPS'] + x['ccs_offset'], YMAX)
+            for x in allcpds]
+
+    fig = plt.figure(figsize=(8,8))
+    ax = fig.subplots(subplot_kw={'projection': 'polar',  }
+    )
+
+    c = ax.scatter(hcList, yList, marker='o', facecolors='w',
+                    linewidths=.3, edgecolors='k',
+                    s=16,
+    )
+
+    for ii in range(len(collections)):
+        XX = [hcList[j] for j in collections[ii]]
+        YY = [yList[j] for j in collections[ii]]
+        ax.scatter(XX, YY, marker='o', facecolors=colors_collections[ii], s=24, alpha=.5)
+
+    ax.set_theta_zero_location('S')
+    ax.set_theta_direction(-1)
+    ax.set_thetalim((theta_limit[0]-theta_offset, theta_limit[1]+theta_offset))
+    ax.set_ylim(0, YMAX + 0.1)
+    ax.set_xticks(xticks)
+    ax.set_xticklabels([str(x) for x in xlabels])
+
+    ax.set_rgrids([0.5, 1.5])
+    ax.grid(color='r', linewidth=0.1)
+    for p in ax.spines.values():
+        # inner, polar, start, end
+        p.set_color('r')
+        p.set_linewidth(0.2)
+
+    ax.set_rorigin(-1)
+    ax.text(1.7, YMAX + .45, "H:C", )
+    ax.text(1.96*np.pi, 1.6, "NOPS:C", rotation=285)
+    ax.set_title("Global metabolites")
+    plt.savefig(outfile, dpi=300)
+    plt.close(fig)
+
+
+def plot_lcvk_pathway_batch(pathway_nodes, pathway_edges, title,
+                          ydata='ratio_NOPS', 
+                      fontsize=5, rotation=30, show_names=True, show_formula=False, outdir='.'
+                      ):
+    theta_limit = (0.1*np.pi, 1.9*np.pi)
+    theta_offset = 0.05         # so that nodes do not sit on border lines
+    hcList = [max(min(x['ratio_H_C'], 2.5), 0.3) for x in pathway_nodes]
+    hcList = standardize_data(hcList)
+    
+    # ticks reverse function of standardize_data
+    xlabels = [0.8, 1.1, 1.4, 1.7, 2, 2.3]
+    xticks = standardize_data(xlabels)
+    
+    YMAX = 3
+    yList = [min(x[ydata] + x['ccs_offset'], YMAX)  for x in pathway_nodes]
+    
+    formulas = [x['neutral_formula'] for x in pathway_nodes]
+    names = [x['name'] for x in pathway_nodes]
+    
+    layout = dict((x['id'], (hcList[ii], yList[ii])) for ii,x in enumerate(pathway_nodes))
+    
+    _nodes = [x['id'] for x in pathway_nodes]
+    #sizes = [len(fdict[x[0]]) * 3 for x in kv_list_gem]
+    
+    text_offset = 0.01
+    fig = plt.figure(figsize=(15,15))
+    ax = fig.subplots(subplot_kw={'projection': 'polar'})
+    ax.set_theta_zero_location('S')
+    ax.set_theta_direction(-1)
+    ax.set_thetalim((theta_limit[0]-theta_offset, theta_limit[1]+theta_offset))
+    ax.set_ylim(0, 3.1)
+    
+    ax.scatter(hcList, yList, marker='o', facecolors='blue', 
+                linewidths=.2, edgecolors='m', 
+                s=48, alpha=0.5,
+                )
+    
+    # optionally optimize text labels here, to avoid too much overlap in cpd names
+    
+    for ii, f in enumerate(formulas):
+        L = names[ii]
+        if show_names:
+            ax.text(hcList[ii], yList[ii] - text_offset, L, color='k',
+                 fontsize=fontsize, rotation=rotation, alpha=0.9)
+        if show_formula:
+            L = f + ', \n' + names[ii]
+            ax.text(hcList[ii], yList[ii] - text_offset, L, color='k',
+                 fontsize=fontsize, rotation=rotation, alpha=0.9)
+        
+    for edge in set(pathway_edges):     # set to remove repeated edges; edge has to be tuple
+        if edge[0] in _nodes and edge[1] in _nodes:
+            ax.annotate("",
+                xy=layout[edge[0]], xycoords='data',
+                xytext=layout[edge[1]], textcoords='data',
+                arrowprops=dict(arrowstyle="->", color="0.5", alpha=0.2,
+                                shrinkA=5, shrinkB=5,
+                                patchA=None, patchB=None,
+                                connectionstyle="arc3,rad=-0.3",
+                                ),
+                )
+    
+    ax.set_xticks(xticks)
+    ax.set_xticklabels([str(x) for x in xlabels])
+
+    ax.set_rgrids([0.5, 2])
+    ax.grid(color='r', linewidth=0.05)
+    for p in ax.spines.values():
+        # inner, polar, start, end
+        p.set_color('r')
+        p.set_linewidth(0.1)
+
+    ax.set_rorigin(-1)
+    ax.text(1.7, YMAX + .35, "H:C", )
+    ax.text(1.945*np.pi, 1.6, ydata, rotation=285)
+    
+    ax.set_title(title) # "KV-Li plot"
+    plt.savefig(
+        os.path.join(outdir,
+        title.replace('/', '__') + '.pdf')
+        )
+    plt.close(fig)

lcvk-0.1.1/lcvk.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+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

lcvk-0.1.1/lcvk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+requirements.txt
+setup.py
+lcvk/__init__.py
+lcvk/main.py
+lcvk/metModels.py
+lcvk/polarPlot.py
+lcvk/recipes.py
+lcvk.egg-info/PKG-INFO
+lcvk.egg-info/SOURCES.txt
+lcvk.egg-info/dependency_links.txt
+lcvk.egg-info/requires.txt
+lcvk.egg-info/top_level.txt
+lcvk.egg-info/zip-safe

lcvk-0.1.1/lcvk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lcvk-0.1.1/lcvk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy
+scipy
+matplotlib
+mass2chem

lcvk-0.1.1/lcvk.egg-info/top_level.txt

@@ -0,0 +1 @@
+lcvk

lcvk-0.1.1/lcvk.egg-info/zip-safe

@@ -0,0 +1 @@
+

lcvk-0.1.1/requirements.txt

@@ -0,0 +1,4 @@
+numpy
+scipy
+matplotlib
+mass2chem

lcvk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lcvk-0.1.1/setup.py

@@ -0,0 +1,53 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+
+with open(os.path.join(here, "lcvk", "__init__.py")) as f:
+    exec([x for x in f.readlines() if '__version__' in x][0])
+
+with open(os.path.join(here, "README.md"), "r") as fh:
+    long_description = fh.read()
+
+with open(os.path.join(here, "requirements.txt"), "r") as f:
+    requirements = f.read()
+
+
+setup(
+  name='lcvk',
+  version=__version__,
+  author='Shuzhao Li',
+  author_email='shuzhao.li@gmail.com',
+  description='Li-circular van Krevelen diagram',
+  long_description=long_description,
+  long_description_content_type="text/markdown",
+  url='https://github.com/shuzhao-li-lab/Li_CVK_diagram',
+  license='BSD 3-Clause',
+  keywords='bioinformatics metabolic pathway visualization',
+
+  classifiers=[
+    'Intended Audience :: Developers',
+    'Intended Audience :: Science/Research',
+    'License :: OSI Approved :: BSD License',
+    'Natural Language :: English',
+    'Operating System :: OS Independent',
+    'Programming Language :: Python :: 3',
+    'Topic :: Scientific/Engineering :: Bio-Informatics',
+    'Topic :: Scientific/Engineering :: Chemistry',
+    'Topic :: Software Development :: Libraries :: Python Modules',
+  ],
+
+  packages=find_packages(
+    include=['lcvk', 'lcvk.*']
+  ),
+  data_files=[  ],
+  include_package_data=True,
+  zip_safe=True,
+  entry_points = {
+    },
+
+  python_requires='>=3.7',
+  install_requires=requirements,
+
+)