Estimate the expected total length of stay, or the expected number of visits, in each state, for an individual in a given period of evolution of a multistate model.
1 2 3 4 5 6 7 8 9 10  totlos.msm(x, start=1, end=NULL, fromt=0, tot=Inf, covariates="mean",
piecewise.times=NULL, piecewise.covariates=NULL,
num.integ=FALSE, discount=0, env=FALSE,
ci=c("none","normal","bootstrap"), cl=0.95, B=1000,
cores=NULL, ...)
envisits.msm(x, start=1, end=NULL, fromt=0, tot=Inf, covariates="mean",
piecewise.times=NULL, piecewise.covariates=NULL,
num.integ=FALSE, discount=0,
ci=c("none","normal","bootstrap"), cl=0.95, B=1000,
cores=NULL, ...)

x 
A fitted multistate model, as returned by

start 
Either a single number giving the state at the beginning of the period, or a vector of probabilities of being in each state at this time. 
end 
States to estimate the total length of stay (or number of visits) in. Defaults to all states. This is deprecated, since with the analytic solution (see "Details") it doesn't save any computation to only estimate for a subset of states. 
fromt 
Time from which to estimate. Defaults to 0, the beginning of the process. 
tot 
Time up to which the estimate is made. Defaults to
infinity, giving the expected time spent in or number of visits to
the state until absorption. However, the calculation will be much
more efficient if a finite (potentially large) time is specified:
see the "Details" section. For models without an absorbing state,

covariates 
The covariate values to estimate for. This can either be: the string the number or a list of values, with optional names. For example
where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

piecewise.times 
Times at which piecewiseconstant intensities
change. See 
piecewise.covariates 
Covariates on which the piecewiseconstant
intensities depend. See 
num.integ 
Use numerical integration instead of analytic solution (see below). 
discount 
Discount rate in continuous time. 
env 
Supplied to 
ci 
If If If 
cl 
Width of the symmetric confidence interval, relative to 1 
B 
Number of bootstrap replicates 
cores 
Number of cores to use for bootstrapping using parallel
processing. See 
... 
Further arguments to be passed to the

The expected total length of stay in state j between times t_1 and t_2, from the point of view of an individual in state i at time 0, is defined by the integral from t_1 to t_2 of the i,j entry of the transition probability matrix P(t) = Exp(tQ), where Q is the transition intensity matrix.
The corresponding expected number of visits to state j is ∑_{i=j} T_i Q_{i,j} (excluding the stay in the current state at time 0).
More generally, suppose that pi_0
is the vector of probabilities of being in each state at time 0,
supplied in start
, and we want the vector x giving the expected
lengths of stay in each state. The corresponding integral has the
following solution (van Loan 1978; van Rosmalen et al. 2013)
x = [1, 0_K] Exp(t Q') [0_K, I_K]'
where
Q' = rbind(c(0, pi_0), cbind(0_K, Q  r I_K)),
pi_0 is the row vector of initial state probabilities
supplied in start
, 0_K is
the row vector of K zeros, r is the discount rate, I_K is the K x K identity matrix, and
Exp is the matrix exponential.
Alternatively, the integrals can be calculated numerically, using the
integrate
function. This may take a long time for
models with many states where P(t) is expensive to calculate.
This is required where tot = Inf
, since the package author is
not aware of any analytic expression for the limit of the above
formula as t goes to infinity.
With the argument num.integ=TRUE
, numerical integration is used
even where the analytic solution is available. This facility is just
provided for checking results against versions 1.2.4 and earlier, and
will be removed eventually. Please let the package maintainer know if
any results are different.
For a model where the individual has only one place to go from each state, and each state is visited only once, for example a progressive disease model with no recovery or death, these are equal to the mean sojourn time in each state. However, consider a threestate healthdiseasedeath model with transitions from health to disease, health to death, and disease to death, where everybody starts healthy. In this case the mean sojourn time in the disease state will be greater than the expected length of stay in the disease state. This is because the mean sojourn time in a state is conditional on entering the state, whereas the expected total time diseased is a forecast for a healthy individual, who may die before getting the disease.
In the above formulae, Q is assumed to be constant over time,
but the results generalise easily to piecewiseconstant intensities.
This function automatically handles models fitted using the pci
option to msm
. For any other inhomogeneous models, the
user must specify piecewise.times
and
piecewise.covariates
arguments to totlos.msm
.
A vector of expected total lengths of stay (totlos.msm
),
or expected number of visits (envisits.msm
), for each
transient state.
C. H. Jackson chris.jackson@mrcbsu.cam.ac.uk
C. van Loan (1978). Computing integrals involving the matrix exponential. IEEE Transactions on Automatic Control 23(3)395404.
J. van Rosmalen, M. Toy and J.F. O'Mahony (2013). A mathematical approach for evaluating Markov models in continuous time without discreteevent simulation. Medical Decision Making 33:767779.
sojourn.msm
, pmatrix.msm
, integrate
, boot.msm
.
Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
Please suggest features or report bugs with the GitHub issue tracker.
All documentation is copyright its authors; we didn't write any of that.