chromatographic-peak-detection-and-grouping
Summary
Detect and group chromatographic peaks across LC-MS samples, then identify and correct misaligned feature groups using compound-specific warping functions. This skill bridges XCMS peak detection with ncGTW realignment to reduce coefficient-of-variation in aligned retention times.
When to use
When you have processed LC-MS data through XCMS alignment but suspect misaligned features due to retention-time drift over long acquisition periods (>1 week) or large sample batches (hundreds of samples), or when peak-filling produces unexpectedly high coefficient-of-variation (CV > 0.3) for specific m/z features. Apply this skill after XCMS grouping but before downstream statistical analysis or peak-regrouping.
When NOT to use
- Input data has already been processed through ncGTW or another specialized retention-time correction tool — applying this skill would introduce redundant warping.
- Coefficient-of-variation for all features is already < 0.15 after XCMS peak-filling — misalignment is unlikely and ncGTW realignment will not improve downstream analysis.
- Sample count is small (< 10–20 samples) or acquisition time is short (< 1 day) — ncGTW's constraint-based neighbor warping is optimized for large, long-duration studies where retention-time drift structures are pronounced.
Inputs
- XCMS-aligned LC-MS feature table (xcmsSet object or equivalent)
- Raw LC-MS data in mzML, mzXML, or NetCDF format
- Baseline coefficient-of-variation values per feature (numeric vector)
- Sample metadata with temporal or batch structure
Outputs
- ncGTW-realigned feature table with individualized retention-time warping functions
- Updated coefficient-of-variation values per feature after peak-filling
- Warping function curves for each compound across sample pairs
- Comparison table (XCMS CV vs. ncGTW CV for each misaligned feature)
How to apply
First, load the XCMS-aligned dataset and compute CV values for each detected feature using compCV to establish a baseline (e.g., feature 1 CV = 0.369). Next, apply ncGTW's misalignment detection algorithm, which estimates p-values for each feature using higher-resolution alignment and identifies features with sufficiently small p-values and disjoint sample subsets. For misaligned features, invoke ncGTW's reference-free multiple alignment method, which performs pairwise alignments between samples while constraining warping functions on neighboring samples to estimate individualized warping functions for each compound. After ncGTW realignment, apply fillPeaks and recompute CV values to verify improvement (target: CV reduction to <0.25 for feature 1, <0.15 for feature 2). The realignment succeeds if CV values decrease substantially and remain consistent across the realigned feature set.
Related tools
- ncGTW (Detects misaligned features from XCMS and realigns them using individualized compound-specific warping functions with neighbor-wise constraints) — https://github.com/ChiungTingWu/ncGTW
- xcms (Performs initial peak detection, grouping, and alignment; ncGTW operates as a plug-in to correct misaligned feature groups identified by XCMS)
- R (Host language for ncGTW and xcms packages; required for executing workflow steps (compCV, fillPeaks, alignment functions))
- graphical time warping (GTW) (Foundational dynamic time warping method upon which ncGTW improves by adding compound-specificity and neighbor constraints)
Examples
library(ncGTW); library(xcms); xs_aligned <- xcmsSet(...); cv_before <- compCV(xs_aligned); xs_realigned <- ncGTW(xs_aligned); xs_realigned <- fillPeaks(xs_realigned); cv_after <- compCV(xs_realigned);
Evaluation signals
- Coefficient-of-variation for realigned features decreases by ≥ 30% after ncGTW processing and peak-filling (e.g., 0.369 → 0.229 for feature 1, 0.351 → 0.119 for feature 2).
- P-values computed by ncGTW misalignment detection algorithm identify only a small, interpretable subset of features (not all features are flagged as misaligned).
- Warping function curves estimated for each compound are smooth and consistent across neighboring sample pairs (no sharp discontinuities or wild oscillations).
- Peak-regrouping accuracy (if evaluated) improves downstream or fragmentation pattern consistency is preserved for the realigned features.
- CV values remain stable and low when recomputed on an independent holdout sample set, indicating generalization of the learned warping functions.
Limitations
- ncGTW assumes misalignment is driven by retention-time drift and compound-specific peak shifts; it will not correct for m/z calibration errors or ionization efficiency changes.
- The algorithm requires sufficient sample density and temporal structure (neighboring samples should be similar) for constraint-based warping to work; sparse or randomly ordered samples may not benefit.
- No changelog is available in the repository, so version-specific behavior and bug fixes are difficult to track.
- ncGTW's misalignment detection relies on p-value thresholding; results are sensitive to the choice of resolution used in higher-resolution alignment and the p-value cutoff.
Evidence
- [other] ncGTW realignment reduced CV after peak-filling from 0.369 to 0.229 for feature 1 and from 0.351 to 0.119 for feature 2: "ncGTW realignment reduced CV after peak-filling from 0.369 to 0.229 for feature 1 and from 0.351 to 0.119 for feature 2, compared to XCMS warping functions."
- [intro] ncGTW uses individualized warping functions for different compounds and assigns constraint edges on warping functions of neighboring samples: "ncGTW uses individualized warping functions for different compounds and assigns constraint edges on warping functions of neighboring samples. That is, ncGTW avoids the popular but not accurate"
- [intro] xcms may have some misaligned features, and there is a function in ncGTW to identify such misalignments: "Due to the same warping function assumption or bad parameter settings,
xcms may have some misaligned features, and there is a function in ncGTW to identify such misalignments. After identifying"
- [readme] ncGTW detects the misaligned features with two criterions. First, ncGTW algorithm estimates the p-value of each feature using higher resolution alignment result, where the p-value is given by the null hypothesis with accurate alignment. Second, we identifies all features with sufficiently small p-values and disjoint sample subsets.: "ncGTW detects the misaligned features with two criterions. First, ncGTW algorithm estimates the p-value of each feature using higher resolution alignment result, where the p-value is given by the"
- [readme] ncGTW performs all possible pairwise alignments between each two sample with the structure information in the dataset: "First, instead of set a certain reference, ncGTW performs all possible pairwise alignments between each two sample with the structure information in the dataset."
- [intro] ncGTW is an R package developed as a plug-in of xcms, a popular LC-MS data analysis R package: "
ncGTW is an R package developed as a plug-in of xcms, a popular LC-MS data analysis R package"
1---2name: chromatographic-peak-detection-and-grouping3description: Use when when you have processed LC-MS data through XCMS alignment but suspect misaligned features due to retention-time drift over long acquisition periods (>1 week) or large sample batches (hundreds of samples), or when peak-filling produces unexpectedly high coefficient-of-variation (CV > 0.4license: CC-BY-4.05---67# chromatographic-peak-detection-and-grouping89## Summary1011Detect and group chromatographic peaks across LC-MS samples, then identify and correct misaligned feature groups using compound-specific warping functions. This skill bridges XCMS peak detection with ncGTW realignment to reduce coefficient-of-variation in aligned retention times.1213## When to use1415When you have processed LC-MS data through XCMS alignment but suspect misaligned features due to retention-time drift over long acquisition periods (>1 week) or large sample batches (hundreds of samples), or when peak-filling produces unexpectedly high coefficient-of-variation (CV > 0.3) for specific m/z features. Apply this skill after XCMS grouping but before downstream statistical analysis or peak-regrouping.1617## When NOT to use1819- Input data has already been processed through ncGTW or another specialized retention-time correction tool — applying this skill would introduce redundant warping.20- Coefficient-of-variation for all features is already < 0.15 after XCMS peak-filling — misalignment is unlikely and ncGTW realignment will not improve downstream analysis.21- Sample count is small (< 10–20 samples) or acquisition time is short (< 1 day) — ncGTW's constraint-based neighbor warping is optimized for large, long-duration studies where retention-time drift structures are pronounced.2223## Inputs2425- XCMS-aligned LC-MS feature table (xcmsSet object or equivalent)26- Raw LC-MS data in mzML, mzXML, or NetCDF format27- Baseline coefficient-of-variation values per feature (numeric vector)28- Sample metadata with temporal or batch structure2930## Outputs3132- ncGTW-realigned feature table with individualized retention-time warping functions33- Updated coefficient-of-variation values per feature after peak-filling34- Warping function curves for each compound across sample pairs35- Comparison table (XCMS CV vs. ncGTW CV for each misaligned feature)3637## How to apply3839First, load the XCMS-aligned dataset and compute CV values for each detected feature using compCV to establish a baseline (e.g., feature 1 CV = 0.369). Next, apply ncGTW's misalignment detection algorithm, which estimates p-values for each feature using higher-resolution alignment and identifies features with sufficiently small p-values and disjoint sample subsets. For misaligned features, invoke ncGTW's reference-free multiple alignment method, which performs pairwise alignments between samples while constraining warping functions on neighboring samples to estimate individualized warping functions for each compound. After ncGTW realignment, apply fillPeaks and recompute CV values to verify improvement (target: CV reduction to <0.25 for feature 1, <0.15 for feature 2). The realignment succeeds if CV values decrease substantially and remain consistent across the realigned feature set.4041## Related tools4243- **ncGTW** (Detects misaligned features from XCMS and realigns them using individualized compound-specific warping functions with neighbor-wise constraints) — https://github.com/ChiungTingWu/ncGTW44- **xcms** (Performs initial peak detection, grouping, and alignment; ncGTW operates as a plug-in to correct misaligned feature groups identified by XCMS)45- **R** (Host language for ncGTW and xcms packages; required for executing workflow steps (compCV, fillPeaks, alignment functions))46- **graphical time warping (GTW)** (Foundational dynamic time warping method upon which ncGTW improves by adding compound-specificity and neighbor constraints)4748## Examples4950```51library(ncGTW); library(xcms); xs_aligned <- xcmsSet(...); cv_before <- compCV(xs_aligned); xs_realigned <- ncGTW(xs_aligned); xs_realigned <- fillPeaks(xs_realigned); cv_after <- compCV(xs_realigned);52```5354## Evaluation signals5556- Coefficient-of-variation for realigned features decreases by ≥ 30% after ncGTW processing and peak-filling (e.g., 0.369 → 0.229 for feature 1, 0.351 → 0.119 for feature 2).57- P-values computed by ncGTW misalignment detection algorithm identify only a small, interpretable subset of features (not all features are flagged as misaligned).58- Warping function curves estimated for each compound are smooth and consistent across neighboring sample pairs (no sharp discontinuities or wild oscillations).59- Peak-regrouping accuracy (if evaluated) improves downstream or fragmentation pattern consistency is preserved for the realigned features.60- CV values remain stable and low when recomputed on an independent holdout sample set, indicating generalization of the learned warping functions.6162## Limitations6364- ncGTW assumes misalignment is driven by retention-time drift and compound-specific peak shifts; it will not correct for m/z calibration errors or ionization efficiency changes.65- The algorithm requires sufficient sample density and temporal structure (neighboring samples should be similar) for constraint-based warping to work; sparse or randomly ordered samples may not benefit.66- No changelog is available in the repository, so version-specific behavior and bug fixes are difficult to track.67- ncGTW's misalignment detection relies on p-value thresholding; results are sensitive to the choice of resolution used in higher-resolution alignment and the p-value cutoff.6869## Evidence7071- [other] ncGTW realignment reduced CV after peak-filling from 0.369 to 0.229 for feature 1 and from 0.351 to 0.119 for feature 2: "ncGTW realignment reduced CV after peak-filling from 0.369 to 0.229 for feature 1 and from 0.351 to 0.119 for feature 2, compared to XCMS warping functions."72- [intro] ncGTW uses individualized warping functions for different compounds and assigns constraint edges on warping functions of neighboring samples: "ncGTW uses individualized warping functions for different compounds and assigns constraint edges on warping functions of neighboring samples. That is, ncGTW avoids the popular but not accurate"73- [intro] xcms may have some misaligned features, and there is a function in ncGTW to identify such misalignments: "Due to the same warping function assumption or bad parameter settings, `xcms` may have some misaligned features, and there is a function in `ncGTW` to identify such misalignments. After identifying"74- [readme] ncGTW detects the misaligned features with two criterions. First, ncGTW algorithm estimates the p-value of each feature using higher resolution alignment result, where the p-value is given by the null hypothesis with accurate alignment. Second, we identifies all features with sufficiently small p-values and disjoint sample subsets.: "ncGTW detects the misaligned features with two criterions. First, ncGTW algorithm estimates the p-value of each feature using higher resolution alignment result, where the p-value is given by the"75- [readme] ncGTW performs all possible pairwise alignments between each two sample with the structure information in the dataset: "First, instead of set a certain reference, ncGTW performs all possible pairwise alignments between each two sample with the structure information in the dataset."76- [intro] ncGTW is an R package developed as a plug-in of xcms, a popular LC-MS data analysis R package: "`ncGTW` is an R package developed as a plug-in of `xcms`, a popular LC-MS data analysis R package"
