distance-matrix-computation-for-samples
Summary
Compute pairwise distance matrices between metabolomic samples to quantify dissimilarity and enable downstream clustering and visualization. This is a foundational step in sample separation workflows where hierarchical or other clustering methods require inter-sample distances as input.
When to use
After batch effect removal and data integration, when you have a feature-by-sample matrix (finalData) and wish to separate and visualize sample groups by their metabolomic profiles using clustering methods such as hierarchical clustering analysis (HCA). Use this skill when the input is a normalized feature matrix and you need to compute distances before applying Sample_Separation() with method='HCA' or similar clustering.
When NOT to use
- Input data has not been batch-corrected or integrated — remove batch effects first
- Feature matrix contains missing values or negative intensities without prior imputation or transformation
- Sample count is very small (n < 3) such that distance computation or clustering is uninformative
Inputs
- finalData: feature-by-sample matrix of metabolite intensities (rows = features/m/z, columns = samples)
- finalLabel: vector of sample group labels or class assignments
Outputs
- Distance matrix: symmetric square matrix of pairwise inter-sample distances
- Hierarchical clustering dendrogram: tree visualization of sample groupings
- Cluster assignments: vector assigning each sample to one of k clusters
How to apply
Extract the finalized feature-by-sample matrix (finalData) and corresponding sample group labels (finalLabel) from integrated and batch-corrected metabolomic data. Compute pairwise distances between all samples using an appropriate distance metric (e.g. Euclidean, which is standard for hierarchical clustering in metabolomics). The distance matrix becomes the input to hierarchical clustering algorithms, which then produce dendrograms and cluster assignments. Verify that the distance matrix is symmetric, has zero diagonal, and that all entries are non-negative. Choose the distance metric based on data characteristics: Euclidean distance is typical for continuous metabolite intensities. Pass the resulting distance matrix to clustering functions (e.g., hclust in R via factoextra) to generate sample dendrograms and separate samples into k clusters (e.g., k=2 for two-group comparisons).
Related tools
- factoextra (Distance matrix computation and hierarchical clustering visualization for sample separation)
- ggplot2 (Visualization of dendrograms and clustering results)
- LargeMetabo (Wrapper function Sample_Separation() that orchestrates distance computation, clustering, and dendrogram generation) — https://github.com/LargeMetabo/LargeMetabo
Examples
Sample_Separation(finalData, finalLabel, clusters = 2, method = "HCA")
Evaluation signals
- Distance matrix is symmetric (dist[i,j] == dist[j,i]) and has zero diagonal
- All pairwise distances are non-negative and bounded within expected range for the metric
- Resulting dendrogram clearly separates samples by group label; intra-group distances are smaller than inter-group distances
- Cluster assignments (from k=2 or chosen k) match or closely correlate with biological group labels (finalLabel)
- Dendrogram height and branch structure reflect biological relatedness: samples from the same group cluster together before samples from different groups merge
Limitations
- Distance computation is sensitive to feature scaling; unnormalized or differently-scaled features can dominate the metric
- Euclidean distance assumes linear relationships and can be affected by extreme outliers or highly skewed metabolite distributions
- Hierarchical clustering dendrogram topology can vary with linkage method (single, complete, average, Ward); choose linkage appropriate for metabolomic data structure
- Large feature matrices (thousands of features) can lead to high-dimensional distance artifacts; feature selection or dimensionality reduction may be necessary before distance computation
Evidence
- [other] Research question and workflow context: "How does the Sample_Separation function with hierarchical clustering (HCA) method and k=2 clusters operate to visualize the clustering and separation of different sample groups in metabolomic data?"
- [readme] Function signature and parameters: "Sample_Separation(finalData, finalLabel, clusters = 2, method = "HCA")"
- [readme] Purpose of sample separation workflow: "There are four sample separation methods for visualizing the clustering and separation of different samples."
- [readme] Input data format specification: "Each dataset (csv file) contains five essential columns providing the information of mass, retention time, intensity, isotope and adduct. The first two columns provide the mass and retention time,"
- [other] Output dendrogram generation: "Generate hierarchical dendrogram visualization showing sample groupings and cluster boundaries."
1---2name: distance-matrix-computation-for-samples3description: Use when after batch effect removal and data integration, when you have a feature-by-sample matrix (finalData) and wish to separate and visualize sample groups by their metabolomic profiles using clustering methods such as hierarchical clustering analysis (HCA).4license: CC-BY-4.05---67# distance-matrix-computation-for-samples89## Summary1011Compute pairwise distance matrices between metabolomic samples to quantify dissimilarity and enable downstream clustering and visualization. This is a foundational step in sample separation workflows where hierarchical or other clustering methods require inter-sample distances as input.1213## When to use1415After batch effect removal and data integration, when you have a feature-by-sample matrix (finalData) and wish to separate and visualize sample groups by their metabolomic profiles using clustering methods such as hierarchical clustering analysis (HCA). Use this skill when the input is a normalized feature matrix and you need to compute distances before applying Sample_Separation() with method='HCA' or similar clustering.1617## When NOT to use1819- Input data has not been batch-corrected or integrated — remove batch effects first20- Feature matrix contains missing values or negative intensities without prior imputation or transformation21- Sample count is very small (n < 3) such that distance computation or clustering is uninformative2223## Inputs2425- finalData: feature-by-sample matrix of metabolite intensities (rows = features/m/z, columns = samples)26- finalLabel: vector of sample group labels or class assignments2728## Outputs2930- Distance matrix: symmetric square matrix of pairwise inter-sample distances31- Hierarchical clustering dendrogram: tree visualization of sample groupings32- Cluster assignments: vector assigning each sample to one of k clusters3334## How to apply3536Extract the finalized feature-by-sample matrix (finalData) and corresponding sample group labels (finalLabel) from integrated and batch-corrected metabolomic data. Compute pairwise distances between all samples using an appropriate distance metric (e.g. Euclidean, which is standard for hierarchical clustering in metabolomics). The distance matrix becomes the input to hierarchical clustering algorithms, which then produce dendrograms and cluster assignments. Verify that the distance matrix is symmetric, has zero diagonal, and that all entries are non-negative. Choose the distance metric based on data characteristics: Euclidean distance is typical for continuous metabolite intensities. Pass the resulting distance matrix to clustering functions (e.g., hclust in R via factoextra) to generate sample dendrograms and separate samples into k clusters (e.g., k=2 for two-group comparisons).3738## Related tools3940- **factoextra** (Distance matrix computation and hierarchical clustering visualization for sample separation)41- **ggplot2** (Visualization of dendrograms and clustering results)42- **LargeMetabo** (Wrapper function Sample_Separation() that orchestrates distance computation, clustering, and dendrogram generation) — https://github.com/LargeMetabo/LargeMetabo4344## Examples4546```47Sample_Separation(finalData, finalLabel, clusters = 2, method = "HCA")48```4950## Evaluation signals5152- Distance matrix is symmetric (dist[i,j] == dist[j,i]) and has zero diagonal53- All pairwise distances are non-negative and bounded within expected range for the metric54- Resulting dendrogram clearly separates samples by group label; intra-group distances are smaller than inter-group distances55- Cluster assignments (from k=2 or chosen k) match or closely correlate with biological group labels (finalLabel)56- Dendrogram height and branch structure reflect biological relatedness: samples from the same group cluster together before samples from different groups merge5758## Limitations5960- Distance computation is sensitive to feature scaling; unnormalized or differently-scaled features can dominate the metric61- Euclidean distance assumes linear relationships and can be affected by extreme outliers or highly skewed metabolite distributions62- Hierarchical clustering dendrogram topology can vary with linkage method (single, complete, average, Ward); choose linkage appropriate for metabolomic data structure63- Large feature matrices (thousands of features) can lead to high-dimensional distance artifacts; feature selection or dimensionality reduction may be necessary before distance computation6465## Evidence6667- [other] Research question and workflow context: "How does the Sample_Separation function with hierarchical clustering (HCA) method and k=2 clusters operate to visualize the clustering and separation of different sample groups in metabolomic data?"68- [readme] Function signature and parameters: "Sample_Separation(finalData, finalLabel, clusters = 2, method = "HCA")"69- [readme] Purpose of sample separation workflow: "There are four sample separation methods for visualizing the clustering and separation of different samples."70- [readme] Input data format specification: "Each dataset (csv file) contains five essential columns providing the information of mass, retention time, intensity, isotope and adduct. The first two columns provide the mass and retention time,"71- [other] Output dendrogram generation: "Generate hierarchical dendrogram visualization showing sample groupings and cluster boundaries."
