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"
1---2name: pairwise-mass-comparison-computation3description: 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.4license: CC-BY-4.05---67# pairwise-mass-comparison-computation89## Summary1011Compute 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.1213## When to use1415After 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).1617## When NOT to use1819- Input consists of already-processed transformation networks or pre-computed edge tables (redundant application).20- 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).21- Mass accuracy of the instrument is worse than ~2 ppm, making 1 ppm error tolerance too stringent to recover true transformations.2223## Inputs2425- Peak m/z list (CSV format with columns: m/z, molecular_formula, molecular_class)26- Pre-defined biochemical transformation reference key (mass difference → transformation name mapping with error tolerances)27- Single sample from pre-processed FT-ICR MS output2829## Outputs3031- Edge table (CSV): source peak m/z, target peak m/z, mass difference, transformation name, biotic/abiotic classification32- Pairwise mass difference matrix (n×n, where n = number of peaks)33- Matched transformation list with classification labels3435## How to apply3637Load 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.3839## Related tools4041- **NumPy** (Vectorized subtraction of m/z values to compute all pairwise mass differences efficiently)42- **pandas** (Load, store, and manipulate peak m/z lists and difference matrices as DataFrames)43- **MetaboDirect** (Command-line pipeline that orchestrates pairwise mass comparison as step 3 of transformation network analysis) — https://github.com/Coayala/MetaboDirect44- **FT-ICR MS** (Source instrument providing ultra-high mass accuracy (sub-ppm) that enables reliable mass difference matching)4546## Evaluation signals4748- Pairwise difference matrix is symmetric and has zeros on the diagonal (mathematical consistency).49- All retained mass differences fall within ±1 ppm of their assigned transformation in the reference key (error tolerance met).50- Edge table has no duplicate edges (same source–target pair listed only once per transformation type).51- Every matched transformation is present in the reference key with a biotic or abiotic label; no unclassified transformations leak through.52- 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.5354## Limitations5556- Cannot distinguish chemical isomers, as FT-ICR MS lacks chromatographic separation; mass differences alone do not disambiguate isomeric pairs.57- 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.58- Vectorized computation becomes memory-intensive for samples with very large peak counts (e.g., >10,000 peaks); consider subsampling or chunking for such cases.59- Does not account for ion suppression or enhancement effects, which can cause weak or missing peaks and thus incompletely sampled transformation networks.6061## Evidence6263- [methods] Compute all pairwise mass differences between peaks using vectorized subtraction.: "Compute all pairwise mass differences between peaks using vectorized subtraction."64- [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."65- [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"66- [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"67- [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"
HolobiomicsLab 