feature-abundance-correlation-analysis
Summary
Refine retention-time-based LC-MS feature groups by partitioning them into sub-groups based on pairwise abundance correlation across samples using a user-defined threshold. This skill identifies which co-eluting features (same m/z and retention time window) actually co-vary in intensity, separating true co-ionizations from instrumental or chemical artifacts.
When to use
After initial retention-time-based feature grouping (e.g., using SimilarRtimeParam with a 20-second window), apply this skill when you need to split large feature groups into more homogeneous sub-groups. Use it when abundance patterns diverge within a retention-time window—for example, when 159 features initially group into 94 retention-time groups, but some of those groups contain features with weak or absent correlation (e.g., features within FG.040 showing correlation strengths below a 0.7 threshold between certain feature pairs).
When NOT to use
- Input is already a final compound-level feature table (e.g., post-annotation, merged by chemical identity); abundance correlation grouping is a pre-annotation refinement step.
- Sample sizes are < 3 (correlation statistics are unreliable with insufficient degrees of freedom).
- Abundance data has not been normalized or processed for missing values; gap-filling should precede this step.
Inputs
- Retention-time-based feature groups (output from SimilarRtimeParam)
- Feature abundance matrix (intensity values across samples)
- Sample metadata or grouping information
Outputs
- Sub-grouped feature assignments (refined feature groups indexed by FG.XXX notation)
- Count of total sub-groups produced
- Pairwise correlation matrix for each group
- Correlation heatmap visualization
How to apply
Load retention-time-based feature groups output from SimilarRtimeParam. Apply the groupFeatures() function from MsFeatures with AbundanceSimilarityParam, setting threshold=0.7 (or other domain-justified cutoff), transform=log2 (to handle skewed abundance distributions), and filled=TRUE (to include gap-filled intensities for samples where peaks were not detected). For each retention-time group, compute pairwise Pearson or Spearman correlations of log2-transformed abundances across all samples. Features with pairwise correlation exceeding the threshold are retained in the same sub-group; those falling below it spawn separate sub-groups. Extract sub-group assignments and generate a heatmap (using pheatmap) showing pairwise correlations within each group to validate sub-grouping coherence and identify which feature pairs drive the partitioning.
Related tools
- xcms (Provides preprocessing and retention-time grouping infrastructure; groupFeatures() dispatches to MsFeatures for abundance-based refinement.) — https://github.com/sneumann/xcms
- MsFeatures (Implements AbundanceSimilarityParam and groupFeatures() core logic for abundance correlation-based feature partitioning.)
- pheatmap (Visualizes pairwise correlation matrices within and across feature sub-groups to validate grouping coherence.)
Examples
groupFeatures(fg_rtime, AbundanceSimilarityParam(threshold=0.7, transform="log2", filled=TRUE))
Evaluation signals
- Verify output sub-group count is lower or equal to the input retention-time group count (no expansion, only refinement).
- Check that all pairwise correlations within a sub-group are ≥ the threshold (0.7); correlations between features in different sub-groups should be < threshold.
- Confirm gap-filled abundances (filled=TRUE) do not artificially inflate correlation; compare with filled=FALSE to assess sensitivity.
- Inspect the correlation heatmap visually: sub-groups should form distinct blocks with high within-block correlation and low between-block correlation.
- Validate that feature pairs explicitly mentioned in findings (e.g., FT273–FT274 and FT143–FT273 in FG.040) match the heatmap and sub-group assignments.
Limitations
- Not all features within a retention-time group will show pairwise correlation above the threshold; some weaker correlations are expected and drive further sub-partitioning.
- Log2 transformation assumes abundance values are positive; zero or missing intensities require prior gap-filling or pseudocount addition.
- Correlation-based grouping is sensitive to outlier samples; quality control and potential outlier removal should precede this step.
- Threshold selection (e.g., 0.7) is user-dependent and should be justified by domain knowledge or exploratory analysis; no universal cutoff is recommended in the article.
Evidence
- [other] After applying AbundanceSimilarityParam(threshold=0.7, transform=log2, filled=TRUE), the 159 features were grouped into 94 feature groups.: "After applying AbundanceSimilarityParam(threshold=0.7, transform=log2, filled=TRUE), the 159 features were grouped into 94 feature groups."
- [other] Within FG.040, pairwise correlation analysis reveals that not all features show correlation above the 0.7 threshold—for example, clear correlation is present between FT273 and FT274, and between FT143 and FT273, but other features within this retention time group show weaker correlations.: "Within FG.040, pairwise correlation analysis reveals that not all features show correlation above the 0.7 threshold—for example, clear correlation is present between FT273 and FT274, and between"
- [intro] AbundanceSimilarityParam: perform a feature grouping based on correlation of feature abundances (values) across samples.: "AbundanceSimilarityParam: perform a feature grouping based on correlation of feature abundances (values) across samples."
- [intro] The abundance of features (ions) of the same compound should have a similar pattern across samples.: "The abundance of features (ions) of the same compound should have a similar pattern across samples."
- [intro] Many of the larger retention time-based feature groups have been splitted into two or more sub-groups based on abundance correlation-based refinement.: "Many of the larger retention time-based feature groups have been splitted into two or more sub-groups based on abundance correlation-based refinement."
- [intro] for samples in which no chromatographic peak for a feature was detected, all signal from the m/z - retention time range defined based on the detected chromatographic peaks was integrated.: "for samples in which no chromatographic peak for a feature was detected, all signal from the m/z - retention time range defined based on the detected chromatographic peaks was integrated."
1---2name: feature-abundance-correlation-analysis3description: Use when after initial retention-time-based feature grouping (e.g., using SimilarRtimeParam with a 20-second window), apply this skill when you need to split large feature groups into more homogeneous sub-groups.4license: CC-BY-4.05---67# feature-abundance-correlation-analysis89## Summary1011Refine retention-time-based LC-MS feature groups by partitioning them into sub-groups based on pairwise abundance correlation across samples using a user-defined threshold. This skill identifies which co-eluting features (same m/z and retention time window) actually co-vary in intensity, separating true co-ionizations from instrumental or chemical artifacts.1213## When to use1415After initial retention-time-based feature grouping (e.g., using SimilarRtimeParam with a 20-second window), apply this skill when you need to split large feature groups into more homogeneous sub-groups. Use it when abundance patterns diverge within a retention-time window—for example, when 159 features initially group into 94 retention-time groups, but some of those groups contain features with weak or absent correlation (e.g., features within FG.040 showing correlation strengths below a 0.7 threshold between certain feature pairs).1617## When NOT to use1819- Input is already a final compound-level feature table (e.g., post-annotation, merged by chemical identity); abundance correlation grouping is a pre-annotation refinement step.20- Sample sizes are < 3 (correlation statistics are unreliable with insufficient degrees of freedom).21- Abundance data has not been normalized or processed for missing values; gap-filling should precede this step.2223## Inputs2425- Retention-time-based feature groups (output from SimilarRtimeParam)26- Feature abundance matrix (intensity values across samples)27- Sample metadata or grouping information2829## Outputs3031- Sub-grouped feature assignments (refined feature groups indexed by FG.XXX notation)32- Count of total sub-groups produced33- Pairwise correlation matrix for each group34- Correlation heatmap visualization3536## How to apply3738Load retention-time-based feature groups output from SimilarRtimeParam. Apply the groupFeatures() function from MsFeatures with AbundanceSimilarityParam, setting threshold=0.7 (or other domain-justified cutoff), transform=log2 (to handle skewed abundance distributions), and filled=TRUE (to include gap-filled intensities for samples where peaks were not detected). For each retention-time group, compute pairwise Pearson or Spearman correlations of log2-transformed abundances across all samples. Features with pairwise correlation exceeding the threshold are retained in the same sub-group; those falling below it spawn separate sub-groups. Extract sub-group assignments and generate a heatmap (using pheatmap) showing pairwise correlations within each group to validate sub-grouping coherence and identify which feature pairs drive the partitioning.3940## Related tools4142- **xcms** (Provides preprocessing and retention-time grouping infrastructure; groupFeatures() dispatches to MsFeatures for abundance-based refinement.) — https://github.com/sneumann/xcms43- **MsFeatures** (Implements AbundanceSimilarityParam and groupFeatures() core logic for abundance correlation-based feature partitioning.)44- **pheatmap** (Visualizes pairwise correlation matrices within and across feature sub-groups to validate grouping coherence.)4546## Examples4748```49groupFeatures(fg_rtime, AbundanceSimilarityParam(threshold=0.7, transform="log2", filled=TRUE))50```5152## Evaluation signals5354- Verify output sub-group count is lower or equal to the input retention-time group count (no expansion, only refinement).55- Check that all pairwise correlations within a sub-group are ≥ the threshold (0.7); correlations between features in different sub-groups should be < threshold.56- Confirm gap-filled abundances (filled=TRUE) do not artificially inflate correlation; compare with filled=FALSE to assess sensitivity.57- Inspect the correlation heatmap visually: sub-groups should form distinct blocks with high within-block correlation and low between-block correlation.58- Validate that feature pairs explicitly mentioned in findings (e.g., FT273–FT274 and FT143–FT273 in FG.040) match the heatmap and sub-group assignments.5960## Limitations6162- Not all features within a retention-time group will show pairwise correlation above the threshold; some weaker correlations are expected and drive further sub-partitioning.63- Log2 transformation assumes abundance values are positive; zero or missing intensities require prior gap-filling or pseudocount addition.64- Correlation-based grouping is sensitive to outlier samples; quality control and potential outlier removal should precede this step.65- Threshold selection (e.g., 0.7) is user-dependent and should be justified by domain knowledge or exploratory analysis; no universal cutoff is recommended in the article.6667## Evidence6869- [other] After applying AbundanceSimilarityParam(threshold=0.7, transform=log2, filled=TRUE), the 159 features were grouped into 94 feature groups.: "After applying AbundanceSimilarityParam(threshold=0.7, transform=log2, filled=TRUE), the 159 features were grouped into 94 feature groups."70- [other] Within FG.040, pairwise correlation analysis reveals that not all features show correlation above the 0.7 threshold—for example, clear correlation is present between FT273 and FT274, and between FT143 and FT273, but other features within this retention time group show weaker correlations.: "Within FG.040, pairwise correlation analysis reveals that not all features show correlation above the 0.7 threshold—for example, clear correlation is present between FT273 and FT274, and between"71- [intro] AbundanceSimilarityParam: perform a feature grouping based on correlation of feature abundances (values) across samples.: "AbundanceSimilarityParam: perform a feature grouping based on correlation of feature abundances (values) across samples."72- [intro] The abundance of features (ions) of the same compound should have a similar pattern across samples.: "The abundance of features (ions) of the same compound should have a similar pattern across samples."73- [intro] Many of the larger retention time-based feature groups have been splitted into two or more sub-groups based on abundance correlation-based refinement.: "Many of the larger retention time-based feature groups have been splitted into two or more sub-groups based on abundance correlation-based refinement."74- [intro] for samples in which no chromatographic peak for a feature was detected, all signal from the m/z - retention time range defined based on the detected chromatographic peaks was integrated.: "for samples in which no chromatographic peak for a feature was detected, all signal from the m/z - retention time range defined based on the detected chromatographic peaks was integrated."
HolobiomicsLab 