m/z-based-feature-grouping
Summary
Refine and merge putative metabolic features across multiple samples by clustering on mass-to-charge ratio (m/z) after retention-time-based clustering. This step consolidates features with matching m/z values into unified entries for a multi-sample aligned feature table.
When to use
Apply this skill after retention-time clustering has grouped features from multiple LC-MS samples, when you need to refine feature assignments by enforcing m/z consistency and eliminate duplicate or near-duplicate features with the same mass but potentially misaligned retention times.
When NOT to use
- Do not use this skill on already-aligned multi-sample feature tables; m/z clustering is meant to refine per-sample or RT-pre-clustered data, not re-cluster aligned output.
- Do not apply m/z clustering in isolation without prior retention-time-based clustering; the two-stage approach is designed to work sequentially for robust alignment.
- Do not use this skill on single-sample feature extracts; m/z-based grouping is only meaningful when consolidating features across multiple samples.
Inputs
- retention-time-clustered feature groups (intermediate output from RT clustering)
- extracted feature tables from individual samples (MS1 peak picking, MS2 recognition, or targeted list output)
Outputs
- unified aligned feature table with merged entries
- alignment statistics (number of aligned features, sample-to-feature coverage matrix, quality metrics)
How to apply
Following retention-time-based clustering, apply m/z-based clustering to refine the grouping and merge features with matching mass-to-charge ratios within the specified m/z tolerance (e.g., 10 ppm, controlled by the mz.tol or similar parameter). The JPA alignment workflow performs this as a secondary refinement step: features already grouped by retention time are re-examined for m/z consistency, and features falling within the m/z tolerance window are merged into single aligned features. This two-stage approach (RT-first, then m/z) reduces false positives from retention-time drift while ensuring mass accuracy. Generate alignment statistics post-clustering to report the number of aligned features and sample-to-feature coverage metrics, which serve as validation that the procedure produced a coherent feature table.
Related tools
- JPA (Performs the m/z-based clustering refinement step as Part 5 of its alignment workflow after RT clustering) — https://github.com/HuanLab/JPA.git
- XCMS (Embedded within JPA to provide underlying peak picking and feature extraction prior to alignment and clustering)
Evaluation signals
- Verify that all features within the specified m/z tolerance window have been merged into single aligned entries in the output table.
- Check the sample-to-feature coverage matrix to confirm each aligned feature is present across expected samples with no spurious duplicates.
- Confirm that the number of aligned features is less than or equal to the sum of per-sample feature counts, indicating successful consolidation.
- Validate that m/z values of merged features fall within the specified tolerance (e.g., max pairwise m/z difference ≤ 10 ppm) and are representative of cluster centers.
- Review alignment quality metrics (e.g., number of features aligned across all samples vs. singletons) to assess the robustness of the clustering.
Limitations
- M/z tolerance must be set appropriately for the instrument's mass accuracy; overly tight tolerances may prevent valid feature merging, while loose tolerances may incorrectly merge distinct metabolites.
- The two-stage clustering approach (RT then m/z) assumes that retention-time pre-clustering is robust; poor RT clustering will propagate errors into the m/z refinement step.
- High m/z features or isobaric compounds within the tolerance window may be incorrectly merged, leading to loss of information about distinct metabolites with similar mass.
- The procedure does not account for adduct variants or in-source fragmentation; those must be handled by downstream annotation modules (e.g., CAMERA).
Evidence
- [other] Apply retention time-based clustering to group putatively identical features across samples within specified tolerance windows. Apply m/z-based clustering to refine grouping and merge features with matching mass-to-charge ratios.: "Apply retention time-based clustering to group putatively identical features across samples within specified tolerance windows. 3. Apply m/z-based clustering to refine grouping and merge features"
- [other] Generate alignment statistics including number of aligned features, sample-to-feature coverage matrix, and alignment quality metrics.: "Generate alignment statistics including number of aligned features, sample-to-feature coverage matrix, and alignment quality metrics."
- [other] JPA alignment workflow step (Part 5: Alignment) operates after feature extraction and before annotation.: "JPA includes an alignment workflow step (Part 5: Alignment) as part of its comprehensive metabolomics data processing pipeline that operates after feature extraction and before annotation."
- [readme] for multi-sample analysis, sample alignment is performed after feature extraction. It will be discussed in section 5.: "for multi-sample analysis, sample alignment is performed after feature extraction. It will be discussed in section 5."
1---2name: m-z-based-feature-grouping3description: Use when after retention-time clustering has grouped features from multiple LC-MS samples, when you need to refine feature assignments by enforcing m/z consistency and eliminate duplicate or near-duplicate features with the same mass but potentially misaligned retention times.4license: CC-BY-4.05---67# m/z-based-feature-grouping89## Summary1011Refine and merge putative metabolic features across multiple samples by clustering on mass-to-charge ratio (m/z) after retention-time-based clustering. This step consolidates features with matching m/z values into unified entries for a multi-sample aligned feature table.1213## When to use1415Apply this skill after retention-time clustering has grouped features from multiple LC-MS samples, when you need to refine feature assignments by enforcing m/z consistency and eliminate duplicate or near-duplicate features with the same mass but potentially misaligned retention times.1617## When NOT to use1819- Do not use this skill on already-aligned multi-sample feature tables; m/z clustering is meant to refine per-sample or RT-pre-clustered data, not re-cluster aligned output.20- Do not apply m/z clustering in isolation without prior retention-time-based clustering; the two-stage approach is designed to work sequentially for robust alignment.21- Do not use this skill on single-sample feature extracts; m/z-based grouping is only meaningful when consolidating features across multiple samples.2223## Inputs2425- retention-time-clustered feature groups (intermediate output from RT clustering)26- extracted feature tables from individual samples (MS1 peak picking, MS2 recognition, or targeted list output)2728## Outputs2930- unified aligned feature table with merged entries31- alignment statistics (number of aligned features, sample-to-feature coverage matrix, quality metrics)3233## How to apply3435Following retention-time-based clustering, apply m/z-based clustering to refine the grouping and merge features with matching mass-to-charge ratios within the specified m/z tolerance (e.g., 10 ppm, controlled by the mz.tol or similar parameter). The JPA alignment workflow performs this as a secondary refinement step: features already grouped by retention time are re-examined for m/z consistency, and features falling within the m/z tolerance window are merged into single aligned features. This two-stage approach (RT-first, then m/z) reduces false positives from retention-time drift while ensuring mass accuracy. Generate alignment statistics post-clustering to report the number of aligned features and sample-to-feature coverage metrics, which serve as validation that the procedure produced a coherent feature table.3637## Related tools3839- **JPA** (Performs the m/z-based clustering refinement step as Part 5 of its alignment workflow after RT clustering) — https://github.com/HuanLab/JPA.git40- **XCMS** (Embedded within JPA to provide underlying peak picking and feature extraction prior to alignment and clustering)4142## Evaluation signals4344- Verify that all features within the specified m/z tolerance window have been merged into single aligned entries in the output table.45- Check the sample-to-feature coverage matrix to confirm each aligned feature is present across expected samples with no spurious duplicates.46- Confirm that the number of aligned features is less than or equal to the sum of per-sample feature counts, indicating successful consolidation.47- Validate that m/z values of merged features fall within the specified tolerance (e.g., max pairwise m/z difference ≤ 10 ppm) and are representative of cluster centers.48- Review alignment quality metrics (e.g., number of features aligned across all samples vs. singletons) to assess the robustness of the clustering.4950## Limitations5152- M/z tolerance must be set appropriately for the instrument's mass accuracy; overly tight tolerances may prevent valid feature merging, while loose tolerances may incorrectly merge distinct metabolites.53- The two-stage clustering approach (RT then m/z) assumes that retention-time pre-clustering is robust; poor RT clustering will propagate errors into the m/z refinement step.54- High m/z features or isobaric compounds within the tolerance window may be incorrectly merged, leading to loss of information about distinct metabolites with similar mass.55- The procedure does not account for adduct variants or in-source fragmentation; those must be handled by downstream annotation modules (e.g., CAMERA).5657## Evidence5859- [other] Apply retention time-based clustering to group putatively identical features across samples within specified tolerance windows. Apply m/z-based clustering to refine grouping and merge features with matching mass-to-charge ratios.: "Apply retention time-based clustering to group putatively identical features across samples within specified tolerance windows. 3. Apply m/z-based clustering to refine grouping and merge features"60- [other] Generate alignment statistics including number of aligned features, sample-to-feature coverage matrix, and alignment quality metrics.: "Generate alignment statistics including number of aligned features, sample-to-feature coverage matrix, and alignment quality metrics."61- [other] JPA alignment workflow step (Part 5: Alignment) operates after feature extraction and before annotation.: "JPA includes an alignment workflow step (Part 5: Alignment) as part of its comprehensive metabolomics data processing pipeline that operates after feature extraction and before annotation."62- [readme] for multi-sample analysis, sample alignment is performed after feature extraction. It will be discussed in section 5.: "for multi-sample analysis, sample alignment is performed after feature extraction. It will be discussed in section 5."
HolobiomicsLab 