add_cif: Add cumulative incidence function to data

In pammtools: Piece-Wise Exponential Additive Mixed Modeling Tools for Survival Analysis

Add cumulative incidence function to data

Description

Add cumulative incidence function to data

Usage

add_cif(newdata, object, ...)

## Default S3 method:
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 class '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

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)
}

pammtools documentation built on Aug. 27, 2026, 1:08 a.m.