hierarchical-clustering-plot
Use when building a sample-level hierarchical clustering dendrogram from a bulk expression matrix and sample annotation table, especially for QC, batch inspection, or sample similarity assessment. Trigger keywords: hierarchical clustering, dendrogram, sample QC, batch inspection, sample similarity. NOT for: differential expression testing, gene clustering heatmaps, single-cell clustering workflows.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- hierarchical-clustering-plot
- description
- Use when building a sample-level hierarchical clustering dendrogram from a bulk expression matrix and sample annotation table, especially for QC, batch inspection, or sample similarity assessment. Trigger keywords: hierarchical clustering, dendrogram, sample QC, batch inspection, sample similarity. NOT for: differential expression testing, gene clustering heatmaps, single-cell clustering workflows.
02 资源文件 16
- 其他DESCRIPTION378 B
- 参考文档references/algorithm.md2.5 KB
- 参考文档references/cli-guide.md4.5 KB
- 参考文档references/troubleshooting.md5.4 KB
- 脚本scripts/clustering_functions.R1.2 KB
- 脚本scripts/input_functions.R4.1 KB
- 脚本scripts/logging_utils.R1.0 KB
- 脚本scripts/main.R3.8 KB
- 脚本scripts/output_utils.R1.3 KB
- 脚本scripts/run_analysis.R3.7 KB
- 脚本scripts/runtime_utils.R1.6 KB
- 脚本scripts/validation_utils.R1.8 KB
- 资产文件tests/data/sample_expression_matrix.csv10.2 KB
- 资产文件tests/data/sample_groups.csv653 B
- 其他tests/run_tests.R1.4 KB
- 其他tests/testthat/test-clustering.R6.1 KB
03 SKILL.md 正文
Hierarchical Clustering Plot
When to Use
Use this skill when you need a sample-level hierarchical clustering dendrogram from a bulk expression matrix and a sample annotation table.
- Good fits: sample QC, batch inspection, sample similarity assessment, checking whether annotated sample groups cluster as expected.
- Trigger keywords: hierarchical clustering, dendrogram, sample QC, batch inspection, sample similarity.
- Not for: differential expression testing, gene clustering heatmaps, single-cell clustering workflows.
When to Read External Files
| Situation | File to Read | Purpose |
|---|---|---|
| Need algorithm details | references/algorithm.md |
Distance calculation, linkage rules, and clustering assumptions |
| Need to run analysis or inspect CLI entrypoint behavior | scripts/main.R |
Execute the workflow and inspect argument parsing, defaults, required flags, and sourced modules |
| Need workflow implementation details | scripts/run_analysis.R |
See orchestration order, temp workspace handling, and output generation |
| Need logging or warning behavior | scripts/logging_utils.R |
See standardized console log formatting and memory usage messages |
| Need file or parameter validation details | scripts/validation_utils.R |
See path checks, output-directory checks, and scalar validation |
| Need timeout, temp workspace, or session info behavior | scripts/runtime_utils.R |
See timeout control, temp cleanup, output copying, and session-info export |
| Need expression/group input handling | scripts/input_functions.R |
See CSV loading, sample matching, and label extraction |
| Need clustering logic | scripts/clustering_functions.R |
See distance calculation and hclust() generation |
| Need output-writing logic | scripts/output_utils.R |
See CSV export and PDF rendering |
| Encounter errors, warnings, or unexpected clustering patterns | references/troubleshooting.md |
Common failures, warning follow-up, and interpretation guidance |
| Need CLI examples or common parameter combinations | references/cli-guide.md |
Detailed command patterns for standard, variant, and test runs |
| Need example input files or schema-concrete fixtures | tests/data/ |
Inspect sample CSV layouts for expression and group inputs |
| Need expected output names or artifact formats | ## Output Files and references/cli-guide.md |
Confirm the files the workflow writes and inspect documented example previews |
| Need to run regression tests | tests/run_tests.R |
Execute the automated test suite |
| Need exact test assertions or edge cases | tests/testthat/test-clustering.R |
Inspect validation, reproducibility, and output checks |
Usage
Rscript scripts/main.R \
--input_file ./expression_matrix.csv \
--group_file ./sample_groups.csv \
--output_dir ./output/ \
--distance_method euclidean \
--linkage_method complete \
--label_column batch \
--timeout_seconds 300 \
--seed 42
Arguments
| Short | Long | Type | Default | Description |
|---|---|---|---|---|
-i |
--input_file |
character | required | Expression matrix file (features as rows, samples as columns) |
-g |
--group_file |
character | required | Sample annotation file (first column sample ID, one metadata column for labels) |
-o |
--output_dir |
character | ./output/ |
Output directory |
-d |
--distance_method |
character | euclidean |
Distance metric for dist(): euclidean, maximum, manhattan, canberra, binary, minkowski |
-m |
--linkage_method |
character | complete |
Linkage method for hclust(): complete, single, average, mcquitty, median, centroid, ward.D, ward.D2 |
-l |
--label_column |
character | second column | Column used as dendrogram labels |
-c |
--label_cex |
numeric | 0.8 |
Dendrogram label size, must be > 0 |
-t |
--timeout_seconds |
integer | 300 |
Elapsed time limit in seconds, must be > 0 |
-s |
--seed |
integer | 42 |
Random seed for reproducibility |
Input Format
Expression Matrix (input_file)
Features as rows, samples as columns, CSV format with feature IDs in the first column.
,Sample01,Sample02,Sample03
TSPAN6,1.847876677,1.831755661,3.827625975
TNMD,0.034919984,0.053250385,1.388850793
Requirements:
- The first column contains unique feature IDs.
- All sample columns must be numeric.
- Sample column names must be unique and non-empty.
- At least two matched samples are required.
Sample Annotation (group_file)
CSV with sample IDs in the first column. The second column is used by default for leaf labels unless --label_column is provided.
sample,batch
Sample01,batch1
Sample02,batch2
Sample03,batch1
Requirements:
- Sample IDs must match expression matrix column names exactly.
- The selected label column must exist and contain no empty values.
- The file must contain at least one metadata column in addition to sample IDs.
Output Files
| File | Description |
|---|---|
hierarchical_clustering_plot.pdf |
Sample dendrogram plot |
sample_distance_matrix.csv |
Pairwise sample distance matrix |
clustering_order.csv |
Leaf order shown in the dendrogram |
matched_samples.csv |
Sample-to-label table used for plotting |
session_info.txt |
R session and package version info |
Workflow
Step 1: Validate Input
WHEN checking file or parameter validation, READ: scripts/validation_utils.R
WHEN checking expression/group CSV handling, READ: scripts/input_functions.R
- Check file existence
- Reject empty files before parsing
- Read the expression matrix and sample annotation CSV files
- Validate required columns, unique IDs, and numeric expression values
Step 2: Align Samples
WHEN checking sample matching logic, READ: scripts/input_functions.R
- Match sample IDs between the annotation file and expression matrix
- Reorder matrix columns to the annotation file order
- Select the label column used for plotting
Step 3: Build Hierarchical Clustering
WHEN interpreting distance or linkage behavior, READ: references/algorithm.md
WHEN checking clustering implementation, READ: scripts/clustering_functions.R
- Transpose the expression matrix to sample-by-feature form
- Compute pairwise sample distances with
dist() - Build the dendrogram with
hclust()
Step 4: Save Outputs
WHEN checking output staging and cleanup behavior, READ: scripts/run_analysis.R
WHEN checking PDF/CSV export behavior, READ: scripts/output_utils.R
WHEN checking timeout, session info, or final file copy behavior, READ: scripts/runtime_utils.R
- Stage outputs in a temporary workspace
- Export the pairwise distance matrix
- Export the plotted leaf order
- Render the dendrogram as PDF
- Copy finalized outputs into the requested output directory
Methods
Distance Matrix
Sample distances are computed from the transposed expression matrix using base R dist().
Hierarchical Clustering
The clustering tree is built with base R hclust(). The default linkage method is complete, matching the source analysis script.
Examples
Basic Usage
Rscript scripts/main.R \
-i tests/data/sample_expression_matrix.csv \
-g tests/data/sample_groups.csv \
-o ./output/ \
-t 300
Use Sample IDs as Labels
Rscript scripts/main.R \
-i tests/data/sample_expression_matrix.csv \
-g tests/data/sample_groups.csv \
-o ./output_sample_labels/ \
-l sample
Use Average Linkage
Rscript scripts/main.R \
-i tests/data/sample_expression_matrix.csv \
-g tests/data/sample_groups.csv \
-o ./output_average/ \
-m average
Error Handling
Common Errors
| Error | Cause | Solution | Read More |
|---|---|---|---|
SKILL_DEPENDENCY_MISSING |
Required R package is not installed | Install the missing package and rerun | references/troubleshooting.md#skill_dependency_missing |
SKILL_FILE_NOT_FOUND |
Input file does not exist or output directory could not be created | Check the path and permissions | references/troubleshooting.md#skill_file_not_found |
SKILL_EMPTY_FILE |
Input file is empty | Re-export the CSV and confirm it contains data | references/troubleshooting.md#skill_empty_file |
SKILL_EMPTY_DATA |
CSV parsed successfully but contains no data rows | Confirm the CSV has at least one data row | references/troubleshooting.md#skill_empty_data |
SKILL_PARSE_ERROR |
CSV parsing failed | Check encoding, delimiters, and CSV structure | references/troubleshooting.md#skill_parse_error |
SKILL_MISSING_COLUMNS |
Expected columns or headers are missing | Check CSV headers and metadata columns | references/troubleshooting.md#skill_missing_columns |
SKILL_INVALID_TYPE |
Expression values or parameters have the wrong type | Ensure numeric fields are numeric | references/troubleshooting.md#skill_invalid_type |
SKILL_SAMPLE_MISMATCH |
Sample IDs do not match | Ensure the first column in group_file matches matrix column names |
references/troubleshooting.md#skill_sample_mismatch |
SKILL_INVALID_DATA |
Expression or annotation data is malformed | Check duplicate IDs, missing labels, and numeric values | references/troubleshooting.md#skill_invalid_data |
SKILL_INVALID_PARAMETER |
Unsupported distance, linkage, or label parameter | Use one of the documented parameter values | references/troubleshooting.md#skill_invalid_parameter |
SKILL_TIMEOUT |
Analysis exceeded the time limit | Increase --timeout_seconds and rerun |
references/troubleshooting.md#skill_timeout |
SKILL_PLOT_ERROR |
Plot device failed while writing PDF | Check output directory permissions and rerun | references/troubleshooting.md#skill_plot_error |
SKILL_WRITE_ERROR |
Output or intermediate files could not be written | Check output directory permissions and free disk space | references/troubleshooting.md#skill_write_error |
SKILL_WARNING |
Non-fatal warning occurred during execution | Inspect console warnings and verify output quality | references/troubleshooting.md#skill_warning |
SKILL_MEMORY_WARNING |
Memory usage exceeded the warning threshold | Reduce input size or rerun with more memory | references/troubleshooting.md#skill_memory_warning |
IF error persists, READ: references/troubleshooting.md
Testing
Test with Sample Data
# Check help
Rscript scripts/main.R --help
# Run with sample data
Rscript scripts/main.R \
-i tests/data/sample_expression_matrix.csv \
-g tests/data/sample_groups.csv \
-o ./output/
# Run unit tests (requires testthat and data.table)
Rscript tests/run_tests.R
Validation Commands
# Check main output plot exists
ls -la ./output/hierarchical_clustering_plot.pdf
# Inspect clustering order
wc -l ./output/clustering_order.csv
Implementation Checklist
- [x] CLI parsing with
optparse - [x]
set.seed()for reproducibility - [x] Input validation (file existence, emptiness, types, required columns)
- [x] Try-catch based fatal error handling
- [x] Standardized
SKILL_*error classification - [x] Timeout control with
setTimeLimit() - [x] Standardized console-only logging
- [x] Base R clustering implementation
- [x] Session info recording with
sink() - [x] Temporary workspace cleanup with
on.exit() - [x] Memory usage reporting with
gc() - [x] File reading instructions in SKILL.md
- [x] Modular script structure across
scripts/ - [x] Test template added under
tests/testthat/ - [x] Test data provided
- [x] Error handling with
SKILL_*codes - [x]
get_script_dir()defined before use - [x] Scripts in
scripts/directory - [x] References in
references/directory
Last updated: 2026-04-16 | Version: 1.0.0
04 同仓库更多 Skills
bio-workflows-metabolomics-pipeline
Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC/drift/normalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics/isotope-tracing.
bio-metabolomics-xcms-preprocessing
Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment/XcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave/grouping/alignment parameters. For drift correction and QC/CV filtering execution see metabolomics/normalization-qc; for metabolite identification see metabolomics/metabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics/msdial-preprocessing; for downstream statistics see metabolomics/statistical-analysis.
bio-metabolomics-statistical-analysis
Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA/HCA for QC), permutation-validated PLS-DA/OPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch/Mann-Whitney/ANOVA/LMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization/drift correction see metabolomics/normalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning/biomarker-discovery and machine-learning/model-validation; for pathway interpretation see metabolomics/pathway-mapping; for design/power/multiplicity regime see experimental-design/multiple-testing.
bio-metabolomics-pathway-mapping
Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA/QEA), mummichog/PSEA on raw m/z peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference/background set. For annotation confidence levels feeding ORA see metabolomics/metabolite-annotation; for gene-set concepts see pathway-analysis/go-enrichment and pathway-analysis/gsea; for joint gene+metabolite pathways see multi-omics-integration/mofa-integration.
bio-metabolomics-normalization-qc
Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS/GC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak/feature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics/xcms-preprocessing or metabolomics/msdial-preprocessing; transformation/scaling for modeling defers to metabolomics/statistical-analysis; cross-study design issues link to experimental-design/batch-design.
bio-metabolomics-msdial-preprocessing
Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA/DIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics/xcms-preprocessing; for lipid annotation mode see metabolomics/lipidomics; for MSI-level confidence honesty see metabolomics/metabolite-annotation; for drift correction and QC see metabolomics/normalization-qc.