prob_exceed_recurrent: Estimate the probability of exceeding k recurrent events by time t

Description

Estimates \(P(N(t) \geq k)\) as a function of time \(t\), for a range of thresholds \(k\), in the presence of a terminal event (death). The estimator is based on the cumulative incidence of "reaching \(k\) events", treating death as a competing risk. Confidence intervals are computed on the log or plain scale.

Usage

prob_exceed_recurrent(
  formula,
  data,
  cause = 1,
  death.code = 2,
  cens.code = 0,
  exceed = NULL,
  marks = NULL,
  all.cifs = FALSE,
  return.data = FALSE,
  conf.type = c("log", "plain"),
  level = 0.95,
  ...
)

Value

An object of class "exceed" with the following components:

time: Vector of evaluation time points.
prob: Array of dimension (length(time), length(exceed) + 1, nstrata) containing \(P(N(t) \geq k)\) for each threshold and stratum. The first column gives \(P(N(t) < \text{exceed}[1])\).
se.prob: Standard errors of prob.
lower, upper: Pointwise confidence interval bounds.
meanN: Estimated mean number of events \(E(N(t))\) (single stratum only; NULL for stratified analyses).
meanN2, varN: Second moment and variance of \(N(t)\) (single stratum only).
exceed: Thresholds evaluated (excluding zero).
cif.exceed: List of fitted cif objects (if all.cifs = TRUE).
dataList: List of datasets for each threshold (if return.data = TRUE).
nstrata, strata.levels, strata.name: Stratification information.

Use plot() and summary() methods for visualisation and tabulation.

Arguments

formula: A formula with an Event response giving the exit time and status (and optionally entry time). The right-hand side may include cluster() and strata().
data: A data frame containing all variables in formula.
cause: Integer code for the recurrent event of interest. Default is 1.
death.code: Integer code for the terminal event. Default is 2.
cens.code: Integer code for censoring. Default is 0.
exceed: Integer vector of thresholds \(k\) to evaluate. If NULL (default), all observed cumulative counts are used.
marks: Optional numeric vector of event weights. If non-NULL, cumulative counts are formed as weighted sums of events rather than simple counts. Must have the same length as nrow(data).
all.cifs: Logical. If TRUE, the fitted cif object for each threshold is returned in cif.exceed. Default is FALSE.
return.data: Logical. If TRUE, the constructed dataset for each threshold is returned in dataList. Default is FALSE.
conf.type: Type of confidence interval transformation: "log" (default) or "plain".
level: Confidence level. Default is 0.95.
...: Further arguments passed to cif.

Author

Thomas Scheike

Details

For each threshold \(k\) in exceed, the function identifies the first time each subject reaches \(k\) events, then fits a competing risks model (cif) with "reaching \(k\) events" as the event of interest and death as the competing event. Strata are supported. When marks is NULL, each event contributes equally; otherwise events are weighted by their mark values before cumulative counts are formed.

References

Scheike, T. H., Eriksson, L., and Tribler, P. (2019). The mean, variance and correlation for bivariate recurrent events with a terminal event. Journal of the Royal Statistical Society, Series C, 68(5).

Examples

Run this code

data(hfactioncpx12)
dtable(hfactioncpx12, ~status)

oo <- prob_exceed_recurrent(Event(entry, time, status) ~ cluster(id),
                             hfactioncpx12, cause = 1, death.code = 2)
plot(oo)
summary(oo, times = c(1, 2, 5))

Run the code above in your browser using DataLab