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"