# Pairwise Mass Comparison Computation

> Use when after peak m/z values and molecular formulas have been extracted and pre-processed from FT-ICR MS data, and you need to reconstruct biochemical transformation networks ab initio.

- Skill: `holobiomicslab/pairwise-mass-comparison-computation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/pairwise-mass-comparison-computation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/pairwise-mass-comparison-computation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- 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/pairwise-mass-comparison-computation

---


# pairwise-mass-comparison-computation

## Summary

Compute all pairwise mass differences between detected peaks in FT-ICR MS data to identify potential biochemical transformations. This vectorized subtraction yields a difference matrix that serves as input to transformation network reconstruction.

## When to use

After peak m/z values and molecular formulas have been extracted and pre-processed from FT-ICR MS data, and you need to reconstruct biochemical transformation networks ab initio. Apply this skill when you have a list of detected masses for a single sample and want to identify which pairs of masses correspond to known biochemical transformations (e.g., oxidation, methylation, dehydration).

## When NOT to use

- Input consists of already-processed transformation networks or pre-computed edge tables (redundant application).
- Peak list contains unresolved chemical isomers without mass differences as discriminators (FT-ICR MS cannot separate isomers, so mass differences alone may not be informative).
- Mass accuracy of the instrument is worse than ~2 ppm, making 1 ppm error tolerance too stringent to recover true transformations.

## Inputs

- Peak m/z list (CSV format with columns: m/z, molecular_formula, molecular_class)
- Pre-defined biochemical transformation reference key (mass difference → transformation name mapping with error tolerances)
- Single sample from pre-processed FT-ICR MS output

## Outputs

- Edge table (CSV): source peak m/z, target peak m/z, mass difference, transformation name, biotic/abiotic classification
- Pairwise mass difference matrix (n×n, where n = number of peaks)
- Matched transformation list with classification labels

## How to apply

Load the peak m/z list and assigned molecular formulas from the pre-processed CSV output for a single sample. Use vectorized subtraction (NumPy broadcasting) to compute all pairwise mass differences between detected peaks—this produces an n×n difference matrix where n is the number of peaks. Retain only mass differences that fall within ±1 ppm error tolerance when matched against a pre-defined biochemical transformation reference key. Match each retained difference to a transformation name and classification (biotic or abiotic) using the reference database. The rationale is that FT-ICR MS ultra-high mass accuracy (typically sub-ppm) makes mass differences a reliable proxy for specific chemical modifications; the 1 ppm tolerance accounts for measurement uncertainty while rejecting spurious matches.

## Related tools

- **NumPy** (Vectorized subtraction of m/z values to compute all pairwise mass differences efficiently)
- **pandas** (Load, store, and manipulate peak m/z lists and difference matrices as DataFrames)
- **MetaboDirect** (Command-line pipeline that orchestrates pairwise mass comparison as step 3 of transformation network analysis) — https://github.com/Coayala/MetaboDirect
- **FT-ICR MS** (Source instrument providing ultra-high mass accuracy (sub-ppm) that enables reliable mass difference matching)

## Evaluation signals

- Pairwise difference matrix is symmetric and has zeros on the diagonal (mathematical consistency).
- All retained mass differences fall within ±1 ppm of their assigned transformation in the reference key (error tolerance met).
- Edge table has no duplicate edges (same source–target pair listed only once per transformation type).
- Every matched transformation is present in the reference key with a biotic or abiotic label; no unclassified transformations leak through.
- Mass difference values in output edge table are consistent with known biochemical modifications (e.g., +15.99 for oxidation, +14.02 for methylation); spot-check a random sample against reference.

## Limitations

- Cannot distinguish chemical isomers, as FT-ICR MS lacks chromatographic separation; mass differences alone do not disambiguate isomeric pairs.
- Assumes reference transformation key is complete and error tolerances are calibrated for the specific instrument and sample matrix; miscalibrated tolerances will produce false positives or false negatives.
- Vectorized computation becomes memory-intensive for samples with very large peak counts (e.g., >10,000 peaks); consider subsampling or chunking for such cases.
- Does not account for ion suppression or enhancement effects, which can cause weak or missing peaks and thus incompletely sampled transformation networks.

## Evidence

- [methods] Compute all pairwise mass differences between peaks using vectorized subtraction.: "Compute all pairwise mass differences between peaks using vectorized subtraction."
- [methods] Match each mass difference against the pre-defined biochemical transformation key, retaining matches with ≤1 ppm error tolerance.: "Match each mass difference against the pre-defined biochemical transformation key, retaining matches with ≤1 ppm error tolerance."
- [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: "nodes represent masses and edges represent the mass differences corresponding to specific biochemical transformations"
- [readme] MetaboDirect requires Python (3.5 and above), R (4 and above) and Cytoscape (3.8 and above) with the following libraries/modules: numpy, pandas: "MetaboDirect requires Python (3.5 and above), R (4 and above) and Cytoscape (3.8 and above) with the following libraries/modules: numpy, pandas"