simulateCohort: Simulate cohort
In GUIgems: Graphical User Interface for Generalized Multistate Simulation Model

Description Usage Arguments Details Value Author(s) See Also Examples

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.

simulateCohort(transitionFunctions, parameters, cohortSize = 1000,
  parameterCovariances = generateParameterCovarianceMatrix(parameters),
  timeToTransition = array(FALSE, dim = dim(transitionFunctions@list.matrix)),
  baseline = matrix(NA, nrow = cohortSize),
  baselineFunction = baselineFunction_empty, initialState = rep(1,
  cohortSize), absorbing = transitionFunctions@states.number, to = 100,
  report.every = 100, sampler.steps = 1000)

`transitionFunctions`	a `transition.structure` of dimension N x N that contains the hazard functions element corresponds to a transition number, 0 if transition does not occur
`parameters`	a `transition.structure` of dimension N x N that contains the parameters
`cohortSize`	a `numeric` indicating the number of patients to be simulated.
`parameterCovariances`	a `transition.structure` of dimension N x 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 x M with M baseline characteristics of subjects to be simulated.
`baselineFunction`	a `function` generating a `data.frame` of dimension cohortSize x 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

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.

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

Luisa Salazar Vizcaya, Nello Blaser, Thomas Gsponer

generateHazardMatrix,

generateParameterMatrix,

generateParameterCovarianceMatrix,

ArtCohort, transitionProbabilities,

cumulativeIncidence

# 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(r1=0.33,  r2=0.03) # r1, r2 
mu[[2,3]] <- list(shape=1,scale=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))