Metabolite Structural Network Construction

metabolite-structural-network-construction

Summary

Constructs an interactive or static network graph of mass spectrometry features organized into structural clusters by the MAMSI framework, where nodes represent features and edges encode isotopologue, adduct, and cross-assay relationships. This skill visualizes and curates the linkage structure among statistically significant LC-MS features identified from multi-assay metabolomics data.

When to use

After MamsiStructSearch has completed structural clustering of statistically significant LC-MS features (p < 0.01), and you need to visualize feature relationships as a network, inspect edge types (isotopologue, adduct, cross-assay), or export the graph for downstream curation in tools like Cytoscape. Use this skill when your goal is to understand feature connectivity and validate structural relationships identified by mass-to-charge ratio and retention time matching.

When NOT to use

• Structural clusters have not yet been generated by MamsiStructSearch — run get_structural_clusters() first.
• Your goal is only to identify which features belong to the same metabolite — use the cluster membership columns directly rather than visualizing the full network.
• Feature set is extremely large (>10,000 nodes) and interactive rendering becomes prohibitively slow — consider filtering by structural cluster or correlation cluster before visualization.

Inputs

• pandas.DataFrame with MAMSI structural clusters (output from MamsiStructSearch.get_structural_clusters())
• Columns: Feature, Assay, Isotopologue group, Isotopologue pattern, Adduct group, Adduct, Structural cluster, Correlation cluster, Cross-assay link, optional cpdName
• Optional: hierarchical correlation cluster assignments (from MamsiStructSearch.get_correlation_clusters())

Outputs

• networkx.Graph object (if return_nx_object=True)
• HTML interactive network visualization file (if interactive=True)
• matplotlib figure with static network layout and optional node labels (if interactive=False)

How to apply

Load the structural clusters DataFrame output from MamsiStructSearch (containing Feature, Assay, Isotopologue group, Isotopologue pattern, Adduct group, Adduct, Structural cluster, Correlation cluster, Cross-assay link, and optional cpdName columns). Construct a NetworkX graph with features as nodes, assigning node attributes (assay, cluster membership, compound name). Create weighted edges between features based on structural relationship type: isotopologue links (weight=1), adduct links (weight=5), and cross-assay links (weight=10). Set the include_all parameter to control whether to include all features or only those with structural links. Render interactively using pyvis with force-directed layout and save as HTML, or render statically using NetworkX/matplotlib with optional labels. If return_nx_object=True, capture the NetworkX graph object for programmatic inspection or export to other tools.

Related tools

• networkx (Graph construction, node/edge attribute assignment, and programmatic inspection of network topology)
• pyvis (Force-directed interactive visualization and HTML export of the feature network)
• matplotlib (Static network rendering with optional node labels and customizable layout)
• MamsiStructSearch (Upstream structural clustering and isotopologue/adduct/cross-assay link detection) — https://github.com/kopeckylukas/py-mamsi
• Cytoscape (External network curation and visual inspection of exported NetworkX objects)

Examples

network = struct.get_structural_network(include_all=True, interactive=False, labels=True, return_nx_object=True)

Evaluation signals

• Graph contains all expected features as nodes (or only linked features if include_all=False); node count matches input DataFrame
• Edge weights follow the schema: isotopologue=1, adduct=5, cross-assay=10; edge count reflects structural cluster membership
• Node attributes (assay, cluster membership, compound name) are correctly assigned and accessible via NetworkX node property inspection
• Interactive HTML output renders in a web browser with force-directed layout and pan/zoom interactions; static output displays without errors
• NetworkX object can be serialized to GraphML or other formats and successfully imported into external tools like Cytoscape for curation

Limitations

• Network visualization performance degrades for feature sets >5,000–10,000 nodes; consider clustering or filtering before rendering.
• Edge weights are fixed by relationship type and cannot be dynamically adjusted based on confidence or other metrics in this workflow step.
• The framework has been tested on metabolomics phenotyping data from National Phenome Centre assays (HPOS, LPOS, LNEG, etc.) but may require parameter tuning (rt_win, ppm) for other LC-MS platforms or ionization modes.
• Annotation of features (compound names) is only supported for assays analyzed by the National Phenome Centre; other data will lack automated cpdName assignment.
• Cross-assay link detection uses only [M+H]⁺/[M-H]⁻ as reference pairs; other adduct relationships across assays are not currently linked.

Evidence

• [methods] 1. Load structural clusters and correlation clusters from MamsiStructSearch output (DataFrame with Feature, Assay, Isotopologue group, Isotopologue pattern, Adduct group, Adduct, Structural cluster, Correlation cluster, Cross-assay link, and optional cpdName columns).: "Load structural clusters and correlation clusters from MamsiStructSearch output (DataFrame with Feature, Assay, Isotopologue group, Isotopologue pattern, Adduct group, Adduct, Structural cluster,"
• [methods] 2. Construct a NetworkX graph with features as nodes, assigning node attributes (assay, cluster membership, compound name). 3. Create edges between features based on structural relationships: isotopologue links (weight=1), adduct links (weight=5), and cross-assay links (weight=10).: "Construct a NetworkX graph with features as nodes, assigning node attributes (assay, cluster membership, compound name). 3. Create edges between features based on structural relationships:"
• [methods] 4. Optionally include all features in the network or only those with structural links, controlled by the include_all parameter. 5. Render the graph interactively using pyvis with force-directed layout and save as HTML output_file, or display statically using NetworkX and matplotlib with optional node labels.: "Optionally include all features in the network or only those with structural links, controlled by the include_all parameter. 5. Render the graph interactively using pyvis with force-directed layout"
• [methods] If return_nx_object=True, return the NetworkX graph object for downstream curation.: "If return_nx_object=True, return the NetworkX graph object for downstream curation."
• [readme] You can also save the network as an NX object and review in Cytoscape to get better insight on what the structural relationships between individual features are (e.g. adduct links, isotopologues, cross-assay links).: "You can also save the network as an NX object and review in Cytoscape to get better insight on what the structural relationships between individual features are (e.g. adduct links, isotopologues,"
• [readme] The different node colours represent different flattened hierarchical correlation clusters, while the edges between nodes identify their structural links.: "The different node colours represent different flattened hierarchical correlation clusters, while the edges between nodes identify their structural links."
• [methods] MAMSI uses NetworkX and pyvis dependencies to generate structural network graphs that link features organized into clusters by MamsiStructSearch based on their mass-to-charge ratio and retention time properties.: "MAMSI uses NetworkX and pyvis dependencies to generate structural network graphs that link features organized into clusters by MamsiStructSearch based on their mass-to-charge ratio and retention time"