# Feature Pair Scoring In Metabolomics

> Use when use this skill after XCMS feature detection and alignment on non-targeted LC-MS or GC-MS metabolomics data, when you have aligned features with quantitative profiles across samples and need to group features that co-originate from the same compound (accounting for isotopic peaks, adducts.

- Skill: `holobiomicslab/feature-pair-scoring-in-metabolomics` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/feature-pair-scoring-in-metabolomics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/feature-pair-scoring-in-metabolomics/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/feature-pair-scoring-in-metabolomics

---


# Reconstruct the total similarity score as the product of retention time and correlational similarity

## Summary

Compute pairwise total similarity scores for metabolomics features by multiplying retention time similarity and correlational similarity metrics. This scoring approach identifies features likely derived from the same compound (score → 1) versus different compounds (score → 0), enabling unsupervised feature clustering in non-targeted LC-MS and GC-MS data.

## When to use

Use this skill after XCMS feature detection and alignment on non-targeted LC-MS or GC-MS metabolomics data, when you have aligned features with quantitative profiles across samples and need to group features that co-originate from the same compound (accounting for isotopic peaks, adducts, and fragments). Apply it as a precursor to hierarchical clustering-based deconvolution.

## When NOT to use

- Features have not yet been detected and aligned by XCMS or equivalent; use feature detection first.
- Dataset contains only a single sample or very few samples; Pearson correlation coefficients become unstable and unreliable.
- Input is already grouped or annotated as single compounds; the purpose of this skill is de novo grouping, not validation.
- Retention time correction (retcor) has not been applied; uncorrected RT drift will inflate false similarity scores.

## Inputs

- XCMS feature table with aligned m/z, retention time, and intensity values across samples (NetCDF, mzML, or CSV format)
- Feature quantification matrix (samples × features) with missing value imputation completed (e.g., via fillPeaks)

## Outputs

- Symmetric pairwise total similarity matrix (features × features)
- Retention time similarity matrix (intermediate)
- Correlational similarity matrix / Pearson correlation coefficient matrix (intermediate)

## How to apply

Extract retention time (RT) values and Pearson correlation coefficients for all feature pairs from XCMS-processed feature tables. Normalize RT differences into a similarity score (0–1 scale; e.g., Gaussian kernel or inverse distance function). Compute Pearson correlation coefficients between quantitative feature intensity profiles across all samples. Multiply the RT similarity and correlational similarity scores element-wise for each feature pair to produce a symmetric total similarity matrix. The product-based scoring is justified because both conditions (same RT and same quantitative trend) must hold simultaneously for features to originate from one compound; hence product captures this AND logic better than sum or other combinations. Output the resulting symmetric similarity matrix in a format suitable for hierarchical clustering (e.g., distance matrix or similarity matrix for input to dynamicTreeCut).

## Related tools

- **XCMS** (Detects aligned features (m/z, RT, intensity) and provides the input feature table with sample-wise quantification) — https://bioconductor.org/packages/xcms/
- **R** (Execution environment for Pearson correlation computation, matrix normalization, and element-wise multiplication)
- **dynamicTreeCut** (Receives the output similarity matrix and performs hierarchical clustering and dendrogram cutting to group features) — https://cran.r-project.org/package=dynamicTreeCut
- **RAMClustR** (Wraps this scoring workflow and hierarchical clustering into a unified unsupervised feature deconvolution pipeline) — https://github.com/cbroeckl/RAMClustR

## Examples

```
RC <- ramclustR(xcmsObj = xset, ExpDes=experiment)
```

## Evaluation signals

- Symmetry check: verify the output similarity matrix is symmetric (matrix[i,j] ≈ matrix[j,i]) to within numerical precision.
- Range check: all entries in the total similarity matrix must lie in [0, 1] (product of two [0,1] scores).
- High-confidence groupings: feature pairs with total similarity = 1.0 should exhibit both RT proximity (within instrument tolerance, typically <0.5 min for LC-MS) and Pearson r > 0.9 across samples.
- Low-confidence separation: feature pairs with total similarity = 0 or near-zero should show either significant RT divergence OR very weak correlation (|r| < 0.3).
- Dendrogram cluster coherence: after hierarchical clustering of the similarity matrix, cut clusters should yield features within each cluster that share near-identical MS/MS fragmentation patterns and molecular formulas when further analyzed.

## Limitations

- Pearson correlation assumes linear co-variation; non-linear abundance relationships or batch effects not corrected by QC normalization may inflate spurious correlations between unrelated features.
- Retention time tolerance is instrument- and column-dependent; the RT similarity normalization function (e.g., Gaussian kernel bandwidth) must be calibrated per platform and may require manual tuning.
- Features with very low intensity or sparse detection across samples may have unstable correlation estimates, inflating false similarities; pre-filtering by coefficient of variation (CV) is recommended.
- The product rule assumes independence of RT and correlation signals; strong confounding between retention time and sample batch effects can bias both metrics simultaneously.
- No changelog or version history documented; reproducibility across RAMClustR versions may be compromised.

## Evidence

- [intro] RT and correlational similarity product approach: "RAMClustR calculates a pairwise total similarity score as the product of retention time similarity and correlational similarity scores."
- [intro] Interpretation of score outcomes: "A score of 1×1=1 indicates features likely derive from one compound, while scores like 1×0=0 or 0×1=0 indicate features represent different compounds."
- [intro] Two necessary conditions for same-compound features: "two features derived from the same compound with have (approximately) the same retention time. The second is that two features derived from the same compound will have (approximately) the same"
- [intro] Product justification: AND logic: "Since both conditions must be met, the product of the two similarity scores provides the best approximatio of the total similarity score"
- [readme] Concrete workflow steps from README: "ramclustObj <- rc.ramclustr(ramclustObj = ramclustObj)"
- [intro] Feature detection and preprocessing pipeline: "xset <- fillPeaks(xset)  # 'fillPeaks' to remove missing values in final dataset"