nomogram-construction
Use when constructing a prognosis nomogram from survival-related clinical predictors, exporting the nomogram bundle and C-index table, and optionally rendering the final nomogram PDF. NOT for: univariate/multivariable Cox feature screening, calibration curves, ROC analysis, decision-curve analysis, or non-survival outcomes.
- License 许可
- MIT
- 最近更新
- 2026-10-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- nomogram-construction
- license
- MIT
- description
- Use when constructing a prognosis nomogram from survival-related clinical predictors, exporting the nomogram bundle and C-index table, and optionally rendering the final nomogram PDF. NOT for: univariate/multivariable Cox feature screening, calibration curves, ROC analysis, decision-curve analysis, or non-survival outcomes.
- skill-author
- AIPOCH
02 资源文件 19
- 参考文档references/algorithm.md3.0 KB
- 参考文档references/cli-guide.md2.6 KB
- 参考文档references/troubleshooting.md3.4 KB
- 脚本scripts/functions.R3.6 KB
- 脚本scripts/io.R4.1 KB
- 脚本scripts/main.R4.2 KB
- 脚本scripts/run_analysis.R2.3 KB
- 脚本scripts/utils.R991 B
- 脚本scripts/validation.R2.6 KB
- 资产文件tests/data/yuhou_cli_data.csv42.1 KB
- 其他tests/expected_output/data/analysis_data.rds4.0 KB
- 其他tests/expected_output/data/Nomogram_list.qs21.6 KB
- 参考文档tests/expected_output/plot/session_info.txt2.7 KB
- 参考文档tests/expected_output/session_info.txt2.7 KB
- 资产文件tests/expected_output/table/nomogram_c_index.xlsx6.3 KB
- 其他tests/run_smoke_test.R2.0 KB
- 脚本tests/run_smoke_test.sh127 B
- 其他tests/testthat.R233 B
- 其他tests/testthat/test-cli-smoke.R1.3 KB
03 SKILL.md 正文
Nomogram Construction
When to Use
Use this skill when you need to:
- build a prognosis nomogram from already selected clinical prognostic variables;
- estimate model discrimination with a C-index table;
- export a nomogram bundle and generate a publication-ready nomogram PDF.
Typical user requests:
- "Build a prognosis nomogram from age, stage, and risk score."
- "Use these Cox-selected predictors to construct a nomogram and calculate the C-index."
- "Generate a nomogram PDF from a survival prediction model."
When Not to Use
Do not use this skill for:
- screening prognostic variables from scratch with Cox regression;
- ROC curves, calibration curves, or decision-curve analysis;
- diagnosis models, binary classification, or non-survival outcomes;
- single-cell, differential-expression, or pathway analysis.
When to Read External Files
| Situation | File to Read | Purpose |
|---|---|---|
| Need algorithm details | references/algorithm.md |
Cox-based nomogram workflow, C-index, and assumptions |
| Need to run analysis | scripts/main.R |
Execute Rscript scripts/main.R --mode build ... or --mode plot ... |
| Encounter errors | references/troubleshooting.md |
Common SKILL_* errors and solutions |
| Need CLI examples | references/cli-guide.md |
Detailed command-line examples |
| Need test data | tests/data/ |
Example clinical CSV for smoke testing |
Input Validation
This skill accepts:
- A clinical CSV file with survival time, event indicator, and pre-selected prognostic features
- Requests to build a Cox-based prognostic nomogram and compute the C-index
- Requests to re-render a nomogram PDF from an existing
.qsbundle (plot mode)
If the user's request does not involve nomogram construction from survival data — for example, asking to screen features with Cox regression, generate calibration curves, perform ROC analysis, or analyze non-survival binary outcomes — do not proceed with this workflow. Instead respond:
"nomogram-construction is designed to build a prognosis nomogram from pre-selected survival predictors and export the nomogram bundle with C-index table. Your request appears to be outside this scope. Please use a Cox feature-screening skill for variable selection, or a calibration-curve/ROC skill for model validation."
Prerequisites
R packages required: rms, openxlsx, qs, optparse.
Install with:
install.packages(c("rms", "openxlsx", "qs", "optparse"), repos = "https://cloud.r-project.org")
Or run the bootstrap installer:
Rscript scripts/install_dependencies.R
Note:
--helprequiresoptparseto be loaded. If the package check fires before option parsing, installoptparsefirst, then run--help.
Usage
Build Nomogram Bundle
Rscript scripts/main.R \
--mode build \
--data_file ./clinical_data.csv \
--features age,stage,risk \
--time_col futime \
--event_col fustat \
--years 1,2,3 \
--output_dir ./output/ \
--seed 42
Render Nomogram Plot
Rscript scripts/main.R \
--mode plot \
--nomo_data_file ./output/data/Nomogram_list.qs \
--plot_save ./output/plot/nomogram_plot.pdf
Arguments
| Short | Long | Type | Default | Description |
|---|---|---|---|---|
-m |
--mode |
character | build |
Execution mode: build or plot |
-d |
--data_file |
character | required for build | Clinical CSV file with sample IDs as row names |
-f |
--features |
character | required for build | Comma-separated prognostic features |
-t |
--time_col |
character | futime |
Survival time column |
-e |
--event_col |
character | fustat |
Event column encoded as 1=event, 0=censored |
-y |
--years |
character | 1,2,3 |
Prediction time points in years |
-o |
--output_dir |
character | ./output/ |
Output directory for build mode |
--overwrite |
flag | FALSE |
Allow writing into a non-empty output directory | |
-n |
--nomo_data_file |
character | required for plot | Nomogram bundle in .qs format |
-p |
--plot_save |
character | required for plot | Output PDF path |
-w |
--plot_width |
double | 11 |
Plot width in inches |
-H |
--plot_height |
double | 8 |
Plot height in inches |
-F |
--font_size |
double | 8 |
Plot font size |
-l |
--line_width |
double | 5 |
Plot line width |
--font_family |
character | sans |
Font family for PDF output | |
-s |
--seed |
integer | 42 |
Random seed for reproducibility |
-T |
--timeout_seconds |
integer | 0 |
Elapsed time limit in seconds; 0 disables timeout |
Input Format
Clinical Data (data_file)
CSV file with sample IDs as row names and one column per feature/end-point variable.
",age,stage,risk,futime,fustat
SAMPLE_001,65,StageIII,high,365,1
SAMPLE_002,52,StageII,low,730,0
SAMPLE_003,78,StageIV,high,180,1
Requirements
- File format must be CSV.
- Sample IDs must be stored in the first column as row names.
- At least 3 prognostic features are required.
time_colmust contain finite numeric values greater than0.event_colmust contain only0and1.- At least 20 complete samples and at least 10 events are required after filtering incomplete rows.
Nomogram Bundle (nomo_data_file)
The plot mode reads the .qs bundle produced by build mode.
Required bundle objects:
nomogramc_indexmodeldatafeaturestime_points
Output Files
Build Mode
| File | Description |
|---|---|
data/Nomogram_list.qs |
Serialized nomogram bundle |
data/analysis_data.rds |
Complete-case dataset used for modeling |
table/nomogram_c_index.xlsx |
Nomogram discrimination summary |
session_info.txt |
Session information and build parameters |
Plot Mode
| File | Description |
|---|---|
plot/nomogram_plot.pdf |
Rendered nomogram PDF |
plot/session_info.txt |
Plotting session information and parameters |
nomogram_c_index.xlsx
| Column | Description |
|---|---|
metric |
Reported metric name |
value |
Metric value |
Workflow
Step 1: Validate Input
- Check file existence and CSV format.
- Validate required feature, time, and event columns.
- Validate time/event values and minimum sample/event counts.
Step 2: Prepare Modeling Dataset
- Keep only requested features and outcome columns.
- Convert character predictors to factors.
- Remove incomplete rows across model variables.
Step 3: Fit Cox-Based Nomogram Model
- Fit an
rms::cphsurvival model. - Build survival functions at requested time points.
- Construct the nomogram object.
Step 4: Evaluate Performance
- Compute the model C-index.
- Save a compact discrimination summary table.
Step 5: Save And Plot
- Save the nomogram bundle and analysis dataset.
- Render the nomogram PDF in plot mode.
Examples
Basic Build
Rscript scripts/main.R \
--mode build \
-d clinical_data.csv \
-f age,stage,risk \
-o ./output/
Custom Prediction Horizons
Rscript scripts/main.R \
--mode build \
-d clinical_data.csv \
-f age,stage,risk,treatment \
-y 1,3,5 \
-o ./output/
Plot Existing Bundle
Rscript scripts/main.R \
--mode plot \
-n ./output/data/Nomogram_list.qs \
-p ./output/plot/nomogram_plot.pdf \
-w 12 -H 9 -F 10
Error Handling
| Error | Cause | Solution |
|---|---|---|
SKILL_FILE_NOT_FOUND |
Input file does not exist | Verify the file path |
SKILL_EMPTY_DATA |
Input file is empty or has no usable rows and columns | Re-export the input file with valid rows and columns |
SKILL_MISSING_COLUMNS |
Required columns are absent from the clinical data | Check column names and spelling |
SKILL_INVALID_DATA |
Invalid time/event encoding, malformed bundle, or unreadable CSV/QS file | Check input values and file integrity |
SKILL_INSUFFICIENT_DATA |
Too few features, complete samples, or events | Provide more valid predictors or samples |
SKILL_ANALYSIS_ERROR |
cph() fitting, nomogram construction, or output writing failed |
Check data quality, factor levels, and event distribution |
SKILL_INVALID_PARAMETER |
Missing required CLI value, invalid mode, invalid years, or overwrite conflict | Review command-line arguments |
SKILL_PACKAGE_NOT_FOUND |
Required R package is not installed | Install with: Rscript -e "install.packages(c('rms', 'openxlsx', 'qs'), repos='https://cloud.r-project.org')" |
SKILL_TIMEOUT |
The configured timeout was exceeded | Increase --timeout_seconds or reduce workload |
IF error persists, READ: references/troubleshooting.md
Testing
Smoke Test With Included Data
Rscript scripts/main.R --help
Rscript scripts/main.R \
--mode build \
-d tests/data/yuhou_cli_data.csv \
-f age,gender,risk \
-o tests/expected_output/ \
--overwrite
Rscript scripts/main.R \
--mode plot \
-n tests/expected_output/data/Nomogram_list.qs \
-p tests/expected_output/plot/nomogram_plot.pdf
Automated Smoke Test Script
Rscript tests/run_smoke_test.R
Optional shell wrapper:
bash tests/run_smoke_test.sh
Expected Output
tests/expected_output/
|-- data/analysis_data.rds
|-- data/Nomogram_list.qs
|-- plot/nomogram_plot.pdf
|-- plot/session_info.txt
|-- session_info.txt
`-- table/nomogram_c_index.xlsx
Historical development artifacts may still exist in tests/output/, but standardized validation uses tests/expected_output/.
References
- Harrell FE (2015). Regression Modeling Strategies.
- Iasonos A et al. (2008). How to build and interpret a nomogram for cancer prognosis. Journal of Clinical Oncology.
- Balachandran VP et al. (2015). Nomograms in oncology: more than meets the eye. The Lancet Oncology.
For detailed algorithm, READ: references/algorithm.md
Implementation Checklist
- [x] CLI parsing with
optparse - [x]
set.seed()for reproducibility - [x]
requireNamespace()dependency checks - [x] Session info recording
- [x] Timeout parameter exposed as CLI option
- [x] File reading instructions in
SKILL.md - [x] Modular script structure in
scripts/ - [x] Test data provided in
tests/data/ - [x] Error handling with
SKILL_*codes - [x] References documented in
references/
Last updated: 2026-04-27 | Version: 2.1.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.