bandwidth-parameter-effect-comparison
Summary
Compare XCMS grouping results produced with different bandwidth (bw) parameters to detect misaligned feature groups in retention time. This skill identifies features that fail to align consistently across parameter settings, revealing systematic alignment failures in LC-MS data.
When to use
Apply this skill when you suspect XCMS grouping contains misaligned features due to suboptimal parameter settings or insufficient samples. Use it as a prerequisite diagnostic before attempting realignment: generate two XCMS grouping results with contrasting bw values (one large, capturing expected maximal RT drift; one small, matching RT sampling resolution) and compare them to identify inconsistent feature groupings.
When NOT to use
- Input XCMS results were generated with identical bandwidth parameters—comparison requires contrasting parameter sets to reveal divergent groupings.
- Peak detection ppm value is unknown or unavailable—the ppm parameter must match the original peak detection tolerance for valid p-value estimation.
- You are seeking to align individual samples rather than identify systematic feature grouping errors—this skill diagnoses grouping-level misalignment, not sample-level warping.
Inputs
- XCMS grouping result object (large bandwidth parameter set)
- XCMS grouping result object (small bandwidth parameter set)
- ppm tolerance value (numeric, matching peak detection ppm)
Outputs
- excluGroups table (data frame containing detected misaligned feature groups with p-values and sample subset information)
How to apply
Load two XCMS grouping results into R—one generated with a large bw parameter (representing expected maximal retention time drift across your sample set) and one with a small bw parameter (matching your peak detection resolution). Call misalignDetect() from the ncGTW package, providing both grouping results and a ppm tolerance parameter that matches your peak detection ppm threshold. The function estimates p-values using the high-resolution (small bw) result as the null hypothesis of accurate alignment, then identifies features with sufficiently small p-values and disjoint sample subsets. Extract the excluGroups table, which lists feature groups detected as misaligned. This comparative approach exploits the principle that accurate alignment should produce consistent groupings regardless of parameter resolution; divergence signals systematic misalignment.
Related tools
- ncGTW (Executes misalignDetect() function to compare grouping results and identify misaligned feature groups) — https://github.com/ChiungTingWu/ncGTW
- xcms (Generates the two grouping results (with different bw parameters) that serve as inputs to the comparison)
- R (Execution environment for ncGTW and data object manipulation)
Examples
misalign_result <- misalignDetect(xcms_grouping_large_bw, xcms_grouping_small_bw, ppm = 5); excluGroups <- misalign_result@excluGroups
Evaluation signals
- excluGroups table is non-empty and contains feature groups with p-values below a significance threshold, indicating detected misalignments.
- Detected misaligned features show disjoint sample subsets—the affected samples differ across misaligned groups, demonstrating systematic rather than random divergence.
- Features in the excluGroups table can be matched to neighboring features in the low-resolution grouping result, confirming they represent real grouping inconsistencies.
- The excluGroups table has expected row/column structure matching ncGTW output schema (feature group identifiers, p-values, sample information).
- Re-running misalignDetect() with the same inputs reproduces identical excluGroups, confirming reproducibility.
Limitations
- The skill requires careful selection of the two bw parameters: the large bw must be set to expected maximal RT drift across all samples, and the small bw to RT sampling resolution. Inappropriate parameter choice may fail to reveal actual misalignments.
- Detection accuracy depends on sufficient samples and adequate RT drift structure; datasets with fewer samples or uniform RT drift may not produce reliable misalignment signals.
- The method assumes the high-resolution (small bw) grouping is closer to ground truth; if both groupings are substantially incorrect, the comparison may fail to identify true misalignments.
- No changelog is available, limiting reproducibility tracking across ncGTW versions.
Evidence
- [other] misalignDetect() parameter requirements: "misalignDetect() requires two XCMS grouping results with different bw values (one set to expected maximal RT drift, one to RT sampling resolution) and a ppm parameter matching the peak detection ppm"
- [readme] misalignment detection rationale: "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"
- [intro] XCMS misalignment cause: "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."
- [other] output specification: "Extract and return the excluGroups table containing the detected misaligned feature groups."
1---2name: bandwidth-parameter-effect-comparison3description: Use when you suspect XCMS grouping contains misaligned features due to suboptimal parameter settings or insufficient samples.4license: CC-BY-4.05---67# bandwidth-parameter-effect-comparison89## Summary1011Compare XCMS grouping results produced with different bandwidth (bw) parameters to detect misaligned feature groups in retention time. This skill identifies features that fail to align consistently across parameter settings, revealing systematic alignment failures in LC-MS data.1213## When to use1415Apply this skill when you suspect XCMS grouping contains misaligned features due to suboptimal parameter settings or insufficient samples. Use it as a prerequisite diagnostic before attempting realignment: generate two XCMS grouping results with contrasting bw values (one large, capturing expected maximal RT drift; one small, matching RT sampling resolution) and compare them to identify inconsistent feature groupings.1617## When NOT to use1819- Input XCMS results were generated with identical bandwidth parameters—comparison requires contrasting parameter sets to reveal divergent groupings.20- Peak detection ppm value is unknown or unavailable—the ppm parameter must match the original peak detection tolerance for valid p-value estimation.21- You are seeking to align individual samples rather than identify systematic feature grouping errors—this skill diagnoses grouping-level misalignment, not sample-level warping.2223## Inputs2425- XCMS grouping result object (large bandwidth parameter set)26- XCMS grouping result object (small bandwidth parameter set)27- ppm tolerance value (numeric, matching peak detection ppm)2829## Outputs3031- excluGroups table (data frame containing detected misaligned feature groups with p-values and sample subset information)3233## How to apply3435Load two XCMS grouping results into R—one generated with a large bw parameter (representing expected maximal retention time drift across your sample set) and one with a small bw parameter (matching your peak detection resolution). Call misalignDetect() from the ncGTW package, providing both grouping results and a ppm tolerance parameter that matches your peak detection ppm threshold. The function estimates p-values using the high-resolution (small bw) result as the null hypothesis of accurate alignment, then identifies features with sufficiently small p-values and disjoint sample subsets. Extract the excluGroups table, which lists feature groups detected as misaligned. This comparative approach exploits the principle that accurate alignment should produce consistent groupings regardless of parameter resolution; divergence signals systematic misalignment.3637## Related tools3839- **ncGTW** (Executes misalignDetect() function to compare grouping results and identify misaligned feature groups) — https://github.com/ChiungTingWu/ncGTW40- **xcms** (Generates the two grouping results (with different bw parameters) that serve as inputs to the comparison)41- **R** (Execution environment for ncGTW and data object manipulation)4243## Examples4445```46misalign_result <- misalignDetect(xcms_grouping_large_bw, xcms_grouping_small_bw, ppm = 5); excluGroups <- misalign_result@excluGroups47```4849## Evaluation signals5051- excluGroups table is non-empty and contains feature groups with p-values below a significance threshold, indicating detected misalignments.52- Detected misaligned features show disjoint sample subsets—the affected samples differ across misaligned groups, demonstrating systematic rather than random divergence.53- Features in the excluGroups table can be matched to neighboring features in the low-resolution grouping result, confirming they represent real grouping inconsistencies.54- The excluGroups table has expected row/column structure matching ncGTW output schema (feature group identifiers, p-values, sample information).55- Re-running misalignDetect() with the same inputs reproduces identical excluGroups, confirming reproducibility.5657## Limitations5859- The skill requires careful selection of the two bw parameters: the large bw must be set to expected maximal RT drift across all samples, and the small bw to RT sampling resolution. Inappropriate parameter choice may fail to reveal actual misalignments.60- Detection accuracy depends on sufficient samples and adequate RT drift structure; datasets with fewer samples or uniform RT drift may not produce reliable misalignment signals.61- The method assumes the high-resolution (small bw) grouping is closer to ground truth; if both groupings are substantially incorrect, the comparison may fail to identify true misalignments.62- No changelog is available, limiting reproducibility tracking across ncGTW versions.6364## Evidence6566- [other] misalignDetect() parameter requirements: "misalignDetect() requires two XCMS grouping results with different bw values (one set to expected maximal RT drift, one to RT sampling resolution) and a ppm parameter matching the peak detection ppm"67- [readme] misalignment detection rationale: "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"68- [intro] XCMS misalignment cause: "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."69- [other] output specification: "Extract and return the excluGroups table containing the detected misaligned feature groups."
HolobiomicsLab