# Redundant Feature Identification Lcms

> Use when after alignment of two or more same-method nontargeted LCMS datasets (e.g., via Eclipse) when you have a feature table containing retention times and feature intensities across samples. Use it when redundancy is expected—e.

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

---


# Cluster redundant LCMS features by retention time and correlation

## Summary

Gravity identifies and groups redundant LCMS features—those arising from the same compound but detected as distinct entries—by applying retention-time proximity and intensity-correlation filtering. This step reduces false positives in nontargeted metabolomics datasets before annotation and statistical analysis.

## When to use

Apply this skill after alignment of two or more same-method nontargeted LCMS datasets (e.g., via Eclipse) when you have a feature table containing retention times and feature intensities across samples. Use it when redundancy is expected—e.g., multiple ionization adducts, in-source fragments, or instrumental artifacts creating duplicate feature entries for the same metabolite.

## When NOT to use

- Input is already a deduplicated or manually curated feature table with redundancy resolved.
- Features are from different LCMS methods or ionization modes where RT and correlation assumptions do not hold across the cohort.
- Sample cohort is very small (<5 injections) such that Pearson correlation is unstable or not meaningful.

## Inputs

- Feature Metadata table (bmxp.FMDATA): Compound_ID, RT, MZ, Intensity columns
- Feature Abundances table: pivot of Compound_ID × injection_id with abundances
- Retention time tolerance parameter (user-defined; e.g., ±0.05–0.2 min)
- Pearson correlation threshold parameter (e.g., 0.8–0.95)

## Outputs

- Feature Metadata table with appended Cluster_Num column (cluster assignment per feature)
- Feature Metadata table with appended Cluster_Size column (cluster membership count)
- Feature-to-cluster mapping table

## How to apply

Load an aligned LCMS feature table (Feature Metadata + Feature Abundances, indexed by Compound_ID × injection_id) with RT and intensity columns. Compute pairwise Pearson correlation coefficients between all features using their intensity profiles across samples. Apply two-stage filtering: (1) retention-time proximity—flag features whose RTs fall within a defined window (e.g., ±0.1 min or project-specific tolerance); (2) correlation threshold—merge only feature pairs exceeding a correlation cutoff (typically >0.8–0.9 for high redundancy confidence). Assign each merged group a unique Cluster_Num and record Cluster_Size. The rationale: correlated intensity patterns across samples + close RT values strongly indicate the same underlying compound; clustering reduces statistical noise and improves downstream annotation specificity.

## Related tools

- **Eclipse** (Upstream alignment tool that produces the aligned LCMS feature table consumed by Gravity) — https://github.com/broadinstitute/bmxp/blob/main/bmxp/eclipse/readme.md
- **bmxp (Python package)** (Parent package containing Gravity as a standalone module; provides shared schema (FMDATA, IMDATA, SMDATA) and file I/O) — https://github.com/broadinstitute/bmxp
- **Blueshift** (Downstream drift-correction tool that can operate on Gravity-clustered features) — https://github.com/broadinstitute/bmxp/blob/main/bmxp/blueshift/readme.md

## Examples

```
from bmxp.gravity import cluster; import bmxp; cluster(feature_metadata, feature_abundances, rt_tolerance=0.1, correlation_threshold=0.85)
```

## Evaluation signals

- Cluster_Num is assigned to every feature; no missing or null values in the output table.
- Cluster_Size values are consistent—each feature in a cluster of size N has Cluster_Size = N.
- Features within a cluster differ by ≤ the specified RT tolerance and have Pearson r ≥ the correlation threshold; features assigned to different clusters do not meet both criteria.
- Cluster assignments are deterministic (repeated runs on the same input yield identical results).
- Number of output feature rows equals the number of input feature rows (1:1 mapping; clustering does not remove features, only labels them).

## Limitations

- Pearson correlation assumes linear intensity co-variation and can fail when sample cohort is small (<5 injections) or when true redundancy involves non-linear adduct ionization patterns.
- RT tolerance is user-defined and method-dependent; no automatic or adaptive algorithm is described for selecting it.
- The README notes potential future incorporation of XIC (extracted ion chromatogram) shape analysis, implying current version does not account for peak morphology.
- Assumes Feature Metadata and Feature Abundances tables are already aligned; garbage-in, garbage-out if upstream alignment is poor.

## Evidence

- [readme] Gravity - Cluster redundant LCMS features based on RT and Correlation (And someday, XIC shape): "Gravity - Cluster redundant LCMS features based on RT and Correlation (And someday, XIC shape)"
- [other] Group features into clusters by applying retention-time proximity filtering (features within a defined RT window are candidates for clustering) and correlation threshold filtering (only feature pairs exceeding a correlation cutoff are merged).: "Group features into clusters by applying retention-time proximity filtering (features within a defined RT window are candidates for clustering) and correlation threshold filtering (only feature pairs"
- [other] Compute pairwise Pearson correlation coefficients between all features using their intensity profiles across samples.: "Compute pairwise Pearson correlation coefficients between all features using their intensity profiles across samples."
- [other] Gravity is a standalone module that clusters redundant LCMS features using retention time (RT) and correlation as the primary clustering criteria: "Gravity is a standalone module that clusters redundant LCMS features using retention time (RT) and correlation as the primary clustering criteria"
- [readme] All BMXP modules use a shared schema and file formats with our prefered columns headers.: "All BMXP modules use a shared schema and file formats with our prefered columns headers."