[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CVZ09VCDTJ79PBK3EY3FKE":3,"skill-same:01M7CVZ09VCDTJ79PBK3EY3FKE":117},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7CVZ09VCDTJ79PBK3EY3FKE","hierarchical-clustering-plot",null,"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.","mrsonord2240\u002Fopenscience-specialists","mrsonord2240","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F76487430?v=4","01M7CTEM40S43GSJZ9A3YCCXZK","Samuel Nord","01M7CTEM4K69JD1GBYNHVJ9ZP4",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: hierarchical-clustering-plot\ndescription: \"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.\"\n---\n\n# Hierarchical Clustering Plot\n\n## When to Use\n\nUse this skill when you need a sample-level hierarchical clustering dendrogram from a bulk expression matrix and a sample annotation table.\n\n- Good fits: sample QC, batch inspection, sample similarity assessment, checking whether annotated sample groups cluster as expected.\n- Trigger keywords: hierarchical clustering, dendrogram, sample QC, batch inspection, sample similarity.\n- Not for: differential expression testing, gene clustering heatmaps, single-cell clustering workflows.\n\n## When to Read External Files\n\n| Situation | File to Read | Purpose |\n|-----------|--------------|---------|\n| **Need algorithm details** | `references\u002Falgorithm.md` | Distance calculation, linkage rules, and clustering assumptions |\n| **Need to run analysis or inspect CLI entrypoint behavior** | `scripts\u002Fmain.R` | Execute the workflow and inspect argument parsing, defaults, required flags, and sourced modules |\n| **Need workflow implementation details** | `scripts\u002Frun_analysis.R` | See orchestration order, temp workspace handling, and output generation |\n| **Need logging or warning behavior** | `scripts\u002Flogging_utils.R` | See standardized console log formatting and memory usage messages |\n| **Need file or parameter validation details** | `scripts\u002Fvalidation_utils.R` | See path checks, output-directory checks, and scalar validation |\n| **Need timeout, temp workspace, or session info behavior** | `scripts\u002Fruntime_utils.R` | See timeout control, temp cleanup, output copying, and session-info export |\n| **Need expression\u002Fgroup input handling** | `scripts\u002Finput_functions.R` | See CSV loading, sample matching, and label extraction |\n| **Need clustering logic** | `scripts\u002Fclustering_functions.R` | See distance calculation and `hclust()` generation |\n| **Need output-writing logic** | `scripts\u002Foutput_utils.R` | See CSV export and PDF rendering |\n| **Encounter errors, warnings, or unexpected clustering patterns** | `references\u002Ftroubleshooting.md` | Common failures, warning follow-up, and interpretation guidance |\n| **Need CLI examples or common parameter combinations** | `references\u002Fcli-guide.md` | Detailed command patterns for standard, variant, and test runs |\n| **Need example input files or schema-concrete fixtures** | `tests\u002Fdata\u002F` | Inspect sample CSV layouts for expression and group inputs |\n| **Need expected output names or artifact formats** | `## Output Files` and `references\u002Fcli-guide.md` | Confirm the files the workflow writes and inspect documented example previews |\n| **Need to run regression tests** | `tests\u002Frun_tests.R` | Execute the automated test suite |\n| **Need exact test assertions or edge cases** | `tests\u002Ftestthat\u002Ftest-clustering.R` | Inspect validation, reproducibility, and output checks |\n\n---\n\n## Usage\n\n```bash\nRscript scripts\u002Fmain.R \\\n  --input_file .\u002Fexpression_matrix.csv \\\n  --group_file .\u002Fsample_groups.csv \\\n  --output_dir .\u002Foutput\u002F \\\n  --distance_method euclidean \\\n  --linkage_method complete \\\n  --label_column batch \\\n  --timeout_seconds 300 \\\n  --seed 42\n```\n\n---\n\n## Arguments\n\n| Short | Long | Type | Default | Description |\n|-------|------|------|---------|-------------|\n| `-i` | `--input_file` | character | **required** | Expression matrix file (features as rows, samples as columns) |\n| `-g` | `--group_file` | character | **required** | Sample annotation file (first column sample ID, one metadata column for labels) |\n| `-o` | `--output_dir` | character | `.\u002Foutput\u002F` | Output directory |\n| `-d` | `--distance_method` | character | `euclidean` | Distance metric for `dist()`: euclidean, maximum, manhattan, canberra, binary, minkowski |\n| `-m` | `--linkage_method` | character | `complete` | Linkage method for `hclust()`: complete, single, average, mcquitty, median, centroid, ward.D, ward.D2 |\n| `-l` | `--label_column` | character | second column | Column used as dendrogram labels |\n| `-c` | `--label_cex` | numeric | `0.8` | Dendrogram label size, must be `> 0` |\n| `-t` | `--timeout_seconds` | integer | `300` | Elapsed time limit in seconds, must be `> 0` |\n| `-s` | `--seed` | integer | `42` | Random seed for reproducibility |\n\n---\n\n## Input Format\n\n### Expression Matrix (`input_file`)\n\nFeatures as rows, samples as columns, CSV format with feature IDs in the first column.\n\n```csv\n,Sample01,Sample02,Sample03\nTSPAN6,1.847876677,1.831755661,3.827625975\nTNMD,0.034919984,0.053250385,1.388850793\n```\n\n**Requirements:**\n- The first column contains unique feature IDs.\n- All sample columns must be numeric.\n- Sample column names must be unique and non-empty.\n- At least two matched samples are required.\n\n### Sample Annotation (`group_file`)\n\nCSV with sample IDs in the first column. The second column is used by default for leaf labels unless `--label_column` is provided.\n\n```csv\nsample,batch\nSample01,batch1\nSample02,batch2\nSample03,batch1\n```\n\n**Requirements:**\n- Sample IDs must match expression matrix column names exactly.\n- The selected label column must exist and contain no empty values.\n- The file must contain at least one metadata column in addition to sample IDs.\n\n---\n\n## Output Files\n\n| File | Description |\n|------|-------------|\n| `hierarchical_clustering_plot.pdf` | Sample dendrogram plot |\n| `sample_distance_matrix.csv` | Pairwise sample distance matrix |\n| `clustering_order.csv` | Leaf order shown in the dendrogram |\n| `matched_samples.csv` | Sample-to-label table used for plotting |\n| `session_info.txt` | R session and package version info |\n\n## Workflow\n\n### Step 1: Validate Input\n**WHEN checking file or parameter validation**, READ: `scripts\u002Fvalidation_utils.R`\n\n**WHEN checking expression\u002Fgroup CSV handling**, READ: `scripts\u002Finput_functions.R`\n\n- Check file existence\n- Reject empty files before parsing\n- Read the expression matrix and sample annotation CSV files\n- Validate required columns, unique IDs, and numeric expression values\n\n### Step 2: Align Samples\n**WHEN checking sample matching logic**, READ: `scripts\u002Finput_functions.R`\n\n- Match sample IDs between the annotation file and expression matrix\n- Reorder matrix columns to the annotation file order\n- Select the label column used for plotting\n\n### Step 3: Build Hierarchical Clustering\n**WHEN interpreting distance or linkage behavior**, READ: `references\u002Falgorithm.md`\n\n**WHEN checking clustering implementation**, READ: `scripts\u002Fclustering_functions.R`\n\n- Transpose the expression matrix to sample-by-feature form\n- Compute pairwise sample distances with `dist()`\n- Build the dendrogram with `hclust()`\n\n### Step 4: Save Outputs\n**WHEN checking output staging and cleanup behavior**, READ: `scripts\u002Frun_analysis.R`\n\n**WHEN checking PDF\u002FCSV export behavior**, READ: `scripts\u002Foutput_utils.R`\n\n**WHEN checking timeout, session info, or final file copy behavior**, READ: `scripts\u002Fruntime_utils.R`\n\n- Stage outputs in a temporary workspace\n- Export the pairwise distance matrix\n- Export the plotted leaf order\n- Render the dendrogram as PDF\n- Copy finalized outputs into the requested output directory\n\n---\n\n## Methods\n\n### Distance Matrix\nSample distances are computed from the transposed expression matrix using base R `dist()`.\n\n### Hierarchical Clustering\nThe clustering tree is built with base R `hclust()`. The default linkage method is `complete`, matching the source analysis script.\n\n---\n\n## Examples\n\n### Basic Usage\n```bash\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput\u002F \\\n  -t 300\n```\n\n### Use Sample IDs as Labels\n```bash\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput_sample_labels\u002F \\\n  -l sample\n```\n\n### Use Average Linkage\n```bash\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput_average\u002F \\\n  -m average\n```\n\n---\n\n## Error Handling\n\n### Common Errors\n\n| Error | Cause | Solution | Read More |\n|-------|-------|----------|-----------|\n| `SKILL_DEPENDENCY_MISSING` | Required R package is not installed | Install the missing package and rerun | `references\u002Ftroubleshooting.md#skill_dependency_missing` |\n| `SKILL_FILE_NOT_FOUND` | Input file does not exist or output directory could not be created | Check the path and permissions | `references\u002Ftroubleshooting.md#skill_file_not_found` |\n| `SKILL_EMPTY_FILE` | Input file is empty | Re-export the CSV and confirm it contains data | `references\u002Ftroubleshooting.md#skill_empty_file` |\n| `SKILL_EMPTY_DATA` | CSV parsed successfully but contains no data rows | Confirm the CSV has at least one data row | `references\u002Ftroubleshooting.md#skill_empty_data` |\n| `SKILL_PARSE_ERROR` | CSV parsing failed | Check encoding, delimiters, and CSV structure | `references\u002Ftroubleshooting.md#skill_parse_error` |\n| `SKILL_MISSING_COLUMNS` | Expected columns or headers are missing | Check CSV headers and metadata columns | `references\u002Ftroubleshooting.md#skill_missing_columns` |\n| `SKILL_INVALID_TYPE` | Expression values or parameters have the wrong type | Ensure numeric fields are numeric | `references\u002Ftroubleshooting.md#skill_invalid_type` |\n| `SKILL_SAMPLE_MISMATCH` | Sample IDs do not match | Ensure the first column in `group_file` matches matrix column names | `references\u002Ftroubleshooting.md#skill_sample_mismatch` |\n| `SKILL_INVALID_DATA` | Expression or annotation data is malformed | Check duplicate IDs, missing labels, and numeric values | `references\u002Ftroubleshooting.md#skill_invalid_data` |\n| `SKILL_INVALID_PARAMETER` | Unsupported distance, linkage, or label parameter | Use one of the documented parameter values | `references\u002Ftroubleshooting.md#skill_invalid_parameter` |\n| `SKILL_TIMEOUT` | Analysis exceeded the time limit | Increase `--timeout_seconds` and rerun | `references\u002Ftroubleshooting.md#skill_timeout` |\n| `SKILL_PLOT_ERROR` | Plot device failed while writing PDF | Check output directory permissions and rerun | `references\u002Ftroubleshooting.md#skill_plot_error` |\n| `SKILL_WRITE_ERROR` | Output or intermediate files could not be written | Check output directory permissions and free disk space | `references\u002Ftroubleshooting.md#skill_write_error` |\n| `SKILL_WARNING` | Non-fatal warning occurred during execution | Inspect console warnings and verify output quality | `references\u002Ftroubleshooting.md#skill_warning` |\n| `SKILL_MEMORY_WARNING` | Memory usage exceeded the warning threshold | Reduce input size or rerun with more memory | `references\u002Ftroubleshooting.md#skill_memory_warning` |\n\n**IF error persists**, READ: `references\u002Ftroubleshooting.md`\n\n---\n\n## Testing\n\n### Test with Sample Data\n\n```bash\n# Check help\nRscript scripts\u002Fmain.R --help\n\n# Run with sample data\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput\u002F\n\n# Run unit tests (requires testthat and data.table)\nRscript tests\u002Frun_tests.R\n```\n\n### Validation Commands\n\n```bash\n# Check main output plot exists\nls -la .\u002Foutput\u002Fhierarchical_clustering_plot.pdf\n\n# Inspect clustering order\nwc -l .\u002Foutput\u002Fclustering_order.csv\n```\n\n## Implementation Checklist\n\n- [x] CLI parsing with `optparse`\n- [x] `set.seed()` for reproducibility\n- [x] Input validation (file existence, emptiness, types, required columns)\n- [x] Try-catch based fatal error handling\n- [x] Standardized `SKILL_*` error classification\n- [x] Timeout control with `setTimeLimit()`\n- [x] Standardized console-only logging\n- [x] Base R clustering implementation\n- [x] Session info recording with `sink()`\n- [x] Temporary workspace cleanup with `on.exit()`\n- [x] Memory usage reporting with `gc()`\n- [x] File reading instructions in SKILL.md\n- [x] Modular script structure across `scripts\u002F`\n- [x] Test template added under `tests\u002Ftestthat\u002F`\n- [x] Test data provided\n- [x] Error handling with `SKILL_*` codes\n- [x] `get_script_dir()` defined before use\n- [x] Scripts in `scripts\u002F` directory\n- [x] References in `references\u002F` directory\n\n---\n\n*Last updated: 2026-04-16 | Version: 1.0.0*\n","# Hierarchical Clustering Plot\n\n## When to Use\n\nUse this skill when you need a sample-level hierarchical clustering dendrogram from a bulk expression matrix and a sample annotation table.\n\n- Good fits: sample QC, batch inspection, sample similarity assessment, checking whether annotated sample groups cluster as expected.\n- Trigger keywords: hierarchical clustering, dendrogram, sample QC, batch inspection, sample similarity.\n- Not for: differential expression testing, gene clustering heatmaps, single-cell clustering workflows.\n\n## When to Read External Files\n\n| Situation | File to Read | Purpose |\n|-----------|--------------|---------|\n| **Need algorithm details** | `references\u002Falgorithm.md` | Distance calculation, linkage rules, and clustering assumptions |\n| **Need to run analysis or inspect CLI entrypoint behavior** | `scripts\u002Fmain.R` | Execute the workflow and inspect argument parsing, defaults, required flags, and sourced modules |\n| **Need workflow implementation details** | `scripts\u002Frun_analysis.R` | See orchestration order, temp workspace handling, and output generation |\n| **Need logging or warning behavior** | `scripts\u002Flogging_utils.R` | See standardized console log formatting and memory usage messages |\n| **Need file or parameter validation details** | `scripts\u002Fvalidation_utils.R` | See path checks, output-directory checks, and scalar validation |\n| **Need timeout, temp workspace, or session info behavior** | `scripts\u002Fruntime_utils.R` | See timeout control, temp cleanup, output copying, and session-info export |\n| **Need expression\u002Fgroup input handling** | `scripts\u002Finput_functions.R` | See CSV loading, sample matching, and label extraction |\n| **Need clustering logic** | `scripts\u002Fclustering_functions.R` | See distance calculation and `hclust()` generation |\n| **Need output-writing logic** | `scripts\u002Foutput_utils.R` | See CSV export and PDF rendering |\n| **Encounter errors, warnings, or unexpected clustering patterns** | `references\u002Ftroubleshooting.md` | Common failures, warning follow-up, and interpretation guidance |\n| **Need CLI examples or common parameter combinations** | `references\u002Fcli-guide.md` | Detailed command patterns for standard, variant, and test runs |\n| **Need example input files or schema-concrete fixtures** | `tests\u002Fdata\u002F` | Inspect sample CSV layouts for expression and group inputs |\n| **Need expected output names or artifact formats** | `## Output Files` and `references\u002Fcli-guide.md` | Confirm the files the workflow writes and inspect documented example previews |\n| **Need to run regression tests** | `tests\u002Frun_tests.R` | Execute the automated test suite |\n| **Need exact test assertions or edge cases** | `tests\u002Ftestthat\u002Ftest-clustering.R` | Inspect validation, reproducibility, and output checks |\n\n---\n\n## Usage\n\n```bash\nRscript scripts\u002Fmain.R \\\n  --input_file .\u002Fexpression_matrix.csv \\\n  --group_file .\u002Fsample_groups.csv \\\n  --output_dir .\u002Foutput\u002F \\\n  --distance_method euclidean \\\n  --linkage_method complete \\\n  --label_column batch \\\n  --timeout_seconds 300 \\\n  --seed 42\n```\n\n---\n\n## Arguments\n\n| Short | Long | Type | Default | Description |\n|-------|------|------|---------|-------------|\n| `-i` | `--input_file` | character | **required** | Expression matrix file (features as rows, samples as columns) |\n| `-g` | `--group_file` | character | **required** | Sample annotation file (first column sample ID, one metadata column for labels) |\n| `-o` | `--output_dir` | character | `.\u002Foutput\u002F` | Output directory |\n| `-d` | `--distance_method` | character | `euclidean` | Distance metric for `dist()`: euclidean, maximum, manhattan, canberra, binary, minkowski |\n| `-m` | `--linkage_method` | character | `complete` | Linkage method for `hclust()`: complete, single, average, mcquitty, median, centroid, ward.D, ward.D2 |\n| `-l` | `--label_column` | character | second column | Column used as dendrogram labels |\n| `-c` | `--label_cex` | numeric | `0.8` | Dendrogram label size, must be `> 0` |\n| `-t` | `--timeout_seconds` | integer | `300` | Elapsed time limit in seconds, must be `> 0` |\n| `-s` | `--seed` | integer | `42` | Random seed for reproducibility |\n\n---\n\n## Input Format\n\n### Expression Matrix (`input_file`)\n\nFeatures as rows, samples as columns, CSV format with feature IDs in the first column.\n\n```csv\n,Sample01,Sample02,Sample03\nTSPAN6,1.847876677,1.831755661,3.827625975\nTNMD,0.034919984,0.053250385,1.388850793\n```\n\n**Requirements:**\n- The first column contains unique feature IDs.\n- All sample columns must be numeric.\n- Sample column names must be unique and non-empty.\n- At least two matched samples are required.\n\n### Sample Annotation (`group_file`)\n\nCSV with sample IDs in the first column. The second column is used by default for leaf labels unless `--label_column` is provided.\n\n```csv\nsample,batch\nSample01,batch1\nSample02,batch2\nSample03,batch1\n```\n\n**Requirements:**\n- Sample IDs must match expression matrix column names exactly.\n- The selected label column must exist and contain no empty values.\n- The file must contain at least one metadata column in addition to sample IDs.\n\n---\n\n## Output Files\n\n| File | Description |\n|------|-------------|\n| `hierarchical_clustering_plot.pdf` | Sample dendrogram plot |\n| `sample_distance_matrix.csv` | Pairwise sample distance matrix |\n| `clustering_order.csv` | Leaf order shown in the dendrogram |\n| `matched_samples.csv` | Sample-to-label table used for plotting |\n| `session_info.txt` | R session and package version info |\n\n## Workflow\n\n### Step 1: Validate Input\n**WHEN checking file or parameter validation**, READ: `scripts\u002Fvalidation_utils.R`\n\n**WHEN checking expression\u002Fgroup CSV handling**, READ: `scripts\u002Finput_functions.R`\n\n- Check file existence\n- Reject empty files before parsing\n- Read the expression matrix and sample annotation CSV files\n- Validate required columns, unique IDs, and numeric expression values\n\n### Step 2: Align Samples\n**WHEN checking sample matching logic**, READ: `scripts\u002Finput_functions.R`\n\n- Match sample IDs between the annotation file and expression matrix\n- Reorder matrix columns to the annotation file order\n- Select the label column used for plotting\n\n### Step 3: Build Hierarchical Clustering\n**WHEN interpreting distance or linkage behavior**, READ: `references\u002Falgorithm.md`\n\n**WHEN checking clustering implementation**, READ: `scripts\u002Fclustering_functions.R`\n\n- Transpose the expression matrix to sample-by-feature form\n- Compute pairwise sample distances with `dist()`\n- Build the dendrogram with `hclust()`\n\n### Step 4: Save Outputs\n**WHEN checking output staging and cleanup behavior**, READ: `scripts\u002Frun_analysis.R`\n\n**WHEN checking PDF\u002FCSV export behavior**, READ: `scripts\u002Foutput_utils.R`\n\n**WHEN checking timeout, session info, or final file copy behavior**, READ: `scripts\u002Fruntime_utils.R`\n\n- Stage outputs in a temporary workspace\n- Export the pairwise distance matrix\n- Export the plotted leaf order\n- Render the dendrogram as PDF\n- Copy finalized outputs into the requested output directory\n\n---\n\n## Methods\n\n### Distance Matrix\nSample distances are computed from the transposed expression matrix using base R `dist()`.\n\n### Hierarchical Clustering\nThe clustering tree is built with base R `hclust()`. The default linkage method is `complete`, matching the source analysis script.\n\n---\n\n## Examples\n\n### Basic Usage\n```bash\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput\u002F \\\n  -t 300\n```\n\n### Use Sample IDs as Labels\n```bash\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput_sample_labels\u002F \\\n  -l sample\n```\n\n### Use Average Linkage\n```bash\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput_average\u002F \\\n  -m average\n```\n\n---\n\n## Error Handling\n\n### Common Errors\n\n| Error | Cause | Solution | Read More |\n|-------|-------|----------|-----------|\n| `SKILL_DEPENDENCY_MISSING` | Required R package is not installed | Install the missing package and rerun | `references\u002Ftroubleshooting.md#skill_dependency_missing` |\n| `SKILL_FILE_NOT_FOUND` | Input file does not exist or output directory could not be created | Check the path and permissions | `references\u002Ftroubleshooting.md#skill_file_not_found` |\n| `SKILL_EMPTY_FILE` | Input file is empty | Re-export the CSV and confirm it contains data | `references\u002Ftroubleshooting.md#skill_empty_file` |\n| `SKILL_EMPTY_DATA` | CSV parsed successfully but contains no data rows | Confirm the CSV has at least one data row | `references\u002Ftroubleshooting.md#skill_empty_data` |\n| `SKILL_PARSE_ERROR` | CSV parsing failed | Check encoding, delimiters, and CSV structure | `references\u002Ftroubleshooting.md#skill_parse_error` |\n| `SKILL_MISSING_COLUMNS` | Expected columns or headers are missing | Check CSV headers and metadata columns | `references\u002Ftroubleshooting.md#skill_missing_columns` |\n| `SKILL_INVALID_TYPE` | Expression values or parameters have the wrong type | Ensure numeric fields are numeric | `references\u002Ftroubleshooting.md#skill_invalid_type` |\n| `SKILL_SAMPLE_MISMATCH` | Sample IDs do not match | Ensure the first column in `group_file` matches matrix column names | `references\u002Ftroubleshooting.md#skill_sample_mismatch` |\n| `SKILL_INVALID_DATA` | Expression or annotation data is malformed | Check duplicate IDs, missing labels, and numeric values | `references\u002Ftroubleshooting.md#skill_invalid_data` |\n| `SKILL_INVALID_PARAMETER` | Unsupported distance, linkage, or label parameter | Use one of the documented parameter values | `references\u002Ftroubleshooting.md#skill_invalid_parameter` |\n| `SKILL_TIMEOUT` | Analysis exceeded the time limit | Increase `--timeout_seconds` and rerun | `references\u002Ftroubleshooting.md#skill_timeout` |\n| `SKILL_PLOT_ERROR` | Plot device failed while writing PDF | Check output directory permissions and rerun | `references\u002Ftroubleshooting.md#skill_plot_error` |\n| `SKILL_WRITE_ERROR` | Output or intermediate files could not be written | Check output directory permissions and free disk space | `references\u002Ftroubleshooting.md#skill_write_error` |\n| `SKILL_WARNING` | Non-fatal warning occurred during execution | Inspect console warnings and verify output quality | `references\u002Ftroubleshooting.md#skill_warning` |\n| `SKILL_MEMORY_WARNING` | Memory usage exceeded the warning threshold | Reduce input size or rerun with more memory | `references\u002Ftroubleshooting.md#skill_memory_warning` |\n\n**IF error persists**, READ: `references\u002Ftroubleshooting.md`\n\n---\n\n## Testing\n\n### Test with Sample Data\n\n```bash\n# Check help\nRscript scripts\u002Fmain.R --help\n\n# Run with sample data\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fsample_expression_matrix.csv \\\n  -g tests\u002Fdata\u002Fsample_groups.csv \\\n  -o .\u002Foutput\u002F\n\n# Run unit tests (requires testthat and data.table)\nRscript tests\u002Frun_tests.R\n```\n\n### Validation Commands\n\n```bash\n# Check main output plot exists\nls -la .\u002Foutput\u002Fhierarchical_clustering_plot.pdf\n\n# Inspect clustering order\nwc -l .\u002Foutput\u002Fclustering_order.csv\n```\n\n## Implementation Checklist\n\n- [x] CLI parsing with `optparse`\n- [x] `set.seed()` for reproducibility\n- [x] Input validation (file existence, emptiness, types, required columns)\n- [x] Try-catch based fatal error handling\n- [x] Standardized `SKILL_*` error classification\n- [x] Timeout control with `setTimeLimit()`\n- [x] Standardized console-only logging\n- [x] Base R clustering implementation\n- [x] Session info recording with `sink()`\n- [x] Temporary workspace cleanup with `on.exit()`\n- [x] Memory usage reporting with `gc()`\n- [x] File reading instructions in SKILL.md\n- [x] Modular script structure across `scripts\u002F`\n- [x] Test template added under `tests\u002Ftestthat\u002F`\n- [x] Test data provided\n- [x] Error handling with `SKILL_*` codes\n- [x] `get_script_dir()` defined before use\n- [x] Scripts in `scripts\u002F` directory\n- [x] References in `references\u002F` directory\n\n---\n\n*Last updated: 2026-04-16 | Version: 1.0.0*\n",{"name":5,"description":7},"main","e0956dc9606356ab78468936b502e55a365282e2","specialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot",0,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists","https:\u002F\u002Fgithub.com\u002Fmrsonord2240","2026-10-12 03:19:04",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add mrsonord2240\u002Fopenscience-specialists --skill hierarchical-clustering-plot",{"tool":37,"command":38},"bunx","bunx skills add mrsonord2240\u002Fopenscience-specialists --skill hierarchical-clustering-plot",{"tool":40,"command":41},"pnpm","pnpm dlx skills add mrsonord2240\u002Fopenscience-specialists --skill hierarchical-clustering-plot","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002FSKILL.md",true,[45,51,57,61,65,71,75,79,83,87,91,95,99,105,109,113],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"DESCRIPTION","OTHER","其他",378,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002FDESCRIPTION",{"path":52,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":55,"sourceHtmlUrl":56},"references\u002Falgorithm.md","REFERENCE","参考文档",2548,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Freferences\u002Falgorithm.md",{"path":58,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":59,"sourceHtmlUrl":60},"references\u002Fcli-guide.md",4659,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Freferences\u002Fcli-guide.md",{"path":62,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":63,"sourceHtmlUrl":64},"references\u002Ftroubleshooting.md",5574,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Freferences\u002Ftroubleshooting.md",{"path":66,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":69,"sourceHtmlUrl":70},"scripts\u002Fclustering_functions.R","SCRIPT","脚本",1220,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Fclustering_functions.R",{"path":72,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":73,"sourceHtmlUrl":74},"scripts\u002Finput_functions.R",4201,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Finput_functions.R",{"path":76,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":77,"sourceHtmlUrl":78},"scripts\u002Flogging_utils.R",1028,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Flogging_utils.R",{"path":80,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":81,"sourceHtmlUrl":82},"scripts\u002Fmain.R",3848,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Fmain.R",{"path":84,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":85,"sourceHtmlUrl":86},"scripts\u002Foutput_utils.R",1330,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Foutput_utils.R",{"path":88,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":89,"sourceHtmlUrl":90},"scripts\u002Frun_analysis.R",3797,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Frun_analysis.R",{"path":92,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":93,"sourceHtmlUrl":94},"scripts\u002Fruntime_utils.R",1676,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Fruntime_utils.R",{"path":96,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":97,"sourceHtmlUrl":98},"scripts\u002Fvalidation_utils.R",1838,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Fscripts\u002Fvalidation_utils.R",{"path":100,"resourceType":101,"resourceTypeDesc":102,"sizeBytes":103,"sourceHtmlUrl":104},"tests\u002Fdata\u002Fsample_expression_matrix.csv","ASSET","资产文件",10458,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Ftests\u002Fdata\u002Fsample_expression_matrix.csv",{"path":106,"resourceType":101,"resourceTypeDesc":102,"sizeBytes":107,"sourceHtmlUrl":108},"tests\u002Fdata\u002Fsample_groups.csv",653,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Ftests\u002Fdata\u002Fsample_groups.csv",{"path":110,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":111,"sourceHtmlUrl":112},"tests\u002Frun_tests.R",1447,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Ftests\u002Frun_tests.R",{"path":114,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":115,"sourceHtmlUrl":116},"tests\u002Ftestthat\u002Ftest-clustering.R",6214,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Ftumor-immune-microenvironment-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fhierarchical-clustering-plot\u002Ftests\u002Ftestthat\u002Ftest-clustering.R",[118,125,132,139,146,153],{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":19},"01M7CW36A6QAGWFE2C008M1XPG","bio-workflows-metabolomics-pipeline","Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC\u002Fdrift\u002Fnormalization, 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\u002Fisotope-tracing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-workflows-metabolomics-pipeline\u002FSKILL.md",[],[],{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":19},"01M7CW2Y18623NA2S1Y30FRQW1","bio-metabolomics-xcms-preprocessing","Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment\u002FXcmsExperiment 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\u002Fgrouping\u002Falignment parameters. For drift correction and QC\u002FCV filtering execution see metabolomics\u002Fnormalization-qc; for metabolite identification see metabolomics\u002Fmetabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics\u002Fmsdial-preprocessing; for downstream statistics see metabolomics\u002Fstatistical-analysis.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-xcms-preprocessing\u002FSKILL.md",[],[],{"skillNo":133,"name":134,"nameZh":6,"description":135,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":136,"categories":137,"keywords":138,"publishedAt":19},"01M7CW2M364HVWPNQEKE2WP4PP","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\u002FHCA for QC), permutation-validated PLS-DA\u002FOPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch\u002FMann-Whitney\u002FANOVA\u002FLMM 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\u002Fdrift correction see metabolomics\u002Fnormalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning\u002Fbiomarker-discovery and machine-learning\u002Fmodel-validation; for pathway interpretation see metabolomics\u002Fpathway-mapping; for design\u002Fpower\u002Fmultiplicity regime see experimental-design\u002Fmultiple-testing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-statistical-analysis\u002FSKILL.md",[],[],{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":145,"publishedAt":19},"01M7CW2BCBF851WYE03Z8XPEDQ","bio-metabolomics-pathway-mapping","Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA\u002FQEA), mummichog\u002FPSEA on raw m\u002Fz 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\u002Fbackground set. For annotation confidence levels feeding ORA see metabolomics\u002Fmetabolite-annotation; for gene-set concepts see pathway-analysis\u002Fgo-enrichment and pathway-analysis\u002Fgsea; for joint gene+metabolite pathways see multi-omics-integration\u002Fmofa-integration.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-pathway-mapping\u002FSKILL.md",[],[],{"skillNo":147,"name":148,"nameZh":6,"description":149,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":150,"categories":151,"keywords":152,"publishedAt":19},"01M7CW21NSZMCPMF7D9CHJM718","bio-metabolomics-normalization-qc","Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS\u002FGC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak\u002Ffeature 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\u002Fxcms-preprocessing or metabolomics\u002Fmsdial-preprocessing; transformation\u002Fscaling for modeling defers to metabolomics\u002Fstatistical-analysis; cross-study design issues link to experimental-design\u002Fbatch-design.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-normalization-qc\u002FSKILL.md",[],[],{"skillNo":154,"name":155,"nameZh":6,"description":156,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":157,"categories":158,"keywords":159,"publishedAt":19},"01M7CW1SWVM0NYHVE6Q7MA3G7R","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\u002FDIA (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\u002Fxcms-preprocessing; for lipid annotation mode see metabolomics\u002Flipidomics; for MSI-level confidence honesty see metabolomics\u002Fmetabolite-annotation; for drift correction and QC see metabolomics\u002Fnormalization-qc.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002FSKILL.md",[],[]]