predict_tp: Calculate subject specific transition probabilities from a multi-state proportional hazards model.

Description

Given a coxph model fit on multi-state data (prepared with msprep), determine transition probabilities for subjects in newdata.

Usage

predict_tp(
  object,
  predt,
  direction = c("forward", "fixedhorizon"),
  newdata,
  trans
)

Value

An object of class "probtrans.subjects". This is a list of length n (number of subjects in newdata), with each list element an object of class probtrans for the associated subject. List elements can be accessed using [[x]], with x

ranging from 1 to n. Additionally, each list element has an element $id, representing the subject id and the output object also has an element $subject_ids representing the subject ids in order.

Arguments

object

A coxph object fit on multi-state data. Must contain a strata(X) term. Data used for the coxph() fit preferably prepared using msprep.

predt

A positive number indicating the prediction time. This is either the time at which the prediction is made (if direction = "forward") or the time for which the prediction is to be made (if direction = "backward").

direction

One of "forward" (default) or "fixedhorizon", indicating whether prediction is forward or for a fixed horizon

newdata

A data.frame containing a single row per subject in the data. It must contain the following named columns:

id:: (optional) Unique identifier of the subject, can be numeric or character;

"variables":

The variables and their values for the subject(s) (optionally identified by "id"). After using expand.covs, the names of the new data must match the names of the variables in the coxph object.

Note that newdata must contain a column containing the variable which was used to determine the stratum of a transition in object. Usually the stratum is determined from a column that is generated automatically in the pre-processing steps of this function.

trans

A transition matrix as created by transMat.

Details

When using this function for newdata with many subjects, consider running the function multiple times for parts of newdata to negate the risk of running our of memory. Using this function, it is only possible to consider models with transition specific covariates. If you would like to have covariates shared over transitions or proportional hazards assumptions between transitions, see probtrans_coxph.

Examples

Run this code

#Example from the mstate vignette
#We determine the subject specific transition probabilities for subjects
#in the ebmt3 data-set 
if(require("mstate")){
  data(ebmt3)
  n <- nrow(ebmt3)
  tmat <- transMat(x = list(c(2, 3), c(3), c()), names = c("Tx",
                                                           "PR", "RelDeath"))
  #From days to years                                                          
  ebmt3$prtime <- ebmt3$prtime/365.25
  ebmt3$rfstime <- ebmt3$rfstime/365.25
  #Covariates we will use
  covs <- c("dissub", "age", "drmatch", "tcd", "prtime")
  msbmt <- msprep(time = c(NA, "prtime", "rfstime"), status = c(NA,
                  "prstat", "rfsstat"), data = ebmt3, trans = tmat, keep = covs)
  #Expand covariates so that we can have transition specific covariates
  msbmt2 <- expand.covs(msbmt, covs, append = TRUE, longnames = FALSE)
  
  #-------------Model---------------------#
  
  #Simple model, transition specific covariates, each transition own baseline hazard
  c1 <- coxph(Surv(Tstart, Tstop, status) ~ dissub1.1 + dissub2.1 +
                age1.1 + age2.1 + drmatch.1 + tcd.1 + dissub1.2 + dissub2.2 +
                age1.2 + age2.2 + drmatch.2 + tcd.2 + dissub1.3 + dissub2.3 +
                age1.3 + age2.3 + drmatch.3 + tcd.3 + strata(trans), data = msbmt2,
                method = "breslow")
  
   #Predict transition probabilities for first 30 subjects.
   tp_subjects <- predict_tp(c1, predt = 0, direction = "forward", 
                                  newdata = ebmt3[1:30,], trans = tmat)
                                  
   #Now we can plot the transition probabilities for each subject separately:
   plot(tp_subjects, id = 1)
   #tp_subjects has length number of subjects in newdata + 1
   #And tp_subjects[[i]] is an object of class "probtrans", so you can 
   #use all probtrans functions: summary, plot etc.
}