adduct-mass-difference-ranking
Summary
Rank observed mass differences by their occurrence frequency in MALDI-MS imaging data and annotate matches to known adduct species. This skill identifies abundant adduct signals that would otherwise be obscured in the metabolome by systematically counting pairwise mass differences and cross-referencing them against reference adduct tables.
When to use
Apply this skill when you have computed a histogram of mass differences from all pairwise mass comparisons in your MALDI-MS imaging dataset and need to prioritize which mass differences are most frequent and likely represent genuine molecular adducts (e.g., metabolite + matrix ions) rather than noise. Use it after binning mass differences into a histogram with instrument-appropriate bin width (e.g., 0.01 Da for high-resolution MS) and before testing spatial correlations between parent and adduct ions.
When NOT to use
- Input is raw, unbinned pairwise mass differences without histogram binning — use hist() first to account for measurement error and uncertainty.
- You already have a curated list of target adducts and only need to filter for those specific masses — use adductMatch() instead to find only known adducts.
- Mass precision is extremely high (sub-ppm, e.g., Orbitrap) but your histogram bin width is too coarse — topAdducts will merge distinct true adducts; adjust bin width before ranking.
Inputs
- massdiffhist object (output from hist() applied to a massdiff data frame)
- reference adduct table (data.frame with columns: name, formula, mass; e.g., built-in 'adducts' or 'adducts2' datasets)
Outputs
- ranked data.frame containing: mass difference values, occurrence counts, quantile ranks, matched adduct names (if any matches found)
How to apply
Load a massdiff histogram object (produced by applying hist() to the output of massdiff() on an msimat object) into R. Apply the topAdducts function, specifying the number of top hits to return (e.g., n=10 for the ten most frequent mass differences). The function ranks all mass differences in descending order by their occurrence counts (bin heights in the histogram) and cross-references each observed mass difference against a reference adduct table (using the built-in 'adducts' or 'adducts2' datasets, or a user-supplied table in data.frame format with columns: name, formula, mass). The function reports the ranked mass differences with their occurrence counts, quantile ranks, and any matched adduct names. Output is a data.frame suitable for filtering, visualization, or downstream correlation testing to confirm spatial colocalization of parent and adduct ions.
Related tools
- mass2adduct (R package providing topAdducts function and supporting functions (massdiff, hist, adductMatch) for ranking and annotating mass differences in MALDI-MS imaging data) — https://github.com/kbseah/mass2adduct
- R (Computing environment for loading massdiffhist objects and invoking topAdducts)
Examples
topAdducts(d.diff.hist, n=10)
Evaluation signals
- Output data.frame has exactly 4+ columns (mass_difference, count, quantile, adduct_match) and row count ≤ n parameter supplied to topAdducts.
- Occurrence counts are in strictly descending order (rank invariant: count[i] ≥ count[i+1]).
- All matched adduct names correspond to entries in the reference table used; unmatched rows have NA or empty string in adduct_match column.
- Quantile values are between 0 and 1, and generally high (>0.5–1.0) because most mass differences have zero to few counts (as noted in README).
- Rank matches visual peaks in the histogram plot — top 1–5 rows should correspond to visually prominent histogram bins.
Limitations
- topAdducts only ranks observed mass differences; it does not distinguish true adducts from random peaks without spatial correlation testing (use corrPairsMSI afterward).
- Matching relies on finding closest-matching bin in reference table — if bin width is too coarse, true adducts may be missed; if too fine, bins may not accumulate enough counts to rank high.
- Output quantile values are often unintuitive (close to 1.0) because the majority of mass differences have zero counts; quantile interpretation requires context from the full histogram.
- Built-in 'adducts' and 'adducts2' reference tables are limited to biologically-relevant species; users must supply custom adduct tables for non-standard ionization modes or matrix types.
- For very large datasets (hundreds or thousands of peaks), the function may consume substantial memory during histogram binning; no memory-chunking option is provided for topAdducts itself (chunking available only for corrPairsMSI).
Evidence
- [other] topAdducts ranks mass differences by their occurrences in descending order and reports matches to known adducts if any are found.: "topAdducts ranks mass differences by their occurrences in descending order and reports matches to known adducts if any are found."
- [other] The function ranks all mass differences by their occurrence counts in descending order and cross-references each against the built-in adducts or user-supplied adduct reference table.: "The function ranks all mass differences by their occurrence counts in descending order and cross-references each against the built-in adducts or user-supplied adduct reference table (if available) to"
- [readme] The procedure above (adductMatch) only looks for known adducts. What about peaks in the histogram which may not have a good match with the reference list? The function topAdducts performs the complementary function: Rank mass differences by the number of times they are observed, and report any matches to known adducts.: "The function topAdducts performs the complementary function: Rank mass differences by the number of times they are observed, and report any matches to known adducts."
- [other] Output is a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names (if applicable).: "Output the ranked table as a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names (if applicable)."
- [readme] Note that quantile values will usually be quite high because the majority of mass differences have zero to few counts.: "Note that quantile values will usually be quite high because the majority of mass differences have zero to few counts."
1---2name: adduct-mass-difference-ranking3description: Use when you have computed a histogram of mass differences from all pairwise mass comparisons in your MALDI-MS imaging dataset and need to prioritize which mass differences are most frequent and likely represent genuine molecular adducts (e.g., metabolite + matrix ions) rather than noise.4license: CC-BY-4.05---67# adduct-mass-difference-ranking89## Summary1011Rank observed mass differences by their occurrence frequency in MALDI-MS imaging data and annotate matches to known adduct species. This skill identifies abundant adduct signals that would otherwise be obscured in the metabolome by systematically counting pairwise mass differences and cross-referencing them against reference adduct tables.1213## When to use1415Apply this skill when you have computed a histogram of mass differences from all pairwise mass comparisons in your MALDI-MS imaging dataset and need to prioritize which mass differences are most frequent and likely represent genuine molecular adducts (e.g., metabolite + matrix ions) rather than noise. Use it after binning mass differences into a histogram with instrument-appropriate bin width (e.g., 0.01 Da for high-resolution MS) and before testing spatial correlations between parent and adduct ions.1617## When NOT to use1819- Input is raw, unbinned pairwise mass differences without histogram binning — use hist() first to account for measurement error and uncertainty.20- You already have a curated list of target adducts and only need to filter for those specific masses — use adductMatch() instead to find only known adducts.21- Mass precision is extremely high (sub-ppm, e.g., Orbitrap) but your histogram bin width is too coarse — topAdducts will merge distinct true adducts; adjust bin width before ranking.2223## Inputs2425- massdiffhist object (output from hist() applied to a massdiff data frame)26- reference adduct table (data.frame with columns: name, formula, mass; e.g., built-in 'adducts' or 'adducts2' datasets)2728## Outputs2930- ranked data.frame containing: mass difference values, occurrence counts, quantile ranks, matched adduct names (if any matches found)3132## How to apply3334Load a massdiff histogram object (produced by applying hist() to the output of massdiff() on an msimat object) into R. Apply the topAdducts function, specifying the number of top hits to return (e.g., n=10 for the ten most frequent mass differences). The function ranks all mass differences in descending order by their occurrence counts (bin heights in the histogram) and cross-references each observed mass difference against a reference adduct table (using the built-in 'adducts' or 'adducts2' datasets, or a user-supplied table in data.frame format with columns: name, formula, mass). The function reports the ranked mass differences with their occurrence counts, quantile ranks, and any matched adduct names. Output is a data.frame suitable for filtering, visualization, or downstream correlation testing to confirm spatial colocalization of parent and adduct ions.3536## Related tools3738- **mass2adduct** (R package providing topAdducts function and supporting functions (massdiff, hist, adductMatch) for ranking and annotating mass differences in MALDI-MS imaging data) — https://github.com/kbseah/mass2adduct39- **R** (Computing environment for loading massdiffhist objects and invoking topAdducts)4041## Examples4243```44topAdducts(d.diff.hist, n=10)45```4647## Evaluation signals4849- Output data.frame has exactly 4+ columns (mass_difference, count, quantile, adduct_match) and row count ≤ n parameter supplied to topAdducts.50- Occurrence counts are in strictly descending order (rank invariant: count[i] ≥ count[i+1]).51- All matched adduct names correspond to entries in the reference table used; unmatched rows have NA or empty string in adduct_match column.52- Quantile values are between 0 and 1, and generally high (>0.5–1.0) because most mass differences have zero to few counts (as noted in README).53- Rank matches visual peaks in the histogram plot — top 1–5 rows should correspond to visually prominent histogram bins.5455## Limitations5657- topAdducts only ranks observed mass differences; it does not distinguish true adducts from random peaks without spatial correlation testing (use corrPairsMSI afterward).58- Matching relies on finding closest-matching bin in reference table — if bin width is too coarse, true adducts may be missed; if too fine, bins may not accumulate enough counts to rank high.59- Output quantile values are often unintuitive (close to 1.0) because the majority of mass differences have zero counts; quantile interpretation requires context from the full histogram.60- Built-in 'adducts' and 'adducts2' reference tables are limited to biologically-relevant species; users must supply custom adduct tables for non-standard ionization modes or matrix types.61- For very large datasets (hundreds or thousands of peaks), the function may consume substantial memory during histogram binning; no memory-chunking option is provided for topAdducts itself (chunking available only for corrPairsMSI).6263## Evidence6465- [other] topAdducts ranks mass differences by their occurrences in descending order and reports matches to known adducts if any are found.: "topAdducts ranks mass differences by their occurrences in descending order and reports matches to known adducts if any are found."66- [other] The function ranks all mass differences by their occurrence counts in descending order and cross-references each against the built-in adducts or user-supplied adduct reference table.: "The function ranks all mass differences by their occurrence counts in descending order and cross-references each against the built-in adducts or user-supplied adduct reference table (if available) to"67- [readme] The procedure above (adductMatch) only looks for known adducts. What about peaks in the histogram which may not have a good match with the reference list? The function topAdducts performs the complementary function: Rank mass differences by the number of times they are observed, and report any matches to known adducts.: "The function topAdducts performs the complementary function: Rank mass differences by the number of times they are observed, and report any matches to known adducts."68- [other] Output is a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names (if applicable).: "Output the ranked table as a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names (if applicable)."69- [readme] Note that quantile values will usually be quite high because the majority of mass differences have zero to few counts.: "Note that quantile values will usually be quite high because the majority of mass differences have zero to few counts."
HolobiomicsLab 