# 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

1 2 3 4 5 6 | ```
simulateCohort(transitionFunctions, parameters, cohortSize = 1000,
parameterCovariances = FALSE, timeToTransition = array(FALSE, dim =
dim(transitionFunctions@list.matrix)), baseline = matrix(NA, nrow =
cohortSize), initialState = rep(1, cohortSize),
absorbing = transitionFunctions@states.number, to = 100,
report.every = 100, sampler.steps = 1000)
``` |

### Arguments

`transitionFunctions` |
a |

`parameters` |
a |

`cohortSize` |
a |

`parameterCovariances` |
a |

`timeToTransition` |
a |

`baseline` |
a |

`initialState` |
a |

`absorbing` |
a |

`to` |
final time of the simulation. |

`report.every` |
a |

`sampler.steps` |
a |

### 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 x 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | ```
# 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))
``` |