Skip to contents

Decision Curve Analysis for evaluating the clinical utility of prediction models and diagnostic tests. Calculates net benefit across threshold probabilities to determine if using a model provides more benefit than default strategies. Inputs must be probabilities for a clearly defined binary outcome and prediction horizon; calibration must be assessed separately, and this analysis does not handle censoring.

Usage

decisioncurve(
  data,
  outcome = NULL,
  outcomePositive,
  models = NULL,
  modelNames = "",
  thresholdRange = "clinical",
  thresholdMin = 0.05,
  thresholdMax = 0.5,
  thresholdStep = 0.01,
  showTable = TRUE,
  selectedThresholds = "0.05, 0.10, 0.15, 0.20, 0.25, 0.30",
  showPlot = TRUE,
  plotStyle = "standard",
  showReferenceLinesLabels = FALSE,
  highlightRange = FALSE,
  highlightMin = 0.1,
  highlightMax = 0.3,
  calculateClinicalImpact = FALSE,
  populationSize = 1000,
  showInterventionAvoided = FALSE,
  confidenceIntervals = FALSE,
  bootReps = 1000,
  seed = 42,
  ciLevel = 0.95,
  ciBand = "pointwise",
  showBenefitRange = FALSE,
  compareModels = FALSE,
  weightedAUC = FALSE,
  clinicalDecisionRule = FALSE,
  decisionRuleVar = NULL,
  decisionRulePositive,
  decisionRuleLabel = "Clinical Rule",
  showClinicalImpactPlot = FALSE,
  costBenefitAnalysis = FALSE,
  testCost = 100,
  treatmentCost = 1000,
  benefitCorrectTreatment = 10000,
  harmFalseTreatment = 500,
  showStandardizedNetBenefit = FALSE,
  multiModelComparison = FALSE,
  showDecisionConsequences = FALSE,
  showInterpretation = FALSE,
  resourceUtilization = FALSE,
  showRelativeUtility = FALSE
)

Arguments

data

The data as a data frame.

outcome

Binary outcome variable (0/1 or FALSE/TRUE). This represents the condition or event you want to predict.

outcomePositive

Which level of the outcome variable represents the positive case (presence of condition/event). It is never taken from the order of the levels: until it is chosen the analysis lists the levels found and computes nothing. From R the argument has no default; pass the level.

models

Variables holding predicted probabilities between 0 and 1 (inclusive), one column per model. They must refer to the outcome and prediction horizon being evaluated, not logits, linear predictors or raw risk scores. The analysis rejects values outside 0 to 1 rather than rescaling them because rescaling would destroy the clinical meaning of the threshold. Being within 0 to 1 does not prove calibration; assess calibration separately in the target population. For time-to-event predictions, use a binary fixed-horizon outcome with appropriate outcome ascertainment because censoring is not handled by this function.

modelNames

Optional comma-separated list of names for the models. If not provided, variable names will be used.

thresholdRange

Range of threshold probabilities to evaluate. Select the range from the actual clinical action and the relative consequences of missed cases and unnecessary interventions; the presets are computational conveniences, not recommendations.

thresholdMin

Minimum threshold probability when using custom range.

thresholdMax

Maximum threshold probability when using custom range.

thresholdStep

Step size between threshold probabilities.

showTable

Display table with net benefit values at selected thresholds.

selectedThresholds

Comma-separated list of threshold probabilities to display in table.

showPlot

Display the decision curve plot.

plotStyle

Style of the decision curve plot.

showReferenceLinesLabels

Show labels for "Treat All" and "Treat None" reference lines.

highlightRange

Highlight a clinically relevant threshold range on the plot.

highlightMin

Minimum threshold for highlighted range.

highlightMax

Maximum threshold for highlighted range.

calculateClinicalImpact

Calculate clinical impact metrics (number needed to screen, etc.).

populationSize

Population size used to project clinical impact, resource use and exploratory monetary payoff from the complete-case cohort proportions.

showInterventionAvoided

Display the net reduction in interventions compared with treat-all, derived from the net-benefit difference after accounting for the threshold odds.

confidenceIntervals

Calculate bootstrap confidence intervals for net benefit at each threshold, for every model and for the clinical decision rule if one is supplied. Pointwise percentile intervals and a simultaneous sup-t band are both computed; ciBand selects which the plot draws.

bootReps

Number of bootstrap replications for confidence intervals.

seed

Random seed for the bootstrap resampling used in the confidence intervals and the model-comparison p-values. Without a fixed seed the same data and the same options produce a different interval and a different p-value on every run.

ciLevel

Confidence level for bootstrap confidence intervals.

ciBand

Which bootstrap interval the decision curve plot draws. 'pointwise' gives a percentile interval at each threshold; read jointly across thresholds these overstate confidence. 'simultaneous' gives a studentized sup-t band (Montiel Olea and Plagborg-Moller 2019) from the same replicates that covers the entire curve with approximately the stated probability; coverage falls below nominal in small samples and where few patients are classified positive. Both are computed; this only selects which is drawn.

showBenefitRange

Report, for each model, the range of threshold probabilities over which its net benefit exceeds both treat-all and treat-none. The range is descriptive and may contain separated stretches. Threshold probability should be elicited from the clinical trade-off, not optimized on the same data.

compareModels

Provide exploratory pairwise bootstrap comparisons of average net benefit across the selected range, between every pair of strategies: the models and, if one is supplied, the clinical decision rule. The p-values are approximate and should not replace comparison at prespecified clinically relevant thresholds or independent validation.

weightedAUC

Summarize each decision curve by the area under it, normalized by the width of the threshold range - that is, the model's average net benefit over that range. The option is named weightedAUC for historical reasons but the average is UNWEIGHTED: every threshold in the range counts equally. The value therefore depends entirely on the threshold range chosen above, so always report the range alongside it. Curves may cross, so this descriptive average does not identify a universally best model.

clinicalDecisionRule

Add clinical decision rule analysis and comparison with models.

decisionRuleVar

Binary variable indicating whether the clinical rule recommends intervention (1/0 or yes/no).

decisionRulePositive

Which level of the rule variable indicates a positive recommendation (treat/intervene). Never taken from the order of the levels: until it is chosen the rule is left out of the analysis. jamovi does not permit a default on a Level option, so this is always a required argument of the R function even when clinicalDecisionRule is FALSE. Programmatic callers that are not using a clinical decision rule must pass decisionRulePositive = NULL explicitly.

decisionRuleLabel

Label for the clinical decision rule in plots and tables.

showClinicalImpactPlot

Display projected true positives and false positives for the selected population size at the selected threshold probabilities.

costBenefitAnalysis

Project a simple exploratory monetary payoff using user-assigned values in one common currency. This is not an ICER, QALY, cost-effectiveness or formal net-monetary-benefit analysis.

testCost

Cost per test or screening procedure in the same currency and time frame as all other payoff inputs.

treatmentCost

Cost of treatment or intervention in the same currency and time frame as all other payoff inputs.

benefitCorrectTreatment

Monetary value assigned to correctly treating a true positive, in the same currency and time frame as every other payoff input. Do not enter QALYs.

harmFalseTreatment

Monetary value assigned to the harm of treating a false positive, in the same currency and time frame as every other payoff input.

showStandardizedNetBenefit

Display standardized net benefit, defined as net benefit divided by outcome prevalence. It is dimensionless and expresses net benefit relative to the maximum achievable value; it is not net benefit per 100 patients.

multiModelComparison

Perform exploratory pairwise bootstrap comparisons between all models, and any clinical decision rule, of the unweighted mean (and median) net-benefit difference over the threshold grid points. Inference is approximate and conditional on the selected threshold range.

showDecisionConsequences

Show detailed table of decision consequences (TP, FP, TN, FN) at selected thresholds.

showInterpretation

Show a plain-language interpretation of the decision curves (the model with the highest average net benefit over the range, its range of benefit, reading guidelines and methodological notes). The Analysis Summary, which states the data requirements, is always shown.

resourceUtilization

Project tests, treatments, unnecessary treatments and missed cases to the selected population size.

showRelativeUtility

Display relative utility curve comparing each model to default strategies.

Value

A results object containing:

results$instructionsa html
results$procedureNotesa html
results$noticesa html
results$resultsTablea table
results$benefitRangeTablea table
results$clinicalImpactTablea table
results$comparisonTablea table
results$weightedAUCTablea table
results$dcaPlotNet-benefit curves with optional bootstrap ribbons, pointwise or a simultaneous sup-t band, for every model and any clinical rule
results$clinicalImpactPlotProjected true and false positives for the selected population size
results$interventionsAvoidedPlotan image
results$summaryTexta html
results$costBenefitTableSimple monetary payoff projection under explicit assumptions; not an ICER, QALY or formal health-economic analysis
results$decisionConsequencesTableDetailed consequences at selected thresholds
results$modelComparisonEnhancedExploratory case-resampling comparison of the unweighted mean net-benefit difference over the threshold grid points
results$resourceUtilizationTableResource utilization projected to the selected population size
results$relativeUtilityPlotRelative utility compared to default strategies
results$standardizedNetBenefitPlotDimensionless net benefit divided by outcome prevalence; not net benefit per 100 patients

Tables can be converted to data frames with asDF or as.data.frame. For example:

results$resultsTable$asDF

as.data.frame(results$resultsTable)

Examples

if (FALSE) { # \dontrun{
# outcomePositive and decisionRulePositive are Level options: jamovi forbids a
# default on them, so both are REQUIRED arguments. Pass NULL for the rule level
# when no clinical decision rule is used.
decisioncurve(
    data = dca_test_data,
    outcome = "cardiac_event",
    outcomePositive = "Yes",
    models = c("basic_model", "enhanced_model"),
    decisionRulePositive = NULL
)
} # }