nomogram-construction

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	`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_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

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

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