pammtools (version 0.8.1)

add_cif: Add cumulative incidence function to data

Description

Add cumulative incidence function to data

Usage

add_cif(newdata, object, ...)
# S3 method for default
add_cif(
  newdata,
  object,
  ci = TRUE,
  overwrite = FALSE,
  alpha = 0.05,
  nsim = 500L,
  cause_var = "cause",
  time_var = NULL,
  interval_length = "intlen",
  check_grouping = TRUE,
  ...
)
# S3 method for pamm_ic
add_cif(
  newdata,
  object,
  ci = TRUE,
  alpha = 0.05,
  nsim = 500L,
  cause_var = "cause",
  time_var = NULL,
  interval_length = "intlen",
  check_grouping = TRUE,
  ...
)

Arguments

newdata

A data frame or list containing the values of the model covariates at which predictions are required. If this is not provided then predictions corresponding to the original data are returned. If newdata is provided then it should contain all the variables needed for prediction: a warning is generated if not. See details for use with link{linear.functional.terms}.

object

a fitted gam object as produced by gam().

...

Further arguments passed to predict.gam and get_hazard

ci

logical. Indicates if confidence intervals should be calculated. Defaults to TRUE.

overwrite

Should hazard columns be overwritten if already present in the data set? Defaults to FALSE. If TRUE, columns with names c("hazard", "se", "lower", "upper") will be overwritten.

alpha

Significance level for pooled confidence intervals.

nsim

Total number of pooled posterior draws used for the interval.

cause_var

Character. Column name of the 'cause' variable.

time_var

Name of the variable used for the baseline hazard. Defaults to "tend".

interval_length

Character, defaults to "intlen". contains the interval length in newdata.

check_grouping

Logical. If TRUE (default), stop if newdata is not grouped so that the time variable is unique within each group, guarding against silently accumulating the cumulative incidence across distinct covariate profiles or causes. Note that check_grouping = FALSE only skips this profile-level safeguard; the independent check that newdata is grouped by cause (inside get_cif()) still applies.

Details

When computing cumulative incidence for multiple groups, the input data must be grouped via group_by() (by cause and any covariates) before calling this function. If newdata still contains several profiles per group (repeated time_var values within a group, typically a forgotten group_by()), the function now stops with an error rather than returning silently incorrect results, as the cumulative incidence would otherwise be accumulated across profiles rather than within each group.

The returned data contains one boundary row per group at time_var = 0 for plotting cumulative incidence from the time origin. On this row, cif = 0; if confidence intervals are requested, cif_lower = cif_upper = 0. If an interval-length column is present, it is set to 0 on the boundary row. add_cumu_hazard() adds an analogous boundary row (with cumu_hazard = 0) for continuous-time models (GAM/SCAM/PAMM), controllable via its boundary argument; interval-factor models (e.g. PEM via glm) keep the original prediction grid without a boundary row.

Examples

# \donttest{
if (require("etm")) {
  data("fourD", package = "etm")
  ped_stacked <- fourD |>
    dplyr::select(-medication, -treated) |>
    as_ped(Surv(time, status) ~., id = "id") |>
    dplyr::mutate(cause = as.factor(cause))
  pam <- pamm(
    ped_status ~ s(tend, by = cause) + sex + sex:cause + age + age:cause,
    data = ped_stacked)
  ped_stacked |>
    make_newdata(tend = unique(tend), cause = unique(cause)) |>
    group_by(cause) |>
    add_cif(pam)
}
# }