xcms-object-handling-and-preprocessing
Summary
Prepare raw mass spectrometry data for downstream metabolomics analysis by applying XCMS feature detection, alignment, retention time correction, and missing value imputation. This preprocessing pipeline transforms raw NetCDF/mzML files into a grouped feature matrix suitable for clustering and annotation.
When to use
You have raw gas or liquid chromatography–mass spectrometry data (in NetCDF or mzML format) and need to detect features, align them across samples by retention time and mass-to-charge ratio, correct for retention time drift, and fill missing values before downstream metabolite clustering or annotation.
When NOT to use
- Input is already a preprocessed feature table or intensity matrix (e.g., CSV with features as rows and samples as columns) — skip directly to clustering.
- Data has already undergone XCMS processing and retention time correction — avoid re-running to prevent over-alignment artifacts.
- Instrument data is in proprietary vendor formats not supported by XCMS (e.g., raw Bruker .d or Waters .raw without prior conversion) — convert to open formats first.
Inputs
- Raw mass spectrometry data files (NetCDF, mzML, or CDF format)
- Sample metadata or experiment design (optional, but recommended for downstream steps)
Outputs
- XCMS xcmsSet object containing grouped and aligned features
- Feature-by-sample intensity matrix with filled missing values
- Feature metadata including retention time, m/z, and sample groupings
How to apply
Execute the XCMS preprocessing workflow in sequence: (1) Load raw instrument files using xcmsSet() to perform centroid feature detection across all samples. (2) Group features across samples by retention time and m/z using group() with default parameters (mass tolerance ~0.015 Da, retention time window ~60 s). (3) Correct for systematic retention time drift across the analytical run using retcor() with symmetric family setting to align features between samples. (4) Regroup features after retention time correction using group() again with slightly relaxed bandwidth (bw = 10) to account for post-correction variation. (5) Impute missing values using fillPeaks() to ensure a complete feature-by-sample intensity matrix. The output xcmsSet object contains aligned, grouped features ready for unsupervised clustering methods like RAMClustR that rely on consistent retention time and intensity correlation structure.
Related tools
- XCMS (Core tool for feature detection, grouping, and retention time correction of raw mass spectrometry data)
- dynamicTreeCut (Used by downstream tools (e.g., RAMClustR) for hierarchical clustering of aligned features; not directly part of preprocessing but depends on XCMS preprocessing output)
Examples
xset <- xcmsSet(cdffiles); xset <- group(xset); xset <- retcor(xset, family="symmetric", plottype=NULL); xset <- group(xset, bw=10); xset <- fillPeaks(xset)
Evaluation signals
- xcmsSet object contains non-zero feature count and feature matrix dimensions match expected (features × samples)
- Retention time values across samples show tight clustering after retcor() and regroup() for features from the same compound (typically ±10 s)
- Missing value rate after fillPeaks() is zero or near-zero; SpecAbund matrix has no NA values
- Feature intensity distributions before and after fillPeaks() are comparable (filled intensities do not dominate or skew global statistics)
- xcmsSet can be successfully passed to downstream tools (e.g., ramclustR(xcmsObj = xset)) without schema errors
Limitations
- Retention time correction assumes that the majority of detected features are real signals; high background or contamination can distort alignment.
- Missing value imputation via fillPeaks() uses zero or minimum intensity logic and may introduce bias for features genuinely absent in some samples.
- XCMS parameters (mass tolerance, retention time window, bandwidth) are heuristic and may require optimization for different instrument types or sample complexity.
- No built-in changelog or version history documented; breaking changes between XCMS versions may affect reproducibility.
Evidence
- [intro] Feature detection and grouping workflow overview: "xset <- xcmsSet(cdffiles) # detect features"
- [intro] Retention time grouping step: "xset <- group(xset) # group features across samples by retention time and mass"
- [intro] Retention time drift correction: "xset <- retcor(xset, family = "symmetric", plottype = NULL) # correct for drive in retention time"
- [intro] Regroup after retention time correction: "xset <- group(xset, bw = 10) # regroup following rt correction"
- [intro] Missing value imputation: "xset <- fillPeaks(xset) # 'fillPeaks' to remove missing values in final dataset"
- [intro] XCMS purpose and integration: "XCMS is a commonly used tool to detect all the signals from a metabolomics dataset, generating aligned features"
- [intro] Features from same compound alignment property: "two features derived from the same compound with have (approximately) the same retention time"
1---2name: xcms-object-handling-and-preprocessing3description: Use when you have raw gas or liquid chromatography–mass spectrometry data (in NetCDF or mzML format) and need to detect features, align them across samples by retention time and mass-to-charge ratio, correct for retention time drift, and fill missing values before downstream metabolite clustering.4license: CC-BY-4.05---67# xcms-object-handling-and-preprocessing89## Summary1011Prepare raw mass spectrometry data for downstream metabolomics analysis by applying XCMS feature detection, alignment, retention time correction, and missing value imputation. This preprocessing pipeline transforms raw NetCDF/mzML files into a grouped feature matrix suitable for clustering and annotation.1213## When to use1415You have raw gas or liquid chromatography–mass spectrometry data (in NetCDF or mzML format) and need to detect features, align them across samples by retention time and mass-to-charge ratio, correct for retention time drift, and fill missing values before downstream metabolite clustering or annotation.1617## When NOT to use1819- Input is already a preprocessed feature table or intensity matrix (e.g., CSV with features as rows and samples as columns) — skip directly to clustering.20- Data has already undergone XCMS processing and retention time correction — avoid re-running to prevent over-alignment artifacts.21- Instrument data is in proprietary vendor formats not supported by XCMS (e.g., raw Bruker .d or Waters .raw without prior conversion) — convert to open formats first.2223## Inputs2425- Raw mass spectrometry data files (NetCDF, mzML, or CDF format)26- Sample metadata or experiment design (optional, but recommended for downstream steps)2728## Outputs2930- XCMS xcmsSet object containing grouped and aligned features31- Feature-by-sample intensity matrix with filled missing values32- Feature metadata including retention time, m/z, and sample groupings3334## How to apply3536Execute the XCMS preprocessing workflow in sequence: (1) Load raw instrument files using xcmsSet() to perform centroid feature detection across all samples. (2) Group features across samples by retention time and m/z using group() with default parameters (mass tolerance ~0.015 Da, retention time window ~60 s). (3) Correct for systematic retention time drift across the analytical run using retcor() with symmetric family setting to align features between samples. (4) Regroup features after retention time correction using group() again with slightly relaxed bandwidth (bw = 10) to account for post-correction variation. (5) Impute missing values using fillPeaks() to ensure a complete feature-by-sample intensity matrix. The output xcmsSet object contains aligned, grouped features ready for unsupervised clustering methods like RAMClustR that rely on consistent retention time and intensity correlation structure.3738## Related tools3940- **XCMS** (Core tool for feature detection, grouping, and retention time correction of raw mass spectrometry data)41- **dynamicTreeCut** (Used by downstream tools (e.g., RAMClustR) for hierarchical clustering of aligned features; not directly part of preprocessing but depends on XCMS preprocessing output)4243## Examples4445```46xset <- xcmsSet(cdffiles); xset <- group(xset); xset <- retcor(xset, family="symmetric", plottype=NULL); xset <- group(xset, bw=10); xset <- fillPeaks(xset)47```4849## Evaluation signals5051- xcmsSet object contains non-zero feature count and feature matrix dimensions match expected (features × samples)52- Retention time values across samples show tight clustering after retcor() and regroup() for features from the same compound (typically ±10 s)53- Missing value rate after fillPeaks() is zero or near-zero; SpecAbund matrix has no NA values54- Feature intensity distributions before and after fillPeaks() are comparable (filled intensities do not dominate or skew global statistics)55- xcmsSet can be successfully passed to downstream tools (e.g., ramclustR(xcmsObj = xset)) without schema errors5657## Limitations5859- Retention time correction assumes that the majority of detected features are real signals; high background or contamination can distort alignment.60- Missing value imputation via fillPeaks() uses zero or minimum intensity logic and may introduce bias for features genuinely absent in some samples.61- XCMS parameters (mass tolerance, retention time window, bandwidth) are heuristic and may require optimization for different instrument types or sample complexity.62- No built-in changelog or version history documented; breaking changes between XCMS versions may affect reproducibility.6364## Evidence6566- [intro] Feature detection and grouping workflow overview: "xset <- xcmsSet(cdffiles) # detect features"67- [intro] Retention time grouping step: "xset <- group(xset) # group features across samples by retention time and mass"68- [intro] Retention time drift correction: "xset <- retcor(xset, family = "symmetric", plottype = NULL) # correct for drive in retention time"69- [intro] Regroup after retention time correction: "xset <- group(xset, bw = 10) # regroup following rt correction"70- [intro] Missing value imputation: "xset <- fillPeaks(xset) # 'fillPeaks' to remove missing values in final dataset"71- [intro] XCMS purpose and integration: "XCMS is a commonly used tool to detect all the signals from a metabolomics dataset, generating aligned features"72- [intro] Features from same compound alignment property: "two features derived from the same compound with have (approximately) the same retention time"
HolobiomicsLab 