Estimate calibration curves for a multistate model using binary logistic regression calibration techniques and inverse probability of censoring weights.'

Creates the underlying data for the calibration curves. calib_blr estimates the observed event probabilities for a given set of predicted transition probabilities in a cohort of interest. This is done using techniques for assessing calibration of binary logistic regression models, in combination with inverse probability of censoring weights and landmarking.

Usage

calib_blr(
  data.mstate,
  data.raw,
  j,
  s,
  t,
  tp.pred,
  curve.type = "rcs",
  rcs.nk = 3,
  loess.span = 0.75,
  loess.degree = 2,
  weights = NULL,
  w.function = NULL,
  w.covs = NULL,
  w.landmark.type = "state",
  w.max = 10,
  w.stabilised = FALSE,
  w.max.follow = NULL,
  CI = FALSE,
  CI.type = "bootstrap",
  CI.R.boot = NULL,
  data.pred.plot = NULL,
  transitions.out = NULL,
  ...
)

Arguments

data.mstate: Validation data in msdata format
data.raw: Validation data in data.frame (one row per individual)
j: Landmark state at which predictions were made
s: Landmark time at which predictions were made
t: Follow up time at which calibration is to be assessed
tp.pred: Matrix of predicted transition probabilities at time t, if in state j at time s. There must be a seperate column for the predicted transition probabilities into every state, even if these predicted transition probabilities are 0.
curve.type: Whether calibration curves are estimated using restricted cubic splines ('rcs') or loess smoothers ('loess')
rcs.nk: Number of knots when curves are estimated using restricted cubic splines
loess.span: Span when curves are estimated using loess smoothers
loess.degree: Degree when curves are estimated. using loess smoothers
weights: Vector of inverse probability of censoring weights
w.function: Custom function for estimating the inverse probability of censoring weights
w.covs: Character vector of variable names to adjust for when calculating inverse probability of censoring weights
w.landmark.type: Whether weights are estimated in all individuals uncensored at time s ('all') or only in individuals uncensored and in state j at time s ('state')
w.max: Maximum bound for inverse probability of censoring weights
w.stabilised: Indicates whether inverse probability of censoring weights should be stabilised or not
w.max.follow: Maximum follow up for model calculating inverse probability of censoring weights. Reducing this to t + 1 may aid in the proportional hazards assumption being met in this model.
CI: Size of confidence intervals as a %
CI.type: Method for estimating confidence interval (currently restricted to bootstrap)
CI.R.boot: Number of bootstrap replicates when estimating the confidence interval for the calibration curve
data.pred.plot: Data frame or matrix of predicted risks for each possible transition over which to plot the calibration curves. Must have one column for every possible transition.
transitions.out: Transitions for which to calculate calibration curves. Will do all possible transitions if left as NULL.
...: Extra arguments to be passed to w.function (custom function for estimating weights)

Value

calib_blr returns a list containing two elements: plotdata and metadata. The plotdata element contains the data for the calibration curves. This will itself be a list with each element containing calibration plot data for the transition probabilities into each of the possible states. Each list element contains patient ids (id) from data.raw, the predicted transition probabilities (pred) and the estimated observed event probabilities (obs). If a confidence interval is requested, upper (obs.upper) and lower (obs.lower) bounds for the observed event probabilities are also returned. If data.pred.plot is defined manually, column (id) is not returned. The metadata element contains metadata including: a vector of the possible transitions, a vector of which transitions calibration curves have been estimated for, the size of the confidence interval, the method for estimating the calibration curve and other user specified information.

Details

Observed event probabilities at time t are estimated for predicted transition probabilities tp.pred out of state j at time s. calib_blr estimates calibration curves using techniques for assessing the calibration of binary logistic regression models (Van Calster et al., 2016). A choice between restricted cubic splines and loess smoothers for estimating the calibration curve can be made using curve.type. Landmarking is applied to only assess calibration in individuals who are uncensored and in state j at time s. Censoring is dealt with using inverse probability of censoring weights (Hernan M, Robins J, 2020).

Two datasets for the same cohort of inidividuals must be provided. Firstly data.mstate must be a dataset of class msdata, generated using the [mstate] package. This dataset is used to apply the landmarking. Secondly, data.raw must be a data.frame with one row per individual, containing the desired variables for estimating the weights, and variables for the time until censoring (dtcens), and an indicator for censoring dtcens.s, where (dtcens.s = 1) if an individual is censored at time dtcens, and dtcens.s = 0 otherwise. When an individual enters an absorbing state, this prevents censoring from happening (i.e. dtcens.s = 0). Unless the user specifies the weights using weights, the weights are estimated using a cox-proportional hazard model, assuming a linear functional form of the variables defined in w.covs. We urge users to specify their own model for estimating the weights. The weights argument must be a vector with length equal to the number of rows of data.raw. Confidence intervals for the calibration curves can be estimated using bootstrapping. This procedure uses the internal method for estimating weights, we therefore encourage users to specify their own bootstrapping procedure, which incorporates their own model for estimating the weights. Details on how to do this are provided in the vignette BLR-IPCW-manual-bootstrap.

The calibration curves can be plotted using plot.calib_blr.

References

Hernan M, Robins J (2020). “12.2 Estimating IP weights via modeling.” In Causal Inference: What If, chapter 12.2. Chapman Hall/CRC, Boca Raton.

Van Calster B, Nieboer D, Vergouwe Y, De Cock B, Pencina MJ, Steyerberg EW (2016). “A calibration hierarchy for risk models was defined: From utopia to empirical data.” Journal of Clinical Epidemiology, 74, 167–176. ISSN 18785921. doi:10.1016/j.jclinepi.2015. 12.005. URL http://dx.doi.org/10.1016/j.jclinepi.2015.12.005

Examples

# Estimate BLR-IPCW calibration curves for the predicted transition
# probabilities at time t = 1826, when predictions were made at time
# s = 0 in state j = 1. These predicted transition probabilities are stored in tps0.

# Extract the predicted transition probabilities out of state j = 1
tp.pred <- dplyr::select(dplyr::filter(tps0, j == 1), any_of(paste("pstate", 1:6, sep = "")))

# Now estimate the observed event probabilities for each possible transition.
# 95% confidence intervals are estimated using bootstrapping with 200
# bootstrap repicates. In practice we recommend using a higher number.
dat.calib.blr <-
calib_blr(data.mstate = msebmtcal,
 data.raw = ebmtcal,
 j=1,
 s=0,
 t = 1826,
 tp.pred = tp.pred,
 w.covs = c("year", "agecl", "proph", "match"))

# The data for each calibration curve are stored in the "plotdata" list
# element.
str(dat.calib.blr)
#> List of 2
#>  $ plotdata:List of 6
#>   ..$ state1:'data.frame':	1778 obs. of  3 variables:
#>   .. ..$ id  : int [1:1778] 2 4 5 7 10 13 14 16 18 19 ...
#>   .. ..$ pred: num [1:1778] 0.114 0.1384 0.1233 0.0974 0.1137 ...
#>   .. ..$ obs : num [1:1778] 0.11 0.104 0.105 0.124 0.11 ...
#>   ..$ state2:'data.frame':	1778 obs. of  3 variables:
#>   .. ..$ id  : int [1:1778] 2 4 5 7 10 13 14 16 18 19 ...
#>   .. ..$ pred: num [1:1778] 0.232 0.184 0.161 0.212 0.232 ...
#>   .. ..$ obs : num [1:1778] 0.17 0.186 0.176 0.179 0.17 ...
#>   ..$ state3:'data.frame':	1778 obs. of  3 variables:
#>   .. ..$ id  : int [1:1778] 2 4 5 7 10 13 14 16 18 19 ...
#>   .. ..$ pred: num [1:1778] 0.0844 0.0758 0.0551 0.0615 0.0844 ...
#>   .. ..$ obs : num [1:1778] 0.1249 0.1167 0.0919 0.1001 0.1248 ...
#>   ..$ state4:'data.frame':	1778 obs. of  3 variables:
#>   .. ..$ id  : int [1:1778] 2 4 5 7 10 13 14 16 18 19 ...
#>   .. ..$ pred: num [1:1778] 0.233 0.218 0.183 0.221 0.233 ...
#>   .. ..$ obs : num [1:1778] 0.243 0.224 0.185 0.228 0.243 ...
#>   ..$ state5:'data.frame':	1778 obs. of  3 variables:
#>   .. ..$ id  : int [1:1778] 2 4 5 7 10 13 14 16 18 19 ...
#>   .. ..$ pred: num [1:1778] 0.148 0.154 0.143 0.144 0.149 ...
#>   .. ..$ obs : num [1:1778] 0.191 0.165 0.222 0.212 0.188 ...
#>   ..$ state6:'data.frame':	1778 obs. of  3 variables:
#>   .. ..$ id  : int [1:1778] 2 4 5 7 10 13 14 16 18 19 ...
#>   .. ..$ pred: num [1:1778] 0.189 0.23 0.335 0.264 0.189 ...
#>   .. ..$ obs : num [1:1778] 0.207 0.254 0.316 0.28 0.207 ...
#>  $ metadata:List of 8
#>   ..$ valid.transitions   : num [1:6] 1 2 3 4 5 6
#>   ..$ assessed.transitions: num [1:6] 1 2 3 4 5 6
#>   ..$ CI                  : logi FALSE
#>   ..$ CI.R.boot           : NULL
#>   ..$ curve.type          : chr "rcs"
#>   ..$ j                   : num 1
#>   ..$ s                   : num 0
#>   ..$ t                   : num 1826
#>  - attr(*, "class")= chr "calib_blr"