hierarchical-clustering-plot

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."

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

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

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

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

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

• CLI parsing with optparse
• set.seed() for reproducibility
• Input validation (file existence, emptiness, types, required columns)
• Try-catch based fatal error handling
• Standardized SKILL_* error classification
• Timeout control with setTimeLimit()
• Standardized console-only logging
• Base R clustering implementation
• Session info recording with sink()
• Temporary workspace cleanup with on.exit()
• Memory usage reporting with gc()
• File reading instructions in SKILL.md
• Modular script structure across scripts/
• Test template added under tests/testthat/
• Test data provided
• Error handling with SKILL_* codes
• get_script_dir() defined before use
• Scripts in scripts/ directory
• References in references/ directory

Last updated: 2026-04-16 | Version: 1.0.0