# Simulate paths through a fully parametric semi-Markov multi-state model

Source:`R/mstate.R`

`sim.fmsm.Rd`

Simulate changes of state and transition times from a semi-Markov
multi-state model fitted using `flexsurvreg`

.

## Usage

```
sim.fmsm(
x,
trans = NULL,
t,
newdata = NULL,
start = 1,
M = 10,
tvar = "trans",
tcovs = NULL,
tidy = FALSE,
debug = FALSE
)
```

## Arguments

- x
A model fitted with

`flexsurvreg`

. See`msfit.flexsurvreg`

for the required form of the model and the data.Alternatively

`x`

can be a list of fitted`flexsurvreg`

model objects. The`i`

th element of this list is the model corresponding to the`i`

th transition in`trans`

. This is a more efficient way to fit a multi-state model, but only valid if the parameters are different between different transitions.- trans
Matrix indicating allowed transitions. See

`msfit.flexsurvreg`

.- t
Time, or vector of times for each of the

`M`

individuals, to simulate trajectories until.- newdata
A data frame specifying the values of covariates in the fitted model, other than the transition number. See

`msfit.flexsurvreg`

.- start
Starting state, or vector of starting states for each of the

`M`

individuals.- M
Number of individual trajectories to simulate.

- tvar
Variable in the data representing the transition type. Not required if

`x`

is a list of models.- tcovs
Names of "predictable" time-dependent covariates in

`newdata`

, i.e. those whose values change at the same rate as time. Age is a typical example. During simulation, their values will be updated after each transition time, by adding the current time to the value supplied in`newdata`

. This assumes the covariate is measured in the same unit as time.`tcovs`

is supplied as a character vector.- tidy
If

`TRUE`

then the simulated data are returned as a tidy data frame with one row per simulated transition. See`simfs_bytrans`

for a function to rearrange the data into this format if it was simulated in non-tidy format. Currently this includes only event times, and excludes any times of censoring that are reported when`tidy=FALSE`

.- debug
Print intermediate outputs: for development use.

## Value

If `tidy=TRUE`

, a data frame with one row for each simulated transition, giving the individual ID `id`

, start state `start`

, end state `end`

, transition label `trans`

, time of the transition since the start of the process (`time`

), and time since the previous transition (`delay`

).

If `tidy=FALSE`

, a list of two matrices named `st`

and `t`

. The rows of
each matrix represent simulated individuals. The columns of `t`

contain the times when the individual changes state, to the corresponding
states in `st`

.

The first columns will always contain the starting states and the starting
times. The last column of `t`

represents either the time when the
individual moves to an absorbing state, or right-censoring in a transient
state at the time given in the `t`

argument to `sim.fmsm`

.

## Details

`sim.fmsm`

relies on the presence of a function to sample random
numbers from the parametric survival distribution used in the fitted model
`x`

, for example `rweibull`

for Weibull models. If
`x`

was fitted using a custom distribution, called `dist`

say,
then there must be a function called (something like) `rdist`

either
in the working environment, or supplied through the `dfns`

argument to
`flexsurvreg`

. This must be in the same format as standard R
functions such as `rweibull`

, with first argument `n`

, and
remaining arguments giving the parameters of the distribution. It must be
vectorised with respect to the parameter arguments.

This function is only valid for semi-Markov ("clock-reset") models, though no warning or error is currently given if the model is not of this type. An equivalent for time-inhomogeneous Markov ("clock-forward") models has currently not been implemented.

## Author

Christopher Jackson chris.jackson@mrc-bsu.cam.ac.uk.

## Examples

```
bexp <- flexsurvreg(Surv(years, status) ~ trans, data=bosms3, dist="exp")
tmat <- rbind(c(NA,1,2),c(NA,NA,3),c(NA,NA,NA))
sim.fmsm(bexp, M=10, t=5, trans=tmat)
#> $st
#> [,1] [,2] [,3]
#> [1,] 1 2 2
#> [2,] 1 2 2
#> [3,] 1 3 3
#> [4,] 1 3 3
#> [5,] 1 2 3
#> [6,] 1 1 1
#> [7,] 1 1 1
#> [8,] 1 3 3
#> [9,] 1 2 3
#> [10,] 1 2 2
#>
#> $t
#> [,1] [,2] [,3]
#> [1,] 0 0.04056377 5.0000000
#> [2,] 0 2.37118887 5.0000000
#> [3,] 0 2.12455204 2.1245520
#> [4,] 0 0.36715147 0.3671515
#> [5,] 0 0.94681789 1.9433587
#> [6,] 0 5.00000000 5.0000000
#> [7,] 0 5.00000000 5.0000000
#> [8,] 0 4.25651403 4.2565140
#> [9,] 0 0.05740866 2.5896499
#> [10,] 0 2.77917357 5.0000000
#>
#> attr(,"trans")
#> [,1] [,2] [,3]
#> [1,] NA 1 2
#> [2,] NA NA 3
#> [3,] NA NA NA
```