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.

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.

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, and "mix" for a mixture of clock-reset and clock-forward models. 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.

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".

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"),
  reset_states = 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.

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.

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)))
#> transition_id sample strategy_id patient_id grp_id t hazard #> 1: 1 1 1 1 1 1 0.19599086 #> 2: 1 1 1 1 1 2 0.19599086 #> 3: 1 1 1 1 1 3 0.19599086 #> 4: 2 1 1 1 1 1 0.04988861 #> 5: 2 1 1 1 1 2 0.04988861 #> 6: 2 1 1 1 1 3 0.04988861
head(transmod$cumhazard(c(1, 2, 3)))
#> transition_id sample strategy_id patient_id grp_id t cumhazard #> 1: 1 1 1 1 1 1 0.19599086 #> 2: 1 1 1 1 1 2 0.39198173 #> 3: 1 1 1 1 1 3 0.58797259 #> 4: 2 1 1 1 1 1 0.04988861 #> 5: 2 1 1 1 1 2 0.09977722 #> 6: 2 1 1 1 1 3 0.14966583
## Simulate disease progression and state probabilities together transmod$sim_stateprobs(t = c(0, 5, 10))[t == 5]
#> sample strategy_id grp_id state_id t prob #> 1: 1 1 1 1 5 0.6666667 #> 2: 1 1 1 2 5 0.0000000 #> 3: 1 1 1 3 5 0.3333333 #> 4: 1 2 1 1 5 0.3333333 #> 5: 1 2 1 2 5 0.0000000 #> 6: 1 2 1 3 5 0.6666667 #> 7: 1 3 1 1 5 0.3333333 #> 8: 1 3 1 2 5 0.3333333 #> 9: 1 3 1 3 5 0.3333333 #> 10: 2 1 1 1 5 1.0000000 #> 11: 2 1 1 2 5 0.0000000 #> 12: 2 1 1 3 5 0.0000000 #> 13: 2 2 1 1 5 0.0000000 #> 14: 2 2 1 2 5 0.3333333 #> 15: 2 2 1 3 5 0.6666667 #> 16: 2 3 1 1 5 0.0000000 #> 17: 2 3 1 2 5 0.3333333 #> 18: 2 3 1 3 5 0.6666667
## 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]
#> sample strategy_id grp_id state_id t prob #> 1: 1 1 1 1 5 0.3333333 #> 2: 1 1 1 2 5 0.0000000 #> 3: 1 1 1 3 5 0.6666667 #> 4: 1 2 1 1 5 0.3333333 #> 5: 1 2 1 2 5 0.6666667 #> 6: 1 2 1 3 5 0.0000000 #> 7: 1 3 1 1 5 0.3333333 #> 8: 1 3 1 2 5 0.3333333 #> 9: 1 3 1 3 5 0.3333333 #> 10: 2 1 1 1 5 0.6666667 #> 11: 2 1 1 2 5 0.0000000 #> 12: 2 1 1 3 5 0.3333333 #> 13: 2 2 1 1 5 0.3333333 #> 14: 2 2 1 2 5 0.0000000 #> 15: 2 2 1 3 5 0.6666667 #> 16: 2 3 1 1 5 0.0000000 #> 17: 2 3 1 2 5 0.6666667 #> 18: 2 3 1 3 5 0.3333333