consensus-clustering-analysis
Use when identifying stable sample subtypes from bulk expression matrices with ConsensusClusterPlus, including PAC-based model selection and consensus matrix/CDF visualization. NOT for: differential expression analysis, single-cell clustering workflows, or non-expression tables.
- License 许可
- MIT
- 最近更新
- 2026-10-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- consensus-clustering-analysis
- author
- AIPOCH
- license
- MIT
- description
- Use when identifying stable sample subtypes from bulk expression matrices with ConsensusClusterPlus, including PAC-based model selection and consensus matrix/CDF visualization. NOT for: differential expression analysis, single-cell clustering workflows, or non-expression tables.
02 资源文件 18
- 其他DESCRIPTION549 B
- 参考文档references/algorithm.md2.2 KB
- 参考文档references/cli-guide.md11.1 KB
- 参考文档references/troubleshooting.md2.9 KB
- 脚本scripts/functions_analysis.R5.6 KB
- 脚本scripts/io_utils.R2.0 KB
- 脚本scripts/main.R5.1 KB
- 脚本scripts/run_analysis.R5.8 KB
- 脚本scripts/utils.R3.6 KB
- 脚本scripts/visualization.R2.8 KB
- 资产文件tests/data/expression_matrix.csv47.0 KB
- 资产文件tests/data/genes.csv229 B
- 资产文件tests/data/groups.csv633 B
- 其他tests/run_tests.R773 B
- 其他tests/testthat.R889 B
- 其他tests/testthat/setup.R251 B
- 其他tests/testthat/test-cli-smoke.R5.5 KB
- 其他tests/testthat/test-functions.R2.1 KB
03 SKILL.md 正文
Consensus Clustering Analysis
When to Use
Use this skill when you need to identify stable sample subtypes from a bulk expression matrix with ConsensusClusterPlus, compare candidate clustering settings with PAC, and export consensus matrix/CDF visualizations.
Do not use this skill for differential expression analysis, single-cell clustering, or non-expression tabular data.
When to Read External Files
| Situation | File to Read | Purpose |
|---|---|---|
| Need algorithm details | references/algorithm.md |
Consensus clustering, PAC scoring, and preprocessing assumptions |
| Need to run analysis | scripts/main.R |
Execute: Rscript scripts/main.R --input_file ... --group_file ... |
| Encounter errors | references/troubleshooting.md |
Common errors and solutions |
| Need CLI examples | references/cli-guide.md |
Detailed CLI usage examples with verified local runs |
Usage
Rscript scripts/main.R \
--input_file ./expression_matrix.csv \
--group_file ./groups.csv \
--disease_group case \
--max_k 4 \
--output_dir ./output/ \
--gene_selection highly_variable \
--top_n 5000 \
--reps 1000 \
--p_item 0.8 \
--p_feature 1.0 \
--timeout_seconds 3600 \
--seed 42
Arguments
| Short | Long | Type | Default | Description |
|---|---|---|---|---|
-i |
--input_file |
character | required | Expression matrix file (genes as rows, samples as columns) |
-g |
--group_file |
character | required | Group information file (sample ID + group columns) |
-d |
--disease_group |
character | case |
Group label retained for clustering |
-k |
--max_k |
integer | 4 |
Maximum cluster count to evaluate |
-o |
--output_dir |
character | ./output/ |
Output directory |
-m |
--gene_selection |
character | highly_variable |
Gene selection mode: highly_variable or custom |
-n |
--top_n |
integer | 5000 |
Number of top variable genes to keep |
-l |
--gene_list |
character | NULL |
Custom gene list file when gene_selection=custom |
-c |
--center_data |
logical | TRUE |
Median-center each gene before clustering |
-r |
--reps |
integer | 1000 |
Consensus resampling repetitions |
--p_item |
double | 0.8 |
Sample resampling proportion | |
--p_feature |
double | 1.0 |
Feature resampling proportion | |
-t |
--timeout_seconds |
integer | 3600 |
Elapsed timeout in seconds |
-s |
--seed |
integer | 42 |
Random seed for reproducibility |
Input Format
Expression Matrix (input_file)
Genes as rows, samples as columns, CSV/TSV/TXT format with gene ID in the first column.
,Sample01,Sample02,Sample03
TSPAN6,1.8479,1.8318,3.8276
TNMD,0.0349,0.0533,1.3889
Group File (group_file)
Delimited text file with sample ID and group columns.
sample,group
Sample01,case
Sample02,control
Sample03,case
Gene List (gene_list)
Optional plain text or single-column CSV file with one gene symbol per line.
TNMD
DPM1
SCYL3
Output Files
| File | Description |
|---|---|
Cluster_res.csv |
PAC summary for each distance/algorithm combination with is_best marking the selected model |
genes_for_clustering.csv |
Selected genes and gene selection mode |
samples_for_clustering.csv |
Samples retained after disease-group filtering |
result_<distance>_<algorithm>/ |
Method-specific consensus outputs and PAC_scores.csv |
Consensus Matrix Plot.pdf |
Consensus matrix heatmap for the optimal model |
CDF curve Plot.pdf |
CDF curves for the optimal method |
session_info.txt |
R session and package version info |
Workflow
Step 1: Validate Input
- Check file existence
- Detect sample and group columns in the group file
- Validate sample matching between expression matrix and group file
Step 2: Prepare Clustering Matrix
- Filter samples by the requested disease group
- Select genes using
highly_variableorcustom - Median-center genes if requested
Step 3: Run Consensus Clustering
- Evaluate supported distance and clustering algorithm combinations
- Compute PAC scores across candidate K values
- Select the optimal model by minimum PAC
Step 4: Generate Outputs
- Save result tables
- Generate consensus matrix and CDF plots
- Record session information for reproducibility
Methods
ConsensusClusterPlus
Repeated subsampling is used to estimate cluster stability across candidate K values and clustering settings.
PAC Score
The proportion of ambiguous clustering is computed as CDF(0.9) - CDF(0.1) from lower-triangle consensus values. Lower PAC indicates more stable clustering.
Gene Selection
highly_variable: rank genes by median absolute deviationcustom: use the intersection of the provided gene list and matrix row names
Examples
Basic Usage
Rscript scripts/main.R \
-i expression_matrix.csv \
-g groups.csv \
-d case \
-k 3 \
-r 20 \
-o output/example_basic \
-t 120
With a Custom Gene List
Rscript scripts/main.R \
-i expression_matrix.csv \
-g groups.csv \
-d case \
-m custom \
-l genes.csv \
-k 4 \
-r 20 \
-o output/example_custom \
-t 120
Without Median Centering
Rscript scripts/main.R \
-i expression_matrix.csv \
-g groups.csv \
-d case \
-c FALSE \
-k 3 \
-r 20 \
-o output/example_rawscale \
-t 120
Error Handling
Common Errors
| Error | Cause | Solution |
|---|---|---|
SKILL_FILE_NOT_FOUND |
Input file does not exist | Check file path and permissions |
SKILL_MISSING_COLUMNS |
Group file lacks sample/group columns | Verify column names in the group file |
SKILL_SAMPLE_MISMATCH |
Sample names do not match | Ensure group file sample IDs match matrix columns |
SKILL_INVALID_PARAMETER |
CLI value is invalid | Check allowed options and numeric ranges |
SKILL_INVALID_DATA |
Too few samples/genes remain after filtering | Lower max_k or review the input data |
SKILL_TIMEOUT |
Run exceeded the configured timeout | Increase timeout_seconds or reduce reps |
SKILL_DEPENDENCY_MISSING |
Required R package is not installed | Install missing packages before rerunning |
IF error persists, READ: references/troubleshooting.md
Testing
Smoke Check
# Check help
Rscript scripts/main.R --help
# Run analysis
Rscript scripts/main.R \
-i tests/data/expression_matrix.csv \
-g tests/data/groups.csv \
-d case \
-k 3 \
-r 20 \
-o output/example_basic \
-t 120
Validation Commands
# Inspect selected model
cat output/example_basic/Cluster_res.csv
# Check output plots exist
ls -la output/example_basic
Implementation Checklist
- [x] CLI parsing with
optparse - [x]
set.seed()for reproducibility - [x]
requireNamespace()dependency checks - [x] Session info recording
- [x]
data.table::fread()input reading - [x] File reading instructions in
SKILL.md - [x] Modular script structure (<150 lines per file)
- [x] Test data provided
- [x] Error handling with
SKILL_*codes - [x] Scripts in
scripts/directory - [x] References in
references/directory
Last updated: 2026-04-17 | 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.