Plot a calibration curve for a Cox Proportional Hazards model

Usage

valProbSurvival(
  fit,
  valdata,
  alpha = 0.05,
  timeHorizon = 5,
  nk = 3,
  plotCal = c("none", "base", "ggplot"),
  addCox = FALSE,
  addRCS = TRUE,
  CL.cox = c("fill", "line"),
  CL.rcs = c("fill", "line"),
  xlab = "Predicted probability",
  ylab = "Observed proportion",
  xlim = c(-0.02, 1),
  ylim = c(-0.15, 1),
  lty.ideal = 1,
  col.ideal = "red",
  lwd.ideal = 1,
  lty.cox = 1,
  col.cox = "grey",
  lwd.cox = 1,
  fill.cox = "lightgrey",
  lty.rcs = 1,
  col.rcs = "black",
  lwd.rcs = 1,
  fill.rcs = rgb(177, 177, 177, 177, maxColorValue = 255),
  riskdist = "predicted",
  d0lab = "0",
  d1lab = "1",
  size.d01 = 5,
  dist.label = 0.01,
  line.bins = -0.05,
  dist.label2 = 0.04,
  length.seg = 0.85,
  legendloc = c(0.5, 0.27)
)

Arguments

fit: the model fit, has to be of type coxph
valdata: the validation data set
alpha: the significance level
timeHorizon: the time point at which the predictions have to be evaluated
nk: the number of knots, for the restricted cubic splines fit
plotCal: indicates if and how the calibration curve has to be plotted. plotCal = "none" plots no calibration curve, plotCal = "base" plots the calibration curve using base R (see plot) and plotCal = "ggplot" creates a plot using ggplot
addCox: logical, indicates if the Cox's estimated calibration curve has to be added to the plot
addRCS: logical, indicates if the restricted cubic splines' (RCS) estimated calibration curve has to be added to the plot
CL.cox: "fill" shows pointwise 95% confidence limits for the Cox calibration curve with a gray area between the lower and upper limits and "line" shows the confidence limits with a dotted line
CL.rcs: "fill" shows pointwise 95% confidence limits for the RCS calibration curve with a gray area between the lower and upper limits and "line" shows the confidence limits with a dotted line
xlab: x-axis label, default is "Predicted Probability".
ylab: y-axis label, default is "Observed proportion".
xlim, ylim: numeric vectors of length 2, giving the x and y coordinates ranges (see plot.window)
lty.ideal: linetype of the ideal line. Default is 1.
col.ideal: controls the color of the ideal line on the plot. Default is "red".
lwd.ideal: controls the line width of the ideal line on the plot. Default is 1.
lty.cox: if addCox = TRUE, the linetype of the Cox calibration curve
col.cox: if addCox = TRUE, the color of the Cox calibration curve
lwd.cox: if addCox = TRUE, the linewidth of the Cox calibration curve
fill.cox: if addCox = TRUE and CL.cox = "fill", the fill of the Cox calibration curve
lty.rcs: if addRCS = TRUE, the linetype of the RCS calibration curve
col.rcs: if addRCS = TRUE, the color of the RCS calibration curve
lwd.rcs: if addRCS = TRUE, the linewidth of the RCS calibration curve
fill.rcs: if addRCS = TRUE and CL.rcs = "fill", the fill of the RCS calibration curve
riskdist: Use "calibrated" to plot the relative frequency distribution of calibrated probabilities after dividing into 101 bins from lim[1] to lim[2]. Set to "predicted" (the default as of rms 4.5-1) to use raw assigned risk, FALSE to omit risk distribution. Values are scaled so that highest bar is 0.15*(lim[2]-lim[1]).
d0lab, d1lab: controls the labels for events and non-events (i.e. outcome y) for the histograms. Defaults are d1lab="1" for events and d0lab="0" for non-events.
size.d01: controls the size of the labels for events and non-events. Default is 5 and this value is multiplied by 0.25 when plotCal = "base".
dist.label: controls the horizontal position of the labels for events and non-events. Default is 0.04.
line.bins: controls the horizontal (y-axis) position of the histograms. Default is -0.05.
dist.label2: controls the vertical distance between the labels for events and non-events. Default is 0.03.
length.seg: controls the length of the histogram lines. Default is 1.
legendloc: if pl=TRUE, list with components x,y or vector c(x,y) for bottom right corner of legend for curves and points. Default is c(.50, .27) scaled to lim. Use locator(1) to use the mouse, FALSE to suppress legend.

Value

An object of type SurvivalCalibrationCurves with the following slots:

call: the matched call.
stats: a list containing performance measures of calibration.
alpha: the significance level used.
Calibration: contains the estimated calibration slope, together with their confidence intervals.
CalibrationCurves: The coordinates for plotting the calibration curves.

References

van Geloven N, Giardiello D, Bonneville E F, Teece L, Ramspek C L, van Smeden M et al. (2022). Validation of prediction models in the presence of competing risks: a guide through modern methods. BMJ, 377:e069249, doi:10.1136/bmj-2021-069249

Examples

if (FALSE) {
library(CalibrationCurves)
data(trainDataSurvival)
data(testDataSurvival)
sFit = coxph(Surv(ryear, rfs) ~ csize + cnode + grade3, data = trainDataSurvival,
 x = TRUE, y = TRUE)
calPerf = valProbSurvival(sFit, gbsg5, plotCal = "base", nk = 5)
}