pammtools (version 0.7.4)

add_trans_prob: 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 = NULL,
  interval_length = "intlen",
  ...
)

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

time_var

Name of the variable used for the baseline hazard. If not given, defaults to "tend" for gam fits, else "interval". The latter is assumed to be a factor, the former numeric.

interval_length

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

...

Further arguments passed to underlying methods.

Examples

if (FALSE) { # require("mstate")
  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!
    arrange(treat, transition, tend) |>
    add_trans_prob(pam)
}