Mass-Spectrum Histogram Interpretation
Summary
Bin calculated mass differences into a histogram with instrument-appropriate precision, then visually and statistically identify peaks representing abundant molecular adducts. This technique transforms raw pairwise mass differences into actionable annotations by matching histogram bins to known chemical transformations.
When to use
After computing all pairwise mass differences from a mass spectrometry imaging dataset, when you need to identify which mass differences correspond to real molecular adducts (e.g., metabolite–matrix or metabolite–salt ions) rather than noise. Use this skill when the number of unique mass difference values is large and measurement uncertainty makes individual differences unreliable for matching to known adducts.
When NOT to use
- Do not use if you have only a few peaks or very low mass resolution; histogram binning requires sufficient pairwise differences to form meaningful peaks.
- Do not use if your mass differences are already annotated or if you only need to identify a single known adduct; use diffGetPeaks() directly instead.
- Do not use if measurement error is unknown or unmeasurable; you cannot set an appropriate bin width without understanding instrument precision.
Inputs
- massdiff object (data.frame with three columns: parent ion mass A, adduct ion mass B, mass difference diff)
- bin width parameter (numeric, instrument-dependent; e.g., 0.01 for typical MALDI instruments)
- reference adduct dataset (data.frame with columns name, formula, mass; built-in adducts or adducts2, or user-supplied)
Outputs
- massdiffhist object (standard R histogram object with counts per bin)
- adductMatch result (data.frame with matched adduct names, formulas, masses, counts, and quantile values)
- topAdducts ranking (data.frame with top n mass differences ranked by count, with adduct matches if available)
- histogram plot (visual representation of mass difference distribution)
How to apply
First, create a histogram of all pairwise mass differences using a bin width that reflects your instrument's known mass precision (e.g., 0.01 for high-resolution instruments; the README recommends this as a starting point). The histogram bundles measured differences that fall within measurement error, normalizing away misleading false precision. Next, apply adductMatch() to the histogram to count occurrences of bins matching known adducts from the built-in adducts or adducts2 reference datasets, reporting both raw counts and quantile values to gauge abundance. Then use topAdducts() to rank all histogram bins by occurrence frequency in descending order and identify matches to known adducts in the highest-abundance bins. Use the visual histogram plot to spot unexpected peaks or bimodal distributions that might indicate instrument calibration issues or unsuspected chemical transformations. Finally, evaluate whether the top-ranked mass differences make biological sense given your sample composition (e.g., common matrices like DHB should produce expected adducts).
Related tools
- mass2adduct (Provides hist() method for massdiff objects, adductMatch() for bin-to-adduct matching, and topAdducts() for ranking; also supplies built-in adducts and adducts2 reference datasets.) — https://github.com/kbseah/mass2adduct
- R (Host language; hist() is base R function, used alongside mass2adduct package functions.)
- SCiLS or MSiReader (Upstream MSI data export software; data must be exported as CSV before import to mass2adduct.)
- Cardinal (Alternative upstream MSI processing software; MSProcessedImagingExperiment or MSContinuousImagingExperiment objects can be converted to msimat format for mass2adduct.) — http://cardinalmsi.org/
Examples
d.diff.hist <- hist(d.diff); adductMatch(d.diff.hist); topAdducts(d.diff.hist, n=10)
Evaluation signals
- Histogram shows distinct, narrow peaks (not broad or flat distribution), indicating genuine mass differences stand out from noise.
- Top-ranked mass differences match known adducts (e.g., DHB-H2O at 136.01600, or common salt/matrix ions) in the reference dataset with high counts and low quantile values.
- Visual inspection of histogram reveals expected peaks for your known sample composition (e.g., if DHB matrix is used, should see DHB-related peaks).
- Quantile values for matched adducts are substantially lower than those of unmatched bins, confirming adduct matches are enriched in the tail of the distribution.
- topAdducts() output shows graceful decrease in counts with rank; absence of a few dominant peaks followed by many singletons suggests good separation of true adducts from noise.
Limitations
- Bin width choice directly affects sensitivity and specificity; too narrow and bins fragment into noise, too wide and distinct adducts merge. The README recommends 0.01 as a starting point but does not provide data-driven guidance for all instruments.
- Reference adduct datasets (adducts, adducts2) are curated for biological relevance but may omit instrument-specific or non-biological adducts; custom adduct lists can be supplied but require manual curation.
- Histogram peak height alone does not prove adducts are real or spatially correlated; follow-up with corrPairsMSI() or corrPairsMSIchunks() to test spatial co-localization of parent and adduct ions in MSI pixels.
- Large datasets (hundreds or thousands of peaks) may cause memory issues during pairwise difference calculation; reformatting to triplet format with msimunging.pl Perl script is recommended but adds a preprocessing step.
- Quantile values are typically very high because most mass differences have zero counts; the quantile alone is not a reliable measure of adduct significance without comparison to the full distribution.
Evidence
- [readme] 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, that depends on the known mass precision of your instrument.: "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] The following function looks for known adducts by finding the closest-matching bin in the mass difference histogram produced above. It reports the number of counts (i.e. how many pairs of MS peaks have that mass difference) and the quantile.: "The following function looks for known adducts by finding the closest-matching bin in the mass difference histogram produced above. It reports the number of counts (i.e. how many pairs of MS peaks"
- [readme]
topAdducts ranks mass differences by the number of times they are observed, and report any matches to known adducts: "topAdducts ranks mass differences by the number of times they are observed, and report any matches to known adducts"
- [other] Create a mass difference histogram using hist() on the massdiff object to identify peaks representing common chemical transformations.: "Create a mass difference histogram using hist() on the massdiff object to identify peaks representing common chemical transformations."
- [intro] In mass spectrometry imaging, adducts can form between target molecules (e.g. metabolites) and other substances such as matrix or salt ions.: "In mass spectrometry imaging, adducts can form between target molecules (e.g. metabolites) and other substances such as matrix or salt ions."
1---2name: mass-spectrum-histogram-interpretation-23description: Use when after computing all pairwise mass differences from a mass spectrometry imaging dataset, when you need to identify which mass differences correspond to real molecular adducts (e.g., metabolite–matrix or metabolite–salt ions) rather than noise.4license: CC-BY-4.05---67# Mass-Spectrum Histogram Interpretation89## Summary1011Bin calculated mass differences into a histogram with instrument-appropriate precision, then visually and statistically identify peaks representing abundant molecular adducts. This technique transforms raw pairwise mass differences into actionable annotations by matching histogram bins to known chemical transformations.1213## When to use1415After computing all pairwise mass differences from a mass spectrometry imaging dataset, when you need to identify which mass differences correspond to real molecular adducts (e.g., metabolite–matrix or metabolite–salt ions) rather than noise. Use this skill when the number of unique mass difference values is large and measurement uncertainty makes individual differences unreliable for matching to known adducts.1617## When NOT to use1819- Do not use if you have only a few peaks or very low mass resolution; histogram binning requires sufficient pairwise differences to form meaningful peaks.20- Do not use if your mass differences are already annotated or if you only need to identify a single known adduct; use diffGetPeaks() directly instead.21- Do not use if measurement error is unknown or unmeasurable; you cannot set an appropriate bin width without understanding instrument precision.2223## Inputs2425- massdiff object (data.frame with three columns: parent ion mass A, adduct ion mass B, mass difference diff)26- bin width parameter (numeric, instrument-dependent; e.g., 0.01 for typical MALDI instruments)27- reference adduct dataset (data.frame with columns name, formula, mass; built-in adducts or adducts2, or user-supplied)2829## Outputs3031- massdiffhist object (standard R histogram object with counts per bin)32- adductMatch result (data.frame with matched adduct names, formulas, masses, counts, and quantile values)33- topAdducts ranking (data.frame with top n mass differences ranked by count, with adduct matches if available)34- histogram plot (visual representation of mass difference distribution)3536## How to apply3738First, create a histogram of all pairwise mass differences using a bin width that reflects your instrument's known mass precision (e.g., 0.01 for high-resolution instruments; the README recommends this as a starting point). The histogram bundles measured differences that fall within measurement error, normalizing away misleading false precision. Next, apply adductMatch() to the histogram to count occurrences of bins matching known adducts from the built-in adducts or adducts2 reference datasets, reporting both raw counts and quantile values to gauge abundance. Then use topAdducts() to rank all histogram bins by occurrence frequency in descending order and identify matches to known adducts in the highest-abundance bins. Use the visual histogram plot to spot unexpected peaks or bimodal distributions that might indicate instrument calibration issues or unsuspected chemical transformations. Finally, evaluate whether the top-ranked mass differences make biological sense given your sample composition (e.g., common matrices like DHB should produce expected adducts).3940## Related tools4142- **mass2adduct** (Provides hist() method for massdiff objects, adductMatch() for bin-to-adduct matching, and topAdducts() for ranking; also supplies built-in adducts and adducts2 reference datasets.) — https://github.com/kbseah/mass2adduct43- **R** (Host language; hist() is base R function, used alongside mass2adduct package functions.)44- **SCiLS or MSiReader** (Upstream MSI data export software; data must be exported as CSV before import to mass2adduct.)45- **Cardinal** (Alternative upstream MSI processing software; MSProcessedImagingExperiment or MSContinuousImagingExperiment objects can be converted to msimat format for mass2adduct.) — http://cardinalmsi.org/4647## Examples4849```50d.diff.hist <- hist(d.diff); adductMatch(d.diff.hist); topAdducts(d.diff.hist, n=10)51```5253## Evaluation signals5455- Histogram shows distinct, narrow peaks (not broad or flat distribution), indicating genuine mass differences stand out from noise.56- Top-ranked mass differences match known adducts (e.g., DHB-H2O at 136.01600, or common salt/matrix ions) in the reference dataset with high counts and low quantile values.57- Visual inspection of histogram reveals expected peaks for your known sample composition (e.g., if DHB matrix is used, should see DHB-related peaks).58- Quantile values for matched adducts are substantially lower than those of unmatched bins, confirming adduct matches are enriched in the tail of the distribution.59- topAdducts() output shows graceful decrease in counts with rank; absence of a few dominant peaks followed by many singletons suggests good separation of true adducts from noise.6061## Limitations6263- Bin width choice directly affects sensitivity and specificity; too narrow and bins fragment into noise, too wide and distinct adducts merge. The README recommends 0.01 as a starting point but does not provide data-driven guidance for all instruments.64- Reference adduct datasets (adducts, adducts2) are curated for biological relevance but may omit instrument-specific or non-biological adducts; custom adduct lists can be supplied but require manual curation.65- Histogram peak height alone does not prove adducts are real or spatially correlated; follow-up with corrPairsMSI() or corrPairsMSIchunks() to test spatial co-localization of parent and adduct ions in MSI pixels.66- Large datasets (hundreds or thousands of peaks) may cause memory issues during pairwise difference calculation; reformatting to triplet format with msimunging.pl Perl script is recommended but adds a preprocessing step.67- Quantile values are typically very high because most mass differences have zero counts; the quantile alone is not a reliable measure of adduct significance without comparison to the full distribution.6869## Evidence7071- [readme] 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, that depends on the known mass precision of your instrument.: "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,"72- [readme] The following function looks for known adducts by finding the closest-matching bin in the mass difference histogram produced above. It reports the number of counts (i.e. how many pairs of MS peaks have that mass difference) and the quantile.: "The following function looks for known adducts by finding the closest-matching bin in the mass difference histogram produced above. It reports the number of counts (i.e. how many pairs of MS peaks"73- [readme] `topAdducts` ranks mass differences by the number of times they are observed, and report any matches to known adducts: "`topAdducts` ranks mass differences by the number of times they are observed, and report any matches to known adducts"74- [other] Create a mass difference histogram using hist() on the massdiff object to identify peaks representing common chemical transformations.: "Create a mass difference histogram using hist() on the massdiff object to identify peaks representing common chemical transformations."75- [intro] In mass spectrometry imaging, adducts can form between target molecules (e.g. metabolites) and other substances such as matrix or salt ions.: "In mass spectrometry imaging, adducts can form between target molecules (e.g. metabolites) and other substances such as matrix or salt ions."
HolobiomicsLab