nomogram-construction

name	nomogram-construction
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.
license	MIT
skill-author	AIPOCH

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 .qs bundle (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: --help requires optparse to be loaded. If the package check fires before option parsing, install optparse first, 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

---

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_col must contain finite numeric values greater than 0.
• event_col must contain only 0 and 1.
• 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:

• nomogram
• c_index
• model
• data
• features
• time_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::cph survival 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

1. Harrell FE (2015). Regression Modeling Strategies.
2. Iasonos A et al. (2008). How to build and interpret a nomogram for cancer prognosis. Journal of Clinical Oncology.
3. 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

• CLI parsing with optparse
• set.seed() for reproducibility
• requireNamespace() dependency checks
• Session info recording
• Timeout parameter exposed as CLI option
• File reading instructions in SKILL.md
• Modular script structure in scripts/
• Test data provided in tests/data/
• Error handling with SKILL_* codes
• References documented in references/

---

Last updated: 2026-04-27 | Version: 2.1.0