# Ms2 Fragment M Z Grouping And Aggregation

> Use when you have extracted MS/MS spectra for a given metabolomic feature across multiple replicates (e.g., after top-TIC filtering) and need to identify which fragments are reproducible across replicates.

- Skill: `holobiomicslab/ms2-fragment-m-z-grouping-and-aggregation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ms2-fragment-m-z-grouping-and-aggregation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ms2-fragment-m-z-grouping-and-aggregation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/ms2-fragment-m-z-grouping-and-aggregation

---


# MS2 Fragment m/z Grouping and Aggregation

## Summary

This skill groups MS/MS fragments across replicate spectra by m/z tolerance, merges nearby peaks, and aggregates their intensities to generate a consensus spectrum with fragment recurrence frequencies. It is applied to denoise tandem mass spectrometry data by identifying reproducible signal fragments across replicates.

## When to use

Apply this skill when you have extracted MS/MS spectra for a given metabolomic feature across multiple replicates (e.g., after top-TIC filtering) and need to identify which fragments are reproducible across replicates. This is particularly useful after filtering to top 80% TIC spectra, where you want to merge m/z peaks within a specified tolerance (e.g., 0.05 Da) and count how often each merged fragment appears across the replicate set.

## When NOT to use

- Input spectra have not yet been filtered by quality metrics (e.g., TIC threshold); perform preprocessing and TIC filtering first.
- You need to denoise at the individual spectrum level before grouping; apply intra-spectrum fragment grouping (merge fragments within tolerance within a single spectrum) before inter-spectrum aggregation.
- Your goal is to match spectra against a reference library without consensus-building; skip aggregation and proceed directly to spectral matching.

## Inputs

- List of extracted MS/MS spectra for a single feature across replicates (Spectra S4 object, filtered by top x% TIC)
- m/z mass tolerance threshold (Da; default 0.05)
- Folder path containing mzML files and feature information

## Outputs

- Consensus spectrum dataframe with grouped fragments (mean m/z, mean intensity, recurrence frequency)
- Fragment count for the consensus spectrum (e.g., 498 fragments for feature 1982)
- Recurrence frequency matrix for labeling individual spectra

## How to apply

First, extract the top-TIC-filtered replicate spectra for a feature (e.g., 66 spectra after 80% TIC filtering from an original 83) using extract_raw_spectra with a specified m/z tolerance (default 0.05 Da). Then apply call_aggregate to perform inter-spectrum fragment grouping: fragments within the tolerance window are merged, their m/z values are averaged, and their intensities are summed. The function simultaneously calculates the recurrence frequency—how many replicate spectra contributed a fragment to each merged m/z bin. This produces a consensus spectrum dataframe with mean m/z, mean intensity, and recurrence frequency for each grouped fragment. The m/z tolerance (typically 0.05 Da) is the critical parameter; choose it based on your instrument's mass accuracy.

## Related tools

- **Spectra** (S4 object class for storing and manipulating MS/MS spectral data; required to represent grouped spectra before aggregation) — https://bioconductor.org/packages/Spectra
- **call_aggregate** (Function that performs inter-spectrum fragment grouping and aggregation; merges fragments within m/z tolerance and calculates recurrence frequencies) — https://github.com/BiosystemEngineeringLab-IITB/dures
- **extract_raw_spectra** (Function that extracts and prepares top-TIC-filtered spectra as input for aggregation; performs initial intra-spectrum grouping within specified m/z tolerance) — https://github.com/BiosystemEngineeringLab-IITB/dures
- **dplyr** (Data manipulation and summarization of consensus spectrum dataframes (mean m/z, intensity aggregation, frequency counts)) — https://cran.r-project.org/package=dplyr
- **S4Vectors** (Provides S4 object infrastructure for handling spectral data structures and recurrence frequency matrices) — https://bioconductor.org/packages/S4Vectors

## Examples

```
l3 = call_aggregate(l2$sps_top_tic_2, 0.05, folder_path)
```

## Evaluation signals

- Fragment count in output consensus spectrum matches expected value (e.g., 498 for feature 1982; verify by row count of consensus dataframe)
- Recurrence frequencies are non-negative integers ≤ total number of replicate spectra and reflect observed fragment occurrence patterns
- Mean m/z values in consensus spectrum fall within the original m/z range and merged peaks respect the specified tolerance window (e.g., 0.05 Da)
- Intensity summation is correct: summed intensities of merged fragments are consistent with input spectra; no negative or NaN values appear
- Consensus spectrum contains no duplicate m/z values within the tolerance threshold

## Limitations

- The choice of m/z tolerance (default 0.05 Da) directly affects fragment grouping resolution; narrower tolerances yield more fragments, wider tolerances risk losing spectral detail. Instrument mass accuracy must be known a priori.
- Aggregation assumes replicate spectra represent the same metabolite feature; misalignment in RT or m/z during feature extraction will degrade consensus quality.
- Fragments present in only one or few replicates will have low recurrence frequencies and may be filtered out in downstream denoising steps; this can lose genuine low-abundance signal if replicates are noisy or few in number.
- No in-built handling of isotope patterns or neutral loss series; fragments related by mass difference must be grouped manually if needed for specialized applications.

## Evidence

- [methods] Extract top x% TIC spectra, and Group fragments within a specified mass tolerance: "Extract the top x% TIC spectra, and Group fragments within a specified mass tolerance"
- [methods] call_aggregate to group fragments across all 66 top-TIC spectra with mass tolerance 0.05 Da to merge nearby m/z values and sum intensities: "Generate consensus spectrum by applying call_aggregate to group fragments across all 66 top-TIC spectra with mass tolerance 0.05 Da to merge nearby m/z values and sum intensities."
- [methods] Extract consensus spectrum dataframe containing mean m/z, mean intensity, and fragment recurrence frequencies: "Extract consensus spectrum dataframe containing mean m/z, mean intensity, and fragment recurrence frequencies for each of the 498 fragments."
- [methods] fragments in the reference spectra that fall within the specified m/z tolerance (tol) are grouped together: "Inter-spectrum fragment grouping: fragments in the reference spectra that fall within the specified m/z tolerance (tol) are grouped together"
- [readme] l2 = extract_raw_spectra(folder_path = folder_path, l1, 0.05, 0.8); l3 = call_aggregate(l2$sps_top_tic_2, 0.05, folder_path): "l2 = extract_raw_spectra(folder_path = folder_path, l1, 0.05, 0.8) #extract top x% (where x = 0.8) TIC spectra, groups fragments within a given tolerance (0.05 Da); l3 ="