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

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

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

Plot Mode

nomogram_c_index.xlsx

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

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