Pairwise mass-difference tabulation from MSI data
Summary
Compute all possible pairwise mass differences from an MSI data matrix to identify potential molecular adducts. This is the foundational step in mass spectrometry imaging adduct detection, transforming a peak list into a complete difference matrix for downstream binning and annotation.
When to use
After loading preprocessed MSI intensity data (via msimat from CSV export) or a simple numeric vector of mass peak values, when you need to discover which masses in your dataset co-vary as parent–adduct pairs. Apply this skill before binning differences into a histogram, especially when matrix or salt ion adducts are suspected in your MALDI-MSI experiment.
When NOT to use
- Input is a single mass value or fewer than two masses—massdiff requires at least two distinct masses to compute pairs.
- You already possess a pre-computed adduct table or difference matrix from external software; re-computing will be redundant.
- Your masses are not from the same acquisition instrument or have inconsistent precision/calibration, risking spurious pairwise matches.
Inputs
- msimat object (preprocessed MSI data matrix from CSV file with peak intensities across pixels)
- numeric vector of mass values (simple list of m/z peaks, no intensity data)
Outputs
- massdiff object (data.frame with columns: parent_mass, adduct_mass, mass_difference)
- massdiff data.frame (three columns: the two parent masses and the difference between them)
How to apply
Load your MSI data into R as an msimat object (from a CSV file with specified separator, e.g., sep=';') or supply a numeric vector of mass values. Call the massdiff() function on this input; it enumerates all possible pairs of masses and computes the mass difference for each pair. The output is a data.frame-class massdiff object with three columns: parent ion A, adduct ion B, and their mass difference. These differences represent putative molecular adducts and will be binned into a histogram (typically using a bin width matching your instrument's mass precision, often ±0.01 Da) in the subsequent workflow step. The rationale is that systematic mass differences appearing many times across the peak list signal genuine adduct relationships rather than random noise.
Related tools
- mass2adduct (R package that implements massdiff() function to compute pairwise mass differences from MSI data matrices and provides downstream adduct identification pipeline) — https://github.com/kbseah/mass2adduct
- msimat (Function within mass2adduct to load and parse MSI intensity data from CSV files (exported from MSiReader or SCiLS) into R data.frame format) — https://github.com/kbseah/mass2adduct
- Cardinal (Optional R package for pre-processing MSI data; MSProcessedImagingExperiment and MSContinuousImagingExperiment objects can be converted to msimat format via cardinal2msimat())
- R (Host language and environment for executing massdiff and subsequent analytical functions)
Examples
d <- msimat("msi.csv", sep=";"); d.diff <- massdiff(d); d.diff.hist <- hist(d.diff)
Evaluation signals
- Output massdiff object has exactly three columns (parent_mass, adduct_mass, mass_difference) and number of rows equals n*(n-1)/2 where n is the number of input masses
- All values in the mass_difference column are numeric, non-negative (or follow expected mass shift direction), and within a biologically plausible range (typically ±500 Da for common adducts)
- Subsequent histogram binning (hist(d.diff)) produces a distribution with recognizable peaks at known adduct mass windows (e.g., 18.01 Da for H₂O loss, 136.02 Da for DHB-H₂O)
- topAdducts() function on the binned histogram returns matches to reference adducts (from the built-in adducts or adducts2 datasets) with non-zero occurrence counts for abundant mass differences
- corrPairsMSI() test on identified parent–adduct pairs shows statistically significant spatial correlations (p < 0.05 after Bonferroni correction) in the imaging data, validating that pairs are not spurious
Limitations
- Computational complexity scales as O(n²) with number of input masses; for very large peak lists (hundreds or thousands), memory usage and runtime become prohibitive. The package provides msimunging.pl (Perl script) to convert large CSV files to triplet format for more efficient storage and processing.
- Mass measurement error and instrumental precision are not intrinsically modeled during massdiff computation; differences must be binned post-hoc with a user-specified bin width matching the known mass accuracy of the instrument (e.g., ±0.01 Da for high-resolution MS). Choosing an inappropriate bin width will obscure or fragment genuine adduct signals.
- The function treats all mass differences equally without weighting by peak abundance or spatial coherence in the MSI dataset; spurious pairwise differences from low-intensity noise peaks will be counted alongside high-confidence adduct pairs. Filtering or weighting by intensity before massdiff() computation can mitigate this.
- No changelog or version tracking is provided in the package repository, limiting reproducibility auditing and traceability of methodological changes across versions.
Evidence
- [other] massdiff-computes-pairwise-masses: "Take all possible pairs of masses and calculate the mass difference for each pair. These mass differences represent potential molecular adducts."
- [other] massdiff-returns-dataframe: "d.diff <- massdiff(d) # Returns object of classes data.frame and massdiff"
- [other] msimat-import-csv: "d <- msimat(system.file("extdata","msi.csv",package="mass2adduct"),sep=";")"
- [intro] adducts-form-from-matrix-salt: "In mass spectrometry imaging, adducts can form between target molecules (e.g. metabolites) and other substances such as matrix or salt ions."
- [readme] massdiff-output-structure: "Output is a
massdiff object with three elements: the two parent masses and the difference between them."
- [readme] bin-width-precision-dependency: "The calculated mass differences are misleadingly precise, because measurement error and uncertainty are not taken into account. They should be binned into a histogram with a user-specified bin width,"
- [readme] large-file-handling: "Plain-text CSV files of MSI data exported by software such as SCILS or MSIreader can be large, on the order of several Gb. For many MSI data sets, a lot of this is "wasted" because the majority of"
1---2name: pairwise-mass-difference-computation3description: Use when after loading preprocessed MSI intensity data (via msimat from CSV export) or a simple numeric vector of mass peak values, when you need to discover which masses in your dataset co-vary as parent–adduct pairs.4license: CC-BY-4.05---67# Pairwise mass-difference tabulation from MSI data89## Summary1011Compute all possible pairwise mass differences from an MSI data matrix to identify potential molecular adducts. This is the foundational step in mass spectrometry imaging adduct detection, transforming a peak list into a complete difference matrix for downstream binning and annotation.1213## When to use1415After loading preprocessed MSI intensity data (via msimat from CSV export) or a simple numeric vector of mass peak values, when you need to discover which masses in your dataset co-vary as parent–adduct pairs. Apply this skill before binning differences into a histogram, especially when matrix or salt ion adducts are suspected in your MALDI-MSI experiment.1617## When NOT to use1819- Input is a single mass value or fewer than two masses—massdiff requires at least two distinct masses to compute pairs.20- You already possess a pre-computed adduct table or difference matrix from external software; re-computing will be redundant.21- Your masses are not from the same acquisition instrument or have inconsistent precision/calibration, risking spurious pairwise matches.2223## Inputs2425- msimat object (preprocessed MSI data matrix from CSV file with peak intensities across pixels)26- numeric vector of mass values (simple list of m/z peaks, no intensity data)2728## Outputs2930- massdiff object (data.frame with columns: parent_mass, adduct_mass, mass_difference)31- massdiff data.frame (three columns: the two parent masses and the difference between them)3233## How to apply3435Load your MSI data into R as an msimat object (from a CSV file with specified separator, e.g., sep=';') or supply a numeric vector of mass values. Call the massdiff() function on this input; it enumerates all possible pairs of masses and computes the mass difference for each pair. The output is a data.frame-class massdiff object with three columns: parent ion A, adduct ion B, and their mass difference. These differences represent putative molecular adducts and will be binned into a histogram (typically using a bin width matching your instrument's mass precision, often ±0.01 Da) in the subsequent workflow step. The rationale is that systematic mass differences appearing many times across the peak list signal genuine adduct relationships rather than random noise.3637## Related tools3839- **mass2adduct** (R package that implements massdiff() function to compute pairwise mass differences from MSI data matrices and provides downstream adduct identification pipeline) — https://github.com/kbseah/mass2adduct40- **msimat** (Function within mass2adduct to load and parse MSI intensity data from CSV files (exported from MSiReader or SCiLS) into R data.frame format) — https://github.com/kbseah/mass2adduct41- **Cardinal** (Optional R package for pre-processing MSI data; MSProcessedImagingExperiment and MSContinuousImagingExperiment objects can be converted to msimat format via cardinal2msimat())42- **R** (Host language and environment for executing massdiff and subsequent analytical functions)4344## Examples4546```47d <- msimat("msi.csv", sep=";"); d.diff <- massdiff(d); d.diff.hist <- hist(d.diff)48```4950## Evaluation signals5152- Output massdiff object has exactly three columns (parent_mass, adduct_mass, mass_difference) and number of rows equals n*(n-1)/2 where n is the number of input masses53- All values in the mass_difference column are numeric, non-negative (or follow expected mass shift direction), and within a biologically plausible range (typically ±500 Da for common adducts)54- Subsequent histogram binning (hist(d.diff)) produces a distribution with recognizable peaks at known adduct mass windows (e.g., 18.01 Da for H₂O loss, 136.02 Da for DHB-H₂O)55- topAdducts() function on the binned histogram returns matches to reference adducts (from the built-in adducts or adducts2 datasets) with non-zero occurrence counts for abundant mass differences56- corrPairsMSI() test on identified parent–adduct pairs shows statistically significant spatial correlations (p < 0.05 after Bonferroni correction) in the imaging data, validating that pairs are not spurious5758## Limitations5960- Computational complexity scales as O(n²) with number of input masses; for very large peak lists (hundreds or thousands), memory usage and runtime become prohibitive. The package provides msimunging.pl (Perl script) to convert large CSV files to triplet format for more efficient storage and processing.61- Mass measurement error and instrumental precision are not intrinsically modeled during massdiff computation; differences must be binned post-hoc with a user-specified bin width matching the known mass accuracy of the instrument (e.g., ±0.01 Da for high-resolution MS). Choosing an inappropriate bin width will obscure or fragment genuine adduct signals.62- The function treats all mass differences equally without weighting by peak abundance or spatial coherence in the MSI dataset; spurious pairwise differences from low-intensity noise peaks will be counted alongside high-confidence adduct pairs. Filtering or weighting by intensity before massdiff() computation can mitigate this.63- No changelog or version tracking is provided in the package repository, limiting reproducibility auditing and traceability of methodological changes across versions.6465## Evidence6667- [other] massdiff-computes-pairwise-masses: "Take all possible pairs of masses and calculate the mass difference for each pair. These mass differences represent potential molecular adducts."68- [other] massdiff-returns-dataframe: "d.diff <- massdiff(d) # Returns object of classes data.frame and massdiff"69- [other] msimat-import-csv: "d <- msimat(system.file("extdata","msi.csv",package="mass2adduct"),sep=";")"70- [intro] adducts-form-from-matrix-salt: "In mass spectrometry imaging, adducts can form between target molecules (e.g. metabolites) and other substances such as matrix or salt ions."71- [readme] massdiff-output-structure: "Output is a `massdiff` object with three elements: the two parent masses and the difference between them."72- [readme] bin-width-precision-dependency: "The calculated mass differences are misleadingly precise, because measurement error and uncertainty are not taken into account. They should be binned into a histogram with a user-specified bin width,"73- [readme] large-file-handling: "Plain-text CSV files of MSI data exported by software such as SCILS or MSIreader can be large, on the order of several Gb. For many MSI data sets, a lot of this is "wasted" because the majority of"
HolobiomicsLab 