Rank Mass Differences by Occurrence with topAdducts
Summary
This skill ranks mass differences observed in MALDI-MS imaging data by their occurrence frequency and cross-references them against known chemical adducts. It surfaces the most abundant molecular adducts—which represent potential metabolite–matrix or metabolite–salt ion associations—from a binned mass difference histogram.
When to use
Apply this skill after you have computed a histogram of pairwise mass differences from MSI peak data and want to identify which mass shifts occur most frequently and whether they correspond to known chemical adducts. This is the appropriate step when your analysis goal is to prioritize candidate adducts for downstream validation (e.g., spatial correlation testing) rather than exhaustively matching all peaks to a reference database.
When NOT to use
- The input mass difference histogram has not been binned with an appropriate bin width for your instrument's mass accuracy; topAdducts will rank noisy or spurious differences.
- You only care about known adducts and do not need discovery of novel mass shifts; use
adductMatch() instead for faster, reference-only matching.
- Your raw MSI data has not yet been pre-processed (peak-binned, baseline-corrected, normalized); topAdducts expects a validated histogram as input.
Inputs
- massdiffhist object (output from hist() applied to a massdiff data frame)
Outputs
- data.frame with columns: mass difference value, occurrence count, quantile rank, matched adduct name (or NA if no match)
How to apply
Load a preprocessed mass difference histogram object (created by applying hist() to a massdiff object) into R. Call the topAdducts() function with the histogram and specify the number of top-ranked hits to return (e.g., n=10). The function internally ranks all observed mass differences by their occurrence counts in descending order, then cross-references each value against the built-in adducts (or user-supplied) reference table using a closest-match lookup (within histogram bin width). The output is a ranked data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names or chemical formulas when a reference hit is found. The ranking by occurrence is the primary sorting criterion, making high-abundance mass shifts discoverable regardless of whether they match known adducts—a key advantage over adductMatch(), which only reports hits with known references.
Related tools
- mass2adduct (R package providing the topAdducts function and supporting massdiff and hist methods for generating ranked adduct occurrence tables) — https://github.com/kbseah/mass2adduct
- R (Statistical computing environment in which mass2adduct functions are executed and histogram objects are manipulated)
Examples
topAdducts(d.diff.hist, n=10)
Evaluation signals
- Output data frame contains n rows (matching the requested parameter) ranked by occurrence count in descending order, with no duplicate mass difference values.
- Quantile values increase monotonically from top to bottom (highest occurrence → lowest quantile; lowest occurrence → high quantile).
- All mass differences in the output fall within the range and bin-width resolution of the input histogram object.
- Adduct name matches (non-NA rows) correspond to mass differences within the closest-match tolerance of known adduct masses in the reference table; verify by manual spot-check against
adducts or adducts2 data set.
- When compared to full histogram, top-ranked entries account for a visually obvious peak or shoulder in the histogram plot.
Limitations
- topAdducts relies on accurate binning during histogram creation; if bin width is too coarse, genuine adducts may merge; if too fine, random noise will appear as rare mass shifts.
- The function performs closest-match lookup against the reference adduct table, so unknown or non-standard adducts will not be annotated even if they rank highly by occurrence.
- Output quantile values are typically very high (close to 1) because most mass differences have zero or few counts; quantile alone is not a strong statistical signal of biological relevance.
- For very large MSI datasets (hundreds or thousands of peaks), memory constraints may prevent computation of the full pairwise mass difference matrix; users must use the Perl script
msimunging.pl or chunked processing elsewhere before reaching topAdducts.
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, and reports them in descending order, as well as matches to known adducts, if any"
- [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: "Apply topAdducts function to the histogram object, specifying the number of top hits to return (e.g., n=10). The function ranks all mass differences by their occurrence counts in descending order and"
- [other] Output is a ranked table as a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names: "Output the ranked table as a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names (if applicable)"
- [readme] topAdducts performs the complementary function to adductMatch by ranking mass differences by occurrence and reporting 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."
- [readme] The package includes two built-in datasets of biologically-relevant chemical species for adduct reference matching: "The package comes with a small data set of common molecular adducts, called
adducts (use the command help(adducts) to see a description). Users can supply their own custom sets of adducts"
1---2name: histogram-peak-occurrence-analysis-23description: Use when after you have computed a histogram of pairwise mass differences from MSI peak data and want to identify which mass shifts occur most frequently and whether they correspond to known chemical adducts.4license: CC-BY-4.05---67# Rank Mass Differences by Occurrence with topAdducts89## Summary1011This skill ranks mass differences observed in MALDI-MS imaging data by their occurrence frequency and cross-references them against known chemical adducts. It surfaces the most abundant molecular adducts—which represent potential metabolite–matrix or metabolite–salt ion associations—from a binned mass difference histogram.1213## When to use1415Apply this skill after you have computed a histogram of pairwise mass differences from MSI peak data and want to identify which mass shifts occur most frequently and whether they correspond to known chemical adducts. This is the appropriate step when your analysis goal is to prioritize candidate adducts for downstream validation (e.g., spatial correlation testing) rather than exhaustively matching all peaks to a reference database.1617## When NOT to use1819- The input mass difference histogram has not been binned with an appropriate bin width for your instrument's mass accuracy; topAdducts will rank noisy or spurious differences.20- You only care about known adducts and do not need discovery of novel mass shifts; use `adductMatch()` instead for faster, reference-only matching.21- Your raw MSI data has not yet been pre-processed (peak-binned, baseline-corrected, normalized); topAdducts expects a validated histogram as input.2223## Inputs2425- massdiffhist object (output from hist() applied to a massdiff data frame)2627## Outputs2829- data.frame with columns: mass difference value, occurrence count, quantile rank, matched adduct name (or NA if no match)3031## How to apply3233Load a preprocessed mass difference histogram object (created by applying `hist()` to a `massdiff` object) into R. Call the `topAdducts()` function with the histogram and specify the number of top-ranked hits to return (e.g., `n=10`). The function internally ranks all observed mass differences by their occurrence counts in descending order, then cross-references each value against the built-in `adducts` (or user-supplied) reference table using a closest-match lookup (within histogram bin width). The output is a ranked data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names or chemical formulas when a reference hit is found. The ranking by occurrence is the primary sorting criterion, making high-abundance mass shifts discoverable regardless of whether they match known adducts—a key advantage over `adductMatch()`, which only reports hits with known references.3435## Related tools3637- **mass2adduct** (R package providing the topAdducts function and supporting massdiff and hist methods for generating ranked adduct occurrence tables) — https://github.com/kbseah/mass2adduct38- **R** (Statistical computing environment in which mass2adduct functions are executed and histogram objects are manipulated)3940## Examples4142```43topAdducts(d.diff.hist, n=10)44```4546## Evaluation signals4748- Output data frame contains n rows (matching the requested parameter) ranked by occurrence count in descending order, with no duplicate mass difference values.49- Quantile values increase monotonically from top to bottom (highest occurrence → lowest quantile; lowest occurrence → high quantile).50- All mass differences in the output fall within the range and bin-width resolution of the input histogram object.51- Adduct name matches (non-NA rows) correspond to mass differences within the closest-match tolerance of known adduct masses in the reference table; verify by manual spot-check against `adducts` or `adducts2` data set.52- When compared to full histogram, top-ranked entries account for a visually obvious peak or shoulder in the histogram plot.5354## Limitations5556- topAdducts relies on accurate binning during histogram creation; if bin width is too coarse, genuine adducts may merge; if too fine, random noise will appear as rare mass shifts.57- The function performs closest-match lookup against the reference adduct table, so unknown or non-standard adducts will not be annotated even if they rank highly by occurrence.58- Output quantile values are typically very high (close to 1) because most mass differences have zero or few counts; quantile alone is not a strong statistical signal of biological relevance.59- For very large MSI datasets (hundreds or thousands of peaks), memory constraints may prevent computation of the full pairwise mass difference matrix; users must use the Perl script `msimunging.pl` or chunked processing elsewhere before reaching topAdducts.6061## Evidence6263- [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, and reports them in descending order, as well as matches to known adducts, if any"64- [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: "Apply topAdducts function to the histogram object, specifying the number of top hits to return (e.g., n=10). The function ranks all mass differences by their occurrence counts in descending order and"65- [other] Output is a ranked table as a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names: "Output the ranked table as a data frame containing mass difference values, occurrence counts, quantile ranks, and matched adduct names (if applicable)"66- [readme] topAdducts performs the complementary function to adductMatch by ranking mass differences by occurrence and reporting 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."67- [readme] The package includes two built-in datasets of biologically-relevant chemical species for adduct reference matching: "The package comes with a small data set of common molecular adducts, called `adducts` (use the command `help(adducts)` to see a description). Users can supply their own custom sets of adducts"
HolobiomicsLab 