Decision Curve Analysis

When to Use

Use this skill when you need to:

• evaluate whether a binary prediction model adds clinical net benefit across threshold probabilities;
• visualize decision curves and clinical-impact curves from a clinical cohort;
• export an auditable DCA model object together with summary text and PDFs.

Typical user requests:

• "Run decision-curve analysis on this binary outcome and risk-score dataset."
• "Generate DCA and clinical-impact plots for this prediction model."
• "Compare net benefit across thresholds for this case-control cohort."

When Not to Use

Do not use this skill for:

• time-to-event or survival outcomes;
• ROC-only discrimination analysis without decision-curve outputs;
• nomogram construction or calibration-curve analysis;
• multiclass outcomes or non-binary endpoints.

When to Read External Files

Usage

Rscript scripts/main.R \
  --data_file ./clinical_dca_data.csv \
  --outcome_col fustat \
  --predictor_col riskScore \
  --output_dir ./output/

Arguments

Input Format

Clinical Data (--data_file)

CSV file with row names as sample IDs. The dataset must contain at least one binary outcome column and one numeric predictor column.

,fustat,riskScore,FOXP3,CD45
Patient_1,1,0.630147268229631,5.7783584300481,3.5407433709834
Patient_2,0,0.23007730941193,6.70308857663772,3.11795942819676
Patient_3,1,0.534809528754818,5.46860669585825,3.40086667402884

Requirements

• File extension must be .csv.
• Row names must be non-missing, unique sample IDs.
• outcome_col and predictor_col must exist.
• Outcome values must use 0/1 encoding. Outcome values are coerced to numeric before validation; logical TRUE/FALSE are converted to 1/0. Factor or character values will produce SKILL_INVALID_PARAMETER.
• Predictor values must be finite numeric values.
• At least 20 rows, 5 positive outcomes, and 5 negative outcomes are required.

Design note: When --study_design cohort is selected, --population_prevalence has no statistical effect; the raw observed event rate is used instead. A warning is emitted if you set a non-default population_prevalence with cohort design.

Output Files

dca_summary.txt

Summary fields include:

• threshold-specific net benefit statistics from summary(dca_model);
• the selected measure (NB or sNB);
• the fitted formula and study-design context recorded in session_info.txt.

Workflow

Step 1: Validate Input

• Confirm the clinical CSV exists and is readable.
• Check that the requested outcome and predictor columns are present.
• Validate sample IDs, binary outcome coding, and numeric predictor values.
• Emit warning if population_prevalence is non-default and study_design is cohort.

Step 2: Prepare Analysis Dataset

• Keep only the outcome and predictor columns required for DCA.
• Coerce outcome and predictor values to numeric.
• Reject cohorts with too few rows or too few events/non-events.

Step 3: Fit Decision-Curve Model

• Fit a logistic decision-curve model with rmda::decision_curve().
• Build a threshold grid from 0 to 1 using threshold_by.
• Apply population_prevalence when study_design is case-control.

Step 4: Save Outputs

• Save the fitted DCA object as .rds.
• Export the text summary as .txt.
• Render the decision curve and clinical-impact curve as PDFs.
• Record session metadata for reproducibility.

Agent Response Contract

After a successful run, report:

1. Study design and predictor used (e.g., case-control, riskScore)
2. Net benefit metric reported (NB or sNB)
3. Threshold range and step used for the grid
4. Key finding: net benefit at clinically relevant threshold(s) from dca_summary.txt
5. Artifact paths: plot/decision_curve.pdf, plot/clinical_impact_curve.pdf, data/dca_model.rds

Examples

Basic Usage

Rscript scripts/main.R \
  --data_file clinical_dca_data.csv \
  --outcome_col fustat \
  --predictor_col riskScore \
  --output_dir ./output/

Cohort Design With Custom Plotting

Rscript scripts/main.R \
  --data_file clinical_dca_data.csv \
  --study_design cohort \
  --outcome_col fustat \
  --predictor_col riskScore \
  --plot_title "Cohort DCA" \
  --decision_curve_color "#3C5488" \
  --impact_colors "#3C5488,#00A087" \
  --show_confidence_intervals \
  --output_dir ./cohort_output/

With Bundled Test Data

Rscript scripts/main.R \
  --data_file tests/data/dca_data.csv \
  --outcome_col fustat \
  --predictor_col riskScore \
  --output_dir tests/output/ \
  --overwrite

Error Handling

IF error persists, READ: references/troubleshooting.md

Input Validation

This skill accepts: a single clinical CSV file with a binary outcome column (0/1 encoded) and a numeric predictor column, for decision curve analysis of a binary prediction model.

If the user's request does not involve decision curve analysis of a binary prediction model — for example, asking to run survival analysis, build ROC curves only, construct a nomogram, or analyze multiclass outcomes — do not proceed with the workflow. Instead respond:

"Decision Curve Analysis is designed to evaluate the clinical utility of binary prediction models by computing net benefit across decision thresholds. Your request appears to be outside this scope. Please provide a binary outcome dataset for DCA, or use a more appropriate tool for survival analysis, ROC analysis, or nomogram construction."

Testing

Smoke Test With Included Data

Rscript scripts/main.R --help

Rscript scripts/main.R \
  --data_file tests/data/dca_data.csv \
  --outcome_col fustat \
  --predictor_col riskScore \
  --output_dir tests/output/ \
  --overwrite

Automated Smoke Test Script

Rscript tests/run_smoke_test.R

Optional shell wrapper:

bash tests/run_smoke_test.sh

Expected Output

tests/output/
|-- data/dca_model.rds
|-- plot/clinical_impact_curve.pdf
|-- plot/decision_curve.pdf
|-- session_info.txt
`-- table/dca_summary.txt

References

1. Vickers AJ, Elkin EB. Decision curve analysis: a novel method for evaluating prediction models.
2. rmda package documentation for clinical decision-curve analysis.

For detailed algorithm, READ: references/algorithm.md

Implementation Checklist

• CLI parsing with optparse
• set.seed() for reproducibility
• Top-level CRAN dependency checks
• Session info recording
• Timeout parameter exposed as CLI option
• Relative-path source() usage via get_script_dir()
• Modular script structure in scripts/
• Test data provided in tests/data/
• Error handling with SKILL_* codes
• Reference docs provided in references/

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