Decision Curve Analysis

Source: https://github.com/aipoch/medical-research-skills

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.
• Predictor values must be finite numeric values.
• At least 20 rows, 5 positive outcomes, and 5 negative outcomes are required.

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.

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.

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

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/