sim_weibmsm {icmstate} | R Documentation |
Simulate multiple trajectories from an interval-censored multi-state model with Weibull transition intensities
Description
Simulate multiple trajectories from a multi-state model quantified by a transition matrix, with interval-censored transitions and Weibull distributed transition intensities. Allows for Weibull censoring in each of the states.
Usage
sim_weibmsm(
data,
tmat,
startprobs,
exact,
shape,
scale,
censshape,
censscale,
n_subj,
obs_pars,
true_trajec = FALSE
)
Arguments
data |
A |
tmat |
A transition matrix as created by |
startprobs |
A numeric vector of length H indicating the probability of each subject to start in any of the possible states. Must sum to 1. By default, all subjects will start in state 1. |
exact |
A numeric vector indicating which states are exactly observed.
The transition time to exact states will be observed at exact times, regardless
of the times in |
shape |
A numeric vector of length M indicating the shape of the Weibull
transition intensity for the corresponding transition in |
scale |
A numeric vector of length M indicating the scale of the Weibull
transition intensity for the corresponding transition in |
censshape |
A numeric vector of length H indicating the Weibull
censoring shape in each of the states. If no censoring is required in some states,
set corresponding entries to |
censscale |
A numeric vector of length H indicating the Weibull censoring
scale in each of the states. If no censoring is required in some states,
set corresponding entries to |
n_subj |
(Optional) Instead of specifying |
obs_pars |
(Optional) A numeric vector of length 3 specifying what the
time is between planned assessments, what the uniform deviation from this
time is at the visits and the maximum visit time.
Specifying |
true_trajec |
Should the true (right-censored) trajectory be returned for
the subjects as well? Default = |
Details
Taking (cens)shape
to be 1 for all transitions, we obtain exponential
(censoring)/transitions with rate 1/(cens)scale
.
If right-censoring parameters are specified, a right-censoring time is generated in
each of the visited states. If the subject is right-censored, we assume the subject
is no longer observed at later obstimes
. Due to the interval-censored
nature of the generation process, it may therefore appear as if the subject
was right-censored in an earlier state.
Suppose a subject arrives in state g at time s. If we wish to generate
a survival time from that state according to a Weibull intensity in a clock forward
model, we can use the inverse transform of the conditional Weibull intensity.
More specifically, letting a
denote the shape and \sigma
denote the scale,
the conditional survival function for t > s
is given by
S(t|s) = \mathbf{P}(T \geq t | T \geq s) = \exp(\left( \frac{s}{\sigma} \right)^a - \left( \frac{t}{\sigma} \right)^a)
The corresponding cumulative intensity is then given by:
A(t|s) = -\log(S(t|s)) = \left( \frac{t}{\sigma} \right)^a - \left( \frac{s}{\sigma} \right)^a
And the inverse cumulative intensity is then:
A^{-1}(t|s) = \sigma \sqrt[a]{t + \left( \frac{s}{\sigma} \right)^a}
A conditional survival time is then generated by:
T|s = A^{-1}(-\log(U)|s)
with U
a sample from the standard uniform distribution.
If we additionally have covariates (or frailties), the -\log(U)
above should be replaced by \frac{-\log(U)}{\exp(\beta X)}
with \beta
and X
the coefficients and covariates respectively.
Value
A matrix
with 3 columns time
, state
and id
, indicating
the observation time, the corresponding state and subject identifier. If
true_trajec = TRUE
, a list
with the matrix described above and a matrix
representing the underlying right-censored trajectory.
Examples
require(mstate)
require(ggplot2)
#Generate from an illness-death model with exponential transitions with
#rates 1/2, 1/10 and 1 for 10 subjects over a time grid.
gd <- sim_weibmsm(tmat = trans.illdeath(), shape = c(1,1,1),
scale = c(2, 10, 1), n_subj = 10, obs_pars = c(2, 0.5, 20),
startprobs = c(0.9, 0.1, 0), true_trajec = TRUE)
#Observed trajectories
visualise_msm(gd$observed)
#True trajectories
visualise_msm(gd$true)
#Can supply data-frame with specified observation times
obs_df <- data.frame(time = c(0, 1, 3, 5, 0.5, 6, 9),
id = c(1, 1, 1, 1, 2, 2, 2))
gd <- sim_weibmsm(data = obs_df, tmat = trans.illdeath(), shape = c(1, 1, 1),
scale = c(2, 10, 1))
visualise_msm(gd)