totlos.simfs: Expected total length of stay in specific states, from a...

View source: R/mstate.R

totlos.simfsR Documentation

Expected total length of stay in specific states, from a fully-parametric, semi-Markov multi-state model


The expected total time spent in each state for semi-Markov multi-state models fitted to time-to-event data with flexsurvreg. This is defined by the integral of the transition probability matrix, though this is not analytically possible and is computed by simulation.


  t = 1,
  start = 1,
  newdata = NULL,
  ci = FALSE,
  tvar = "trans",
  tcovs = NULL,
  group = NULL,
  M = 1e+05,
  B = 1000,
  cl = 0.95,
  cores = NULL



A model fitted with flexsurvreg. See msfit.flexsurvreg for the required form of the model and the data. Additionally this should be semi-Markov, so that the time variable represents the time since the last transition. In other words the response should be of the form Surv(time,status). See the package vignette for further explanation.

x can also be a list of models, with one component for each permitted transition, as illustrated in msfit.flexsurvreg.


Matrix indicating allowed transitions. See msfit.flexsurvreg.


Maximum time to predict to.


Starting state.


A data frame specifying the values of covariates in the fitted model, other than the transition number. See msfit.flexsurvreg.


Return a confidence interval calculated by simulating from the asymptotic normal distribution of the maximum likelihood estimates. This is turned off by default, since two levels of simulation are required. If turned on, users should adjust B and/or M until the results reach the desired precision. The simulation over M is generally vectorised, therefore increasing B is usually more expensive than increasing M.


Variable in the data representing the transition type. Not required if x is a list of models.


Predictable time-dependent covariates such as age, see sim.fmsm.


Optional grouping for the states. For example, if there are four states, and group=c(1,1,2,2), then totlos.simfs returns the expected total time in states 1 and 2 combined, and states 3 and 4 combined.


Number of individuals to simulate in order to approximate the transition probabilities. Users should adjust this to obtain the required precision.


Number of simulations from the normal asymptotic distribution used to calculate variances. Decrease for greater speed at the expense of accuracy.


Width of symmetric confidence intervals, relative to 1.


Number of processor cores used when calculating confidence limits bu repeated simulation. The default uses single-core processing.


This is computed by simulating a large number of individuals M using the maximum likelihood estimates of the fitted model and the function sim.fmsm. Therefore this requires a random sampling function for the parametric survival model to be available: see the "Details" section of sim.fmsm. This will be available for all built-in distributions, though users may need to write this for custom models.

Note the random sampling method for flexsurvspline models is currently very inefficient, so that looping over M will be very slow.

The equivalent function for time-inhomogeneous Markov models is totlos.fs. Note neither of these functions give errors or warnings if used with the wrong type of model, but the results will be invalid.


The expected total time spent in each state (or group of states given by group) up to time t, and corresponding confidence intervals if requested.


Christopher Jackson

See Also



# BOS example in vignette, and in msfit.flexsurvreg
bexp <- flexsurvreg(Surv(years, status) ~ trans, data=bosms3, dist="exp")
tmat <- rbind(c(NA,1,2),c(NA,NA,3),c(NA,NA,NA))

# predict 4 years spent without BOS, 3 years with BOS, before death
# As t increases, this should converge
totlos.simfs(bexp, t=10, trans=tmat)
totlos.simfs(bexp, t=1000, trans=tmat)

flexsurv documentation built on Feb. 16, 2023, 5:07 p.m.