icmstate (version 0.2.0)

sim_weibmsm: 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
)

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.

Arguments

data

A data.frame or matrix with named columns time and id, representing the observation times and corresponding subject id(entifier).

tmat

A transition matrix as created by transMat, with H rows and H columns indicating the states. The total number of possible transitions will be indicated by M.

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 obstimes. No exact states if missing.

shape

A numeric vector of length M indicating the shape of the Weibull transition intensity for the corresponding transition in tmat. See help(dweibull).

scale

A numeric vector of length M indicating the scale of the Weibull transition intensity for the corresponding transition in tmat. See help(dweibull).

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 NA. If left missing, no censoring is applied. See details.

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 NA. If left missing, no censoring is applied. See details.

n_subj

(Optional) Instead of specifying data, specify the number of subjects to generate trajectories for. Requires obs_pars to also be specified.

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 obs_pars = c(2, 0.5, 20) will generate a grid of observation times (0, 2, 4, ..., 20) with a uniform[-0.5, 0.5] random variable added to each observation time, and cut-off at the end-points 0 and 20. The observation times may not overlap, so the first argument must be at least twice as large as the second.

true_trajec

Should the true (right-censored) trajectory be returned for the subjects as well? Default = FALSE.

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.

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)