add_trans_prob: Add transition probabilities

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

Add transition probabilities

Description

add_trans_prob adds transition probabilities on the provided data set and model. Optionally, confidence intervals (CI) are added if ci=TRUE. The function builds on cumulative hazards cumu_hazard and mgcv::gam models.

Usage

add_trans_prob(
  newdata,
  object,
  overwrite = FALSE,
  ci = FALSE,
  alpha = 0.05,
  nsim = 100L,
  time_var = "tend",
  interval_length = "intlen",
  transition = "transition",
  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 linear.functional.terms.
object	A fitted gam object as produced by mgcv::gam
overwrite	Should transition probability columns be overwritten if already present in the data set? Defaults to FALSE. If TRUE, columns with names c("trans_prob", "trans_upper", "trans_lower") will be overwritten.
ci	Logical, defaults to TRUE. Decides if confidence intervals for transition probabilities are calculated.
alpha	Sets the confidence intervals' \alpha level, Defaults to 0.05
nsim	Sets the number of iterations for simulated confidence intervals. Defaults to 100L. Interval bounds are empirical type-6 quantiles of the nsim draws; larger values of nsim yield more stable interval bounds.
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.
transition	Character, defaults to "transition". contains the transition labels in newdata.
check_grouping	Logical. If TRUE (default), the function checks that newdata is grouped so that the time variable is unique within each group once transition is part of the grouping, and stops otherwise, guarding against silently accumulating transition probabilities across distinct covariate profiles (a forgotten group_by()). Set to FALSE to skip the check. As for the other cumulative add_* functions, hand-built grids stacking profiles with disjoint time grids cannot be detected (see add_cumu_hazard).
...	Further arguments passed to underlying methods.

Details

When computing transition probabilities for multiple groups, the input data must be grouped via group_by() before calling this function. If newdata still contains several covariate profiles per (group, transition) – i.e.\ repeated time_var values within a group once transition is added to the grouping, typically a forgotten group_by() – the function now stops with an error rather than returning silently incorrect results, as the transition probability would otherwise be accumulated across profiles rather than within each group.

The returned data contains one boundary row per group and transition at time_var = 0 for plotting transition probabilities from the time origin. On this row, trans_prob = 0; if confidence intervals are requested, trans_lower = trans_upper = 0. If an interval-length column is present, it is set to 0 on the boundary row.

Examples

  data("prothr", package = "mstate")
  prothr <- prothr |>
    mutate(transition = as.factor(paste0(from, "->", to))
    , treat = as.factor(treat)) |>
    filter(Tstart != Tstop, id <= 100) |> select(-trans)
  ped <- as_ped(data= prothr, formula= Surv(Tstart, Tstop, status)~ .,
    transition = "transition", id= "id", timescale  = "calendar")
  pam <- mgcv::bam(ped_status ~ s(tend, by=transition) + transition * treat,
    data = ped, family = poisson(), offset = offset,
    method = "fREML", discrete = TRUE)
  ndf <- make_newdata(ped, tend  = unique(tend),
    treat  = unique(treat),
    transition = unique(transition)) |>
    group_by(treat, transition) |>  # important!
    add_trans_prob(pam)

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