# Ms1 Feature Extraction

> Use when when you have an LC-HRMS feature table (with m/z values, retention times, and isotopic signatures) and a suspect compound database (with reference m/z, expected retention time windows, isotope ratios, and neutral loss fragments), and you need to rapidly prioritize which features are most.

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

---


# ms1-feature-extraction

## Summary

Extract and integrate multiple MS1 chemical predictors (m/z, retention times, isotopic patterns, neutral loss patterns) from LC-HRMS features to compute unified proximity scores between detected features and suspect compounds. This enables rapid prioritization of compound candidates during suspect screening workflows.

## When to use

When you have an LC-HRMS feature table (with m/z values, retention times, and isotopic signatures) and a suspect compound database (with reference m/z, expected retention time windows, isotope ratios, and neutral loss fragments), and you need to rapidly prioritize which features are most likely to correspond to which suspects before MS/MS annotation or manual review.

## When NOT to use

- Input is already a manually validated or MS/MS-confirmed compound assignment — use this skill for pre-annotation only, not to second-guess confirmed identities.
- You lack reference isotopic or neutral loss patterns for your suspect compounds — the scoring will be incomplete and reliability will degrade.
- Your feature table does not include retention time data — RT proximity scoring will be unavailable, reducing discriminatory power.

## Inputs

- LC-HRMS feature table (m/z values, retention times, isotopic pattern signatures)
- Suspect compound database (reference m/z, expected retention time windows, isotope ratios, neutral loss fragments)
- Mass error tolerance (ppm or absolute Da)
- Retention time deviation window (minutes)
- Component weights for ensemble scoring

## Outputs

- Feature–suspect proximity scores (per feature–suspect pair)
- Ranked candidate compound list (sorted by proximity score)
- Filtered prioritized compound assignments (above score threshold)

## How to apply

Load the feature table and suspect compound database into Scannotation. For each feature–suspect pair, compute four component scores: (1) m/z distance using absolute or relative mass error tolerance (typically ppm-based); (2) retention time proximity by comparing observed vs. predicted RT within an acceptable deviation window; (3) isotopic pattern match by comparing observed isotope abundance ratios to theoretical patterns for the suspect; (4) neutral loss pattern match by identifying common loss fragments (H₂O, CO₂, CH₄) in the observed feature fragmentation profile relative to the suspect's expected structure. Combine these four scores via weighted ensemble (default: weighted sum) to produce a final feature–suspect proximity score. Rank all candidates by this score and apply a threshold filter to generate a prioritized compound list for downstream validation.

## Related tools

- **Scannotation** (Automated suspect screening tool that implements the MS1 predictor combiner scoring pipeline to compute feature–suspect proximity scores and prioritize compound candidates for LC-HRMS pre-annotation.) — https://github.com/scannotation/Scannotation_software

## Evaluation signals

- Proximity scores are computed for all feature–suspect pairs without missing values; check that output table has dimensions = (n_features × n_suspects).
- Component scores (m/z, RT, isotope, neutral loss) fall within their expected ranges (typically 0–1 or 0–100 depending on normalization); verify no NaN, Inf, or out-of-bound values.
- Ranked output is sorted in descending order by proximity score; spot-check that top-ranked candidates have higher scores than lower-ranked ones.
- Filtered output respects the applied threshold: all remaining feature–suspect pairs have proximity score ≥ threshold; all removed pairs have score < threshold.
- For known positive control feature–suspect pairs, verify that the assigned proximity score is among the top-ranked (e.g., top 5%) for that feature, confirming the scoring mechanism is not inverting or randomizing ranks.

## Limitations

- Scoring accuracy depends critically on the quality and completeness of reference data in the suspect compound database (isotope ratios, neutral loss fragments). Missing or incorrect reference patterns will degrade ranking.
- Retention time prediction quality varies across chromatographic methods and column chemistries; RT-based scoring may be unreliable if predicted RT windows are poorly calibrated or method-specific.
- The weighted ensemble method for combining component scores is heuristic; optimal weights may vary by chemical class or sample matrix, requiring method-specific tuning.
- Scannotation was developed and tested on Windows 10 and Mac (in Windows virtual machine); cross-platform compatibility on native Linux or other OS is not documented.

## Evidence

- [readme] Scannotation combines MS1 chemical predictors and scores proximity for feature-suspect prioritization.: "This software combines several MS1 chemical predictors: m/z, retention times, isotopic patterns and neutral loss patterns, to score the proximity between features and suspects, thus efficiently"
- [other] The workflow involves loading data, computing four component scores, and combining them via ensemble method.: "Load feature table (m/z values, retention times, isotopic pattern signatures) and suspect compound database (reference m/z, expected retention time windows, isotope ratios, neutral loss fragments)."
- [readme] Scannotation enables rapid pre-annotation of LC-HRMS datasets through automated suspect screening.: "Scannotation is an automated and user-friendly suspect screening tool for the rapid pre-annotation of LC-HRMS datasets."
- [readme] Development and testing platform details.: "Scannotation was developed on Windows 10 and tested on both Windows and on a Mac computer in a Windows virtual machine."