AGENT SKILL

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

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 .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

  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

  • [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

mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2