simulateCohort {gems}

Simulate cohort

Description

Simulates a cohort of patients from a set of functions associated to each possible transition in a multistate model. The multistate model is not required to be a Markov model and may take the history of previous events into account. In the basic version, it allows to simulate from transition-specific hazard function, whose parameters are multivariable normally distributed. For each state, all transition-specific hazard functions and their parameters need to be specified. For simulating one transition, all possible event times are simulated and the minimum is chosen. Then simulation continues from the corresponding state until an absorbing state of time to is reached.

Usage

simulateCohort(transitionFunctions, parameters, cohortSize = 1000,
  parameterCovariances = FALSE, timeToTransition = array(FALSE, dim =
  dim([e-mail])), baseline = matrix(NA, nrow =
  cohortSize), initialState = rep(1, cohortSize),
  absorbing = [e-mail], to = 100,
  report.every = 100, sampler.steps = 1000)

Arguments

transitionFunctions

a transition.structure of dimension N \times N that contains the hazard functions

parameters

a transition.structure of dimension N \times N that contains the parameters

cohortSize

a numeric indicating the number of patients to be simulated.

parameterCovariances

a transition.structure of dimension N \times N of covariance matrices for the parameters.

timeToTransition

a logical matrix; TRUE for all transitions whose transitionFunction is specified as the time until transition instead of as a hazard function or as a character.

baseline

a matrix or data.frame of dimension cohortSize \times M with M baseline characteristics of subjects to be simulated.

initialState

a numeric of length cohortSize with the initial state for each subject simulated.

absorbing

a numeric containing all absorbing states.

to

final time of the simulation.

report.every

a numeric to check progress of simulation.

sampler.steps

a numeric indicating number of steps for discretization of hazard functions

Details

The transitionFunctions contains hazard functions or time to event function associated to each possible transition. The elements of this list can be either expressed as an explicit R function or as a character ("impossible", "Weibull", "multWeibull", "exponential") in order to express impossible transitions or parametric forms for the distributions of time to event. If the functions should depend on time, baseline characteristics or be history-dependent, the function arguments t, bl or history can be used. Time t refers to the time since entry into the current state. For the time since the initial state, use t+sum(history).

The components of the parameters argument list the mean values for the parameters in the transitionFunction. If the corresponding transitionFunction is a function, the parameters should appear in the same order as in the function, leaving out t, bl and history. If the corresponding transitionFunction is the character "Weibull", the first argument is the shape and the second one the scale. If the corresponding transitionFunction is the character "multWeibull", specify weights, shapes, scales in this order.

Note that when using the parameterCovariances argument it is the users responsibility to ensure that the functions are parametrized such that parameters for each transition are multivariate normally distributed and mutually independent.

Value

an object of class "ArtCohort" with time.to.state slot of dimension cohortSize \times N with entry times for each patient into each of the states.

Author(s)

Luisa Salazar Vizcaya, Nello Blaser, Thomas Gsponer

References

Nello Blaser, Luisa Salazar Vizcaya, Janne Estill, Cindy Zahnd, Bindu Kalesan, Matthias Egger, Olivia Keiser, Thomas Gsponer (2015). gems: An R Package for Simulating from Disease Progression Models. Journal of Statistical Software, 64(10), 1-22. URL http://www.jstatsoft.org/v64/i10/.

See Also

generateHazardMatrix, generateParameterMatrix, generateParameterCovarianceMatrix, ArtCohort, transitionProbabilities, cumulativeIncidence

Examples

# Here is an example model with 3 states and 2 possible transitions. 
 
# number of states in the model
statesNumber <- 3 

# cohort size
cohortSize <- 100

# specification of hazard functions
hazardf <- generateHazardMatrix(statesNumber)
hazardf[[1,2]] <- function(t, r1, r2) 
{
  ifelse(t<=2, r1 , r2)
}
hazardf[[2,3]] <- "Weibull" 

# list of parameters for the hazard functions
mu <- generateParameterMatrix(hazardf) 
mu[[1,2]] <- list(0.33,  0.03) # r1, r2 
mu[[2,3]] <- list(1,0.84) # shape, scale

# time
maxTime <- 10

# simulate the cohort
cohort <- simulateCohort(
  transitionFunctions = hazardf,
  parameters = mu,
  cohortSize = cohortSize,
  to=maxTime)

# output
head(cohort)

# transition probability
tr <- transitionProbabilities(cohort, times=seq(0,4,.1))
plot(tr, ci=FALSE)

# cumulative incidence
inc <- cumulativeIncidence(cohort, times=seq(0,4,.1))
plot(inc, ci=FALSE, states=c(2,3))