HolobiomicsLab metabolite-sample-clustering-visualization
Summary
Visualize the hierarchical clustering and separation of metabolomic samples using the Sample_Separation function with HCA (hierarchical clustering analysis) method to group samples by their metabolomic profiles and identify sample separation patterns.
When to use
When you have a feature-by-sample metabolomic matrix (finalData) and corresponding sample group labels (finalLabel) and need to visualize how samples cluster together and separate by group using hierarchical clustering; typically after data integration and batch effect removal steps to assess whether sample groups are sufficiently separated in metabolomic space.
When NOT to use
- When your data has already been reduced to pre-computed distances or dissimilarity matrices; Sample_Separation requires raw feature counts or intensities to compute hierarchical clustering de novo.
- When you have fewer than 2 samples; hierarchical clustering requires sufficient sample size to produce meaningful dendrograms.
- When sample group labels are unknown or unavailable; finalLabel is required to evaluate clustering quality against known group structure.
Inputs
- finalData: feature-by-sample numeric matrix (metabolomic features as rows, samples as columns)
- finalLabel: character or factor vector of sample group labels (length equal to number of samples/columns)
Outputs
- Hierarchical dendrogram visualization showing sample groupings and cluster boundaries
- Sample-to-cluster assignments for each sample
- Hierarchical clustering tree object
How to apply
Load the feature matrix (finalData) and sample group label vector (finalLabel) into R. Call Sample_Separation() with method='HCA' to perform hierarchical clustering analysis and clusters=2 (or other k value) to specify the number of sample clusters. The function performs hierarchical clustering on samples based on their metabolomic profiles and generates a dendrogram visualization. Extract and record cluster assignments for each sample from the output. Evaluate separation quality by examining the dendrogram structure: well-separated groups should show distinct cluster branches with clear boundaries between sample groups.
Related tools
- LargeMetabo (R package containing Sample_Separation() function for hierarchical clustering visualization of metabolomic samples) — https://github.com/LargeMetabo/LargeMetabo
- factoextra (R package used in background processes for cluster visualization and extraction of hierarchical clustering results)
- ggplot2 (R package used for enhanced visualization and dendrogram plotting)
Examples
Sample_Separation(finalData, finalLabel, clusters = 2, method = "HCA")
Evaluation signals
- Dendrogram visually shows distinct separation between known sample groups with minimal inter-group branches
- Cluster assignments recovered from the dendrogram match or closely align with the input finalLabel sample group labels
- All samples are successfully assigned to one of the k specified clusters with no missing or NA assignments
- Dendrogram height/distances between clusters are proportional to metabolomic differences; samples within the same group show shorter branch distances than samples from different groups
Limitations
- HCA dendrogram interpretation can be subjective; different linkage methods may produce different tree topologies and cluster assignments.
- Hierarchical clustering is sensitive to outlier samples which may distort branch structure and mislead group separation assessment.
- Performance and visualization clarity may degrade with very large sample sizes (hundreds to thousands of samples); tree becomes dense and difficult to interpret.
Evidence
- [other] Research question and method from task card: "Sample_Separation() function accepts finalData (feature matrix), finalLabel (sample group labels), clusters parameter (set to 2), and method parameter (set to 'HCA' for hierarchical clustering"
- [other] Workflow steps from task card: "Execute Sample_Separation() function with method='HCA' and clusters=2 parameters to perform hierarchical clustering on samples. Extract and record cluster assignments for each sample. Generate"
- [readme] README workflow description: "There are four sample separation methods for visualizing the clustering and separation of different samples. In the LargeMetabo package, the four methods are provided for sample separation."
- [readme] README example invocation: "finalData <- MarkerData$finalData; finalLabel <- MarkerData$finalLabel; Sample_Separation(finalData, finalLabel, clusters = 2, method = "HCA")"
- [readme] Data preparation context from README: "Before data integration, the csv files containing a feature-by-sample matrix should be prepared in advance. Each dataset (csv file) contains five essential columns providing the information of mass,"