IndivCtstmTrans {hesim}R Documentation

Transitions for an individual-level continuous time state transition model

Description

Simulate health state transitions in an individual-level continuous time state transition model using parameters from a multi-state model.

Format

An R6::R6Class object.

Super class

hesim::CtstmTrans -> IndivCtstmTrans

Public fields

params

An object of class params_surv or params_surv_list.

input_data

Input data used to simulate health state transitions by sample from the probabilistic sensitivity analysis (PSA), treatment strategy and patient. Must be an object of class input_mats. If params contains parameters from a list of models (i.e., of class params_surv_list), then input_data must contain a unique row for each treatment strategy and patient; if params contains parameters from a joint model (i.e., of class params_surv), then input_data must contain a unique row for each treatment strategy, patient, and transition.

trans_mat

A transition matrix describing the states and transitions in a multi-state model in the format from the mstate package. See the documentation for the argument "trans" in mstate::msprep.

start_state

A scalar or vector denoting the starting health state. Default is the first health state. If a vector, must be equal to the number of simulated patients.

start_age

A scalar or vector denoting the starting age of each patient in the simulation. Default is 38. If a vector, must be equal to the number of simulated patients.

death_state

The death state in trans_mat. Used with max_age in sim_disease as patients transition to this state upon reaching maximum age. By default, it is set to the final absorbing state (i.e., a row in trans_mat with all NAs).

clock

"reset" for a clock-reset model, "forward" for a clock-forward model, "mix" for a mixture of clock-reset and clock-forward models by state, and "mixt" for a mixture of clock-reset and clock-forward models by transition. A clock-reset model is a semi-Markov model in which transition rates depend on time since entering a state. A clock-forward model is a Markov model in which transition rates depend on time since entering the initial state. If "mix" is used, then reset_states must be specified. If "mixt" is used, then transition_types must be specified.

reset_states

A vector denoting the states in which time resets. Hazard functions are always a function of elapsed time since either the start of the model or from when time was previously reset. Only used if clock = "mix".

transition_types

A vector denoting the type of transition. The vector is of the same length as the number of transitions and takes values "reset", "time" or "age" for hazards that are functions of reset time, time since study entry or age, respectively. Only used if clock = "mixt".

Methods

Public methods

Inherited methods

Method new()

Create a new IndivCtstmTrans object.

Usage
IndivCtstmTrans$new(
  params,
  input_data,
  trans_mat,
  start_state = 1,
  start_age = 38,
  death_state = NULL,
  clock = c("reset", "forward", "mix", "mixt"),
  reset_states = NULL,
  transition_types = NULL
)
Arguments
params

The params field.

input_data

The input_data field.

trans_mat

The trans_mat field.

start_state

The start_state field.

start_age

The start_age field.

death_state

The death_state field.

clock

The clock field.

reset_states

The reset_states field.

transition_types

The transition_types field.

Returns

A new IndivCtstmTrans object.

Method sim_disease()

Simulate disease progression (i.e., individual trajectories through a multi-state model using an individual patient simulation).

Usage
IndivCtstmTrans$sim_disease(max_t = 100, max_age = 100, progress = NULL)
Arguments
max_t

A scalar or vector denoting the length of time to simulate the model. If a vector, must be equal to the number of simulated patients.

max_age

A scalar or vector denoting the maximum age to simulate each patient until. If a vector, must be equal to the number of simulated patients.

progress

An integer, specifying the PSA iteration (i.e., sample) that should be printed every progress PSA iterations. For example, if progress = 2, then every second PSA iteration is printed. Default is NULL, in which case no output is printed.

Returns

An object of class disprog.

Method sim_stateprobs()

Simulate health state probabilities from a disprog object.

Usage
IndivCtstmTrans$sim_stateprobs(t, disprog = NULL, ...)
Arguments
t

A numeric vector of times.

disprog

A disprog object. If NULL, then this will be simulated prior to computing state probabilities using IndivCtstm$sim_disease().

...

Additional arguments to pass to IndivCtstm$sim_disease() if disprog = NULL.

Returns

An object of class stateprobs.

Method check()

Input validation for class. Checks that fields are the correct type.

Usage
IndivCtstmTrans$check()

Method clone()

The objects of this class are cloneable with this method.

Usage
IndivCtstmTrans$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

IndivCtstmTrans objects are conveniently created from either fitted models or parameter objects with create_IndivCtstmTrans(). A complete economic model can be implemented with the IndivCtstm class.

Examples

library("flexsurv")

# Simulation data
strategies <- data.frame(strategy_id = c(1, 2, 3))
patients <- data.frame(patient_id = seq(1, 3),
                       age = c(45, 50, 60),
                       female = c(0, 0, 1))

# Multi-state model with transition specific models
tmat <- rbind(c(NA, 1, 2),
              c(NA, NA, 3),
              c(NA, NA, NA))
fits <- vector(length = max(tmat, na.rm = TRUE), mode = "list")
for (i in 1:length(fits)){
  fits[[i]] <- flexsurvreg(Surv(years, status) ~ 1,
                           data = bosms3[bosms3$trans == i, ],
                           dist = "exp")
}
fits <- flexsurvreg_list(fits)

# Simulation model
hesim_dat <- hesim_data(strategies = strategies,
                        patients = patients)
fits_data <- expand(hesim_dat)
transmod <- create_IndivCtstmTrans(fits, input_data = fits_data,
                                   trans_mat = tmat,
                                   n = 2)
head(transmod$hazard(c(1, 2, 3)))
head(transmod$cumhazard(c(1, 2, 3)))

## Simulate disease progression and state probabilities together
transmod$sim_stateprobs(t = c(0, 5, 10))[t == 5]

## Simulate disease progression and state probabilities separately
disprog <- transmod$sim_disease(max_t = 10)
transmod$sim_stateprobs(t = c(0, 5, 10), disprog = disprog)[t == 5]
[Package hesim version 0.5.4 Index]