# Feature Wise Spectrum Count Aggregation

> Use when when you have extracted concatenated MS/MS spectra for multiple features from replicate mzML files and need to verify that a TIC-based filtering step (e.g., top x% TIC extraction) reduces per-feature spectrum counts to expected target levels.

- Skill: `holobiomicslab/feature-wise-spectrum-count-aggregation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/feature-wise-spectrum-count-aggregation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/feature-wise-spectrum-count-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/feature-wise-spectrum-count-aggregation

---


# feature-wise-spectrum-count-aggregation

## Summary

Quantify and aggregate MS/MS spectrum counts per metabolomic feature before and after applying TIC-based filtering to assess the efficacy of spectral denoising. This skill validates that quality-control filters (e.g., top 80% TIC cutoff) reduce spectrum redundancy consistently across features.

## When to use

When you have extracted concatenated MS/MS spectra for multiple features from replicate mzML files and need to verify that a TIC-based filtering step (e.g., top x% TIC extraction) reduces per-feature spectrum counts to expected target levels. Typically applied after extract_raw_spectra() and before consensus spectrum generation to confirm that filtering has removed low-intensity, low-information spectra while retaining sufficient replicates for robust consensus.

## When NOT to use

- Input spectra have not been concatenated by feature — use feature-wise grouping first.
- TIC values are not available or have not been calculated for each spectrum.
- You are working with already-consensus or already-aggregated spectra (not individual replicates).

## Inputs

- Preprocessed spectra list (l1) from preprocess() — concatenated MS/MS replicates for all features
- mzML file folder path
- Feature table (Stats.txt or equivalent) with precursor m/z and retention time
- Top TIC threshold parameter (e.g., 0.8 for 80%)
- Mass tolerance parameter (Da)

## Outputs

- Spectra object (sps_top_tic_2) — filtered spectra post-TIC cutoff
- Dataframe with per-feature spectrum counts: feature ID, count before filter, count after filter
- Aggregation summary table (feature-wise spectrum count delta)

## How to apply

Load the preprocessed spectra list (l1) containing concatenated MS/MS replicates for all features using preprocess(). Call extract_raw_spectra() with parameters: folder_path, l1, mass tolerance (default 0.05 Da), and top TIC threshold (0.8 for 80%). Extract the output Spectra object (sps_top_tic_2) and accompanying dataframe showing before/after spectrum counts per feature. Aggregate and cross-tabulate the counts at the feature level, grouping by feature ID and comparing pre-filter vs. post-filter counts. The rationale is that top 80% TIC cutoff should yield consistent reduction ratios (e.g., 83→66 for feature 1982, 43→34 for feature 872) indicating that low-TIC spectra are being systematically removed without over-filtering. If observed reductions deviate significantly from expected patterns, investigate data quality or TIC threshold appropriateness.

## Related tools

- **dures** (Provides extract_raw_spectra() function to perform TIC-based filtering and return spectra and per-feature counts; preprocess() to concatenate spectra by feature.) — https://github.com/BiosystemEngineeringLab-IITB/dures
- **Spectra** (S4 container for MS/MS spectra objects; supports subsetting and metadata access for spectrum enumeration.)
- **dplyr** (Tabulate and aggregate spectrum counts by feature; group_by(feature_id) and summarise(count_before, count_after).)
- **data.table** (Efficient aggregation and cross-tabulation of large spectrum count matrices by feature.)

## Examples

```
l2 = extract_raw_spectra(folder_path = "~/metabolomics/test_1/", l1, 0.05, 0.8); df_counts <- as.data.frame(table(l2$sps_top_tic_2@metadata$feature_id)); print(df_counts)
```

## Evaluation signals

- Per-feature spectrum count reduction is monotonic (count_after ≤ count_before) for all features.
- Reduction magnitude is consistent with the TIC threshold (e.g., top 80% TIC should reduce counts by ~20% on average, though variance per feature is expected).
- Features with low initial spectrum count (e.g., <5 spectra) may reduce to 0 or very small counts; verify this is acceptable for downstream consensus generation.
- Output dataframe row count equals the number of unique features in the input l1 list.
- Spot-check 2–3 named features (e.g., feature 1982, feature 872) and verify reported reductions match expected values (83→66, 43→34) from task documentation.

## Limitations

- TIC-based filtering assumes that low-TIC spectra are predominantly noise; in complex metabolites with multiple fragmentation pathways, some genuine structural isomers may be discarded.
- The top x% threshold is global; features with naturally low TIC variance may experience minimal reduction regardless of threshold.
- Per-feature counts depend on initial m/z and retention time tolerance used in preprocess(); loose tolerances inflate counts and mask filtering efficacy.
- This skill does not validate spectral quality or signal-to-noise; it only counts. A feature may have 66 spectra post-filter but still contain noisy or redundant fragments.

## Evidence

- [methods] Top 80% TIC cutoff reduced spectra counts from 83 to 66 for feature 1982 and from 43 to 34 for feature 872.: "From 83 before to 66 spectra after after top x% TIC"
- [methods] Extract the output Spectra object and dataframe showing before/after spectra counts per feature.: "Extract the output Spectra object (sps_top_tic_2) and dataframe (df) showing before/after spectra counts per feature"
- [methods] Top x% TIC extraction involves extracting the top x% TIC spectra and grouping fragments within specified mass tolerance.: "Extract the top x% TIC spectra, and Group fragments within a specified mass tolerance"
- [readme] The extract_raw_spectra function extracts top x% TIC spectra and groups fragments within a given tolerance.: "l2 = extract_raw_spectra(folder_path = folder_path, l1_subset, 0.05, 0.8)"
- [readme] The workflow loads preprocessed spectra concatenated by feature and then applies TIC filtering.: "l1 = preprocess(folder_path = folder_path, tol_mz = 5, tol_rt = 0.1)"