# Metabolite Feature Extraction Xcms

> Use when you have one or multiple raw mzXML/mzML files from DDA, DIA, or full-scan LCMS analyses and need to detect, align, and quantify metabolite features across samples to create a unified feature matrix before MS2 annotation or in-source fragment analysis.

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

---


# metabolite-feature-extraction-xcms

## Summary

Extract and align MS1 metabolite features from raw LCMS data (mzXML/mzML format) using the XCMS algorithm within the ISFrag R package. This produces a feature table with m/z, retention time, and intensity values suitable for downstream MS2 annotation and in-source fragment identification.

## When to use

You have one or multiple raw mzXML/mzML files from DDA, DIA, or full-scan LCMS analyses and need to detect, align, and quantify metabolite features across samples to create a unified feature matrix before MS2 annotation or in-source fragment analysis.

## When NOT to use

- Input is already a processed feature table (use custom.featuretable instead)
- Data format is not mzXML or mzML (XCMS requires these binary/text mass spectrometry formats)
- You need only CAMERA adduct and isotope annotation without full XCMS feature extraction (CAMERA requires XCMS-only analysis path)

## Inputs

- raw LCMS data files (mzXML or mzML format)
- directory path containing one or multiple mzXML files

## Outputs

- feature table (dataframe with columns: mz, rt, rtmin, rtmax, intensity/maxo per sample)
- CSV file in ISFrag-compatible format
- MSnbase object (from XCMS.featuretable function)

## How to apply

Load raw LCMS data files (mzXML or mzML format) into R using XCMS within ISFrag. Apply XCMS peak-picking to detect peaks across all samples, specifying appropriate peakwidth parameters (e.g., c(5,20) seconds). Align peaks across samples to create a unified feature matrix with m/z and retention time dimensions. For multi-sample analyses, XCMS automatically performs peak alignment and missing value filling to generate features detected in some but not all samples. Export the resulting feature table as a CSV with columns: m/z, retention time, min retention time, max retention time, and intensity values per sample. The output dataframe becomes input for ISFrag's MS2 annotation and ISF identification steps.

## Related tools

- **XCMS** (Performs peak detection, alignment, and intensity integration on MS1 spectra) — https://rdrr.io/bioc/xcms/man/
- **ISFrag** (R package wrapper that calls XCMS for feature extraction and integrates with downstream MS2 annotation and ISF identification) — https://github.com/HuanLab/ISFrag.git
- **R** (Runtime environment; version 4.0.0 or above required)
- **RStudio** (Recommended IDE for installation and execution)
- **devtools** (R package used to install ISFrag from GitHub)

## Examples

```
xcmsFT <- XCMS.featuretable(MS1directory = "X:/Users/Sam_Shen/ISFtest20210127/RP(-)/RP(-)1/fullscan", type = "single", peakwidth = c(5,20))
```

## Evaluation signals

- Output feature table contains all required columns (mz, rt, rtmin, rtmax, intensity) with no missing values in metadata columns
- Feature table row count and column count match expected dimensions (features × samples)
- m/z values are numeric and within expected mass range for target metabolites; retention time values are in seconds and span the LC gradient duration
- Intensity values are positive numeric; multi-sample analyses show features with non-zero intensity in at least one sample (successful alignment and filling)
- CSV export successfully loads and parses without encoding errors; schema matches ISFrag input specification (column order: m/z, rt, rtmin, rtmax, then intensity columns)

## Limitations

- XCMS peak-picking quality depends on appropriate peakwidth parameter selection; incorrect values may miss narrow peaks or detect noise
- Multi-sample peak alignment assumes samples have comparable retention time shift; very different LC conditions across samples may reduce alignment accuracy
- CAMERA adduct and isotope annotation features are only available when using XCMS alone, not when combining XCMS features with custom feature tables
- All mzXML files must be placed in a single folder containing no other irrelevant mzXML files to avoid unintended file inclusion

## Evidence

- [readme] One or multiple mzXML files from DDA, DIA, or fullscan analyses can be analyzed at once using XCMS to extract MS1 features.: "One or multiple mzXML files from DDA, DIA, or fullscan analyses can be analyzed at once using XCMS to extract MS1 features."
- [readme] For multi-sample analyses, peak alignment and filling will be performed by XCMS.: "for multi-sample analyses, peak alignment and filling will be performed by XCMS"
- [other] Detect peaks across all samples using XCMS peak-picking algorithm. Align peaks across samples to create a unified feature matrix with retention time and m/z dimensions. Fill missing values for peaks detected in some samples but not others.: "Detect peaks across all samples using XCMS peak-picking algorithm. 4. Align peaks across samples to create a unified feature matrix with retention time and m/z dimensions. 5. Fill missing values for"
- [readme] In order for ISFrag to succesfully read the provided csv file, it must contain only columns in the following order: m/z, retention time, min retention time, max retention time, followed by an additional column containing the intensities: "it must contain only columns in the following order: m/z, retention time, min retention time, max retention time, followed by an additional column containing the intensities"
- [readme] CAMERA adduct and isotope annotation can only be used for XCMS ONLY ISFrag analysis.: "CAMERA adduct and isotope annotation can only be used for XCMS ONLY ISFrag analysis"