# Retention Time Correlation Filtering

> Use when you have detected multiple LC-MS features (m/z peaks) across a chromatogram and need to distinguish true chemical relationships (isotopes differing by 1.003 Da, adducts with characteristic mass shifts, neutral loss fragments) from noise or unrelated peaks.

- Skill: `holobiomicslab/retention-time-correlation-filtering-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/retention-time-correlation-filtering-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/retention-time-correlation-filtering-2/raw
- Safety review: pending
- 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/retention-time-correlation-filtering-2

---


# retention-time-correlation-filtering

> **License: noncommercial** — confirm your use is a permitted (noncommercial) purpose before applying; commercial use requires a separate license (see `metadata.tool_license`). <!-- asb-license-banner -->
## Summary

Filter and group LC-MS features by retention time proximity to identify related ion species (isotopes, adducts, in-source fragments). This skill removes spurious or unrelated features and clusters true feature families for confident annotation.

## When to use

Apply this skill when you have detected multiple LC-MS features (m/z peaks) across a chromatogram and need to distinguish true chemical relationships (isotopes differing by 1.003 Da, adducts with characteristic mass shifts, neutral loss fragments) from noise or unrelated peaks. Use it as a prerequisite step before assigning feature group annotations, especially when peak detection may have introduced redundant or artifactual signals.

## When NOT to use

- Input is already a feature table with pre-assigned group IDs and validated annotations — skip to MS/MS annotation.
- Retention time information is missing or unreliable (e.g., retention time noise exceeds the expected mass shift tolerance).
- Data is from targeted MS or single-reaction monitoring (SRM) where only a few known m/z values are monitored — feature grouping is unnecessary.

## Inputs

- Feature table (CSV, TSV, or in-memory table with columns: m/z, retention time (seconds), intensity, feature ID)
- Retention time tolerance window (numeric, in seconds)
- Expected mass shift dictionary (isotope offset, adduct masses, neutral losses)

## Outputs

- Annotated feature table with group ID and annotation type (isotope, adduct, in-source fragment, or singleton)
- Feature group membership report (feature ID → group ID mapping)
- Filtered/clustered feature matrix ready for downstream MS/MS annotation

## How to apply

Load a feature table containing m/z, retention time, and intensity values for all detected peaks. Define a retention time window (typically narrow, e.g., ±5–10 seconds) around each feature. Within that window, search for co-eluting features whose m/z values match expected mass differences: isotope shifts (1.003 Da for ¹³C), common adduct mass shifts (+H, +Na, +NH₄, +K, –H), or characteristic neutral losses (–H₂O, –NH₃). Group features sharing the same retention time envelope and matching mass relationships. Assign each group a group ID and annotation label. Features outside the retention time window or without matching mass offsets are retained as singletons or discarded based on quality thresholds.

## Related tools

- **masscube** (Implements feature group annotation mechanism with isotope, adduct, and in-source fragment detection logic applied within retention time windows) — https://github.com/huaxuyu/masscube/
- **Python** (Language and runtime environment for masscube package and custom filtering workflows)

## Evaluation signals

- Verify that all features within each group share a common retention time window (check max Δ RT ≤ tolerance).
- Verify that each feature pair within a group exhibits a mass offset matching one of the expected shifts (isotope +1.003 Da, adduct offset, or neutral loss mass).
- Verify that singleton features (those not grouped) have no co-eluting features with matching mass relationships within the RT window.
- Compare feature count before and after filtering; expect reduction if spurious peaks or noise are present.
- Spot-check annotated groups visually or via MS/MS confirmation to ensure isotope/adduct/fragment labels match chemical expectations (e.g., isotope group should show intensity ratio ~1:0.01 for ¹²C:¹³C).

## Limitations

- Accuracy depends critically on the retention time tolerance window; too narrow and true co-eluting features are missed; too wide and unrelated peaks are grouped.
- Mass shift dictionary must be comprehensive and accurate; missing or incorrectly specified adducts/losses will result in false negatives.
- No changelog found in repository documentation, limiting visibility into algorithm changes or bug fixes.
- Overlapping or poorly resolved chromatographic peaks may confound retention time correlation, leading to incorrect grouping.

## Evidence

- [other] isotope detection logic to identify features differing by 1.003 Da (carbon-13 isotope shift) within a retention time window: "Apply isotope detection logic to identify features differing by 1.003 Da (carbon-13 isotope shift) within a retention time window."
- [other] adduct detection to identify features related by common adduct mass shifts: "Apply adduct detection to identify features related by common adduct mass shifts (e.g., +H, +Na, +NH4, +K, –H)."
- [other] in-source fragment detection to identify features related by characteristic neutral loss patterns: "Apply in-source fragment detection to identify features related by characteristic neutral loss patterns (e.g., –H2O, –NH3)."
- [intro] Confident annotation of feature groups including isotopes, adducts and in-source fragments: "Confident annotation of feature groups including isotopes, adducts and in-source fragments."
- [other] Load the feature table (containing m/z, retention time, and intensity values for detected features): "Load the feature table (containing m/z, retention time, and intensity values for detected features)."