# Mass Difference Network Construction

> Use when you have a preprocessed peak list (m/z values and assigned molecular formulas) from direct injection FT-ICR MS of a complex organic mixture (e.

- Skill: `holobiomicslab/mass-difference-network-construction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-difference-network-construction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-difference-network-construction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/mass-difference-network-construction

---


# mass-difference-network-construction

## Summary

Constructs biochemical transformation networks ab initio from FT-ICR MS peak data by computing all pairwise mass differences between detected m/z values and matching them against a reference database of known biochemical transformations. This skill enables discovery of metabolic pathways and hub metabolites without requiring compound identification or chromatographic separation.

## When to use

Apply this skill when you have a preprocessed peak list (m/z values and assigned molecular formulas) from direct injection FT-ICR MS of a complex organic mixture (e.g., environmental samples, microbial cultures, or natural organic matter), and you want to infer which biochemical transformations have occurred within the sample. Use it specifically when ultra-high mass accuracy (sub-ppm error tolerance) allows reliable matching of mass differences to known transformations, and when you seek to identify transformation hubs and network topology rather than individual compound identities.

## When NOT to use

- Input peak list lacks molecular formula assignments or has low mass accuracy (>5 ppm error); mass difference matching will fail or produce false positives.
- Sample has been chromatographically separated (LC-MS) prior to analysis; you should use retention time and fragmentation patterns instead of mass-difference networks.
- Goal is to identify individual compound structures or absolute metabolite quantities; transformation networks reveal relative pathway connectivity, not species identity or abundance.

## Inputs

- Preprocessed peak m/z list (CSV format)
- Assigned molecular formulas for peaks
- Reference biochemical transformation database with mass differences and biotic/abiotic classification
- Mass accuracy specification for FT-ICR MS instrument (typically sub-ppm)

## Outputs

- Edge table (CSV): source m/z, target m/z, mass difference, transformation name, biotic/abiotic class
- Node table (CSV): peak m/z values, molecular class assignments
- Cytoscape-compatible network files
- Network statistics (degree distribution, component count, hub metabolite rankings)

## How to apply

Load the preprocessed peak m/z list and molecular formulas from CSV output. Compute all pairwise mass differences using vectorized subtraction (NumPy) across the entire peak set. Match each observed mass difference against a reference biochemical transformation key, retaining only matches with ≤1 ppm error tolerance to exploit FT-ICR MS mass accuracy. Classify each matched transformation as biotic or abiotic according to the reference key. Generate an edge table (CSV) recording source m/z, target m/z, mass difference, transformation name, and classification for all validated transformations. Generate a complementary node table (CSV) listing all peaks and their molecular class assignments. Export both tables in Cytoscape-compatible format and compute network statistics (degree distribution, connected component count) to characterize metabolic topology.

## Related tools

- **MetaboDirect** (Command-line pipeline orchestrating full mass-difference network construction workflow including pairwise difference computation, transformation matching, network export, and visualization) — https://github.com/Coayala/MetaboDirect
- **NumPy** (Vectorized array computation for efficient pairwise mass difference subtraction across peak sets)
- **pandas** (Tabular data manipulation for loading peak lists, filtering results, and generating edge/node CSV tables)
- **Cytoscape** (Interactive network visualization and analysis of generated transformation graphs with degree/topology statistics)
- **KEGG database** (Reference source for known biochemical transformations and mass differences used to build the transformation matching key)

## Examples

```
metabodirect -i sample_peaks.csv -f formulas.csv -o output_dir --transformation_db kegg_transformations.csv --ppm_tolerance 1
```

## Evaluation signals

- All pairwise mass differences computed without exception (output edge count ≤ n(n−1)/2 where n = peak count); missing pairs indicate computation failure.
- Every matched transformation mass difference is within ≤1 ppm error tolerance of the reference database entry; audit a random sample of 50+ matches against KEGG.
- Edge and node tables have consistent m/z coverage (all m/z values in edge table appear in node table; node table contains only m/z present in raw input); schema validation for required columns (source m/z, target m/z, mass difference, transformation name, biotic/abiotic).
- Network exhibits expected topological properties for metabolic systems: degree distribution is skewed (few hub metabolites with high degree); connected component count is reasonable relative to sample complexity (typically 1–5 major components for environmental samples).
- Biotic transformations align with known microbial metabolism (e.g., demethylation, oxidation, acetylation); spot-check transformation types against literature on sample type (e.g., soil, peatland leachate, wastewater).

## Limitations

- Cannot distinguish chemical isomers: mass-difference networks conflate structural isomers with identical mass; FT-ICR MS lacks fine resolving power to separate them without complementary NMR or MS/MS fragmentation.
- Ion suppression and signal enhancement can cause false negatives (missed transformations) or false positives (spurious peaks misidentified as transformed metabolites).
- Reference transformation database must be curated and comprehensive; missing or incorrect entries in the reference key will produce incomplete or incorrect networks.
- Mass difference matching assumes transformations are elementary (single step); multi-step pathways involving intermediate species undetected in the sample will not be resolved.

## Evidence

- [other] MetaboDirect generates molecular transformation networks by identifying mass differences between detected masses in a sample, using the ultra-high mass accuracy of FT-ICR MS to recognize chemically transformed species: "MetaboDirect generates molecular transformation networks by identifying mass differences between detected masses in a sample, using the ultra-high mass accuracy of FT-ICR MS to recognize chemically"
- [other] Nodes represent masses and edges represent the mass differences corresponding to specific biochemical transformations, with network outputs showing hub metabolites and transformation types: "nodes represent masses and edges represent the mass differences corresponding to specific biochemical transformations, with network outputs showing hub metabolites and transformation types"
- [other] Compute all pairwise mass differences between peaks using vectorized subtraction. Match each mass difference against the pre-defined biochemical transformation key, retaining matches with ≤1 ppm error tolerance.: "Compute all pairwise mass differences between peaks using vectorized subtraction. 3. Match each mass difference against the pre-defined biochemical transformation key, retaining matches with ≤1 ppm"
- [other] Classify retained transformations as biotic or abiotic according to the reference key. Generate edge table (CSV) listing source peak m/z, target peak m/z, mass difference, transformation name, and classification.: "Classify retained transformations as biotic or abiotic according to the reference key. 5. Generate edge table (CSV) listing source peak m/z, target peak m/z, mass difference, transformation name, and"
- [abstract] MetaboDirect is also uniquely able to automatically generate biochemical transformation networks (ab initio) based on mass differences: "MetaboDirect is also uniquely able to automatically generate biochemical transformation networks (ab initio) based on mass differences"
- [intro] Even though DI-MS has ample coverage and can detect a wide range of compounds (e.g., lipids, sugars, amino acids, or lignin), some drawbacks are its inability to separate chemical isomers, lack of: "Even though DI-MS has ample coverage and can detect a wide range of compounds (e.g., lipids, sugars, amino acids, or lignin), some drawbacks are its inability to separate chemical isomers"
- [methods] consists of two main processes: the calculation of mass-based chemical transformations: "consists of two main processes: the calculation of mass-based chemical transformations"