Version: 1.8.2

Date: 2024年11月07日

Title: Multi-State Markov and Hidden Markov Models in Continuous Time

Description: Functions for fitting continuous-time Markov and hidden Markov multi-state models to longitudinal data. Designed for processes observed at arbitrary times in continuous time (panel data) but some other observation schemes are supported. Both Markov transition rates and the hidden Markov output process can be modelled in terms of covariates, which may be constant or piecewise-constant in time.

License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Imports: survival, mvtnorm, expm, generics, tibble

Suggests: mstate, minqa, doParallel, foreach, numDeriv, testthat, flexsurv, covr

URL: https://github.com/chjackson/msm, https://chjackson.github.io/msm/

BugReports: https://github.com/chjackson/msm/issues

LazyData: yes

Encoding: UTF-8

RoxygenNote: 7.3.2

NeedsCompilation: yes

Packaged: 2024年11月07日 14:19:05 UTC; Chris J

Author: Christopher Jackson [aut, cre]

Maintainer: Christopher Jackson <chris.jackson@mrc-bsu.cam.ac.uk>

Repository: CRAN

Date/Publication: 2024年11月07日 21:10:01 UTC

MatrixExp(mat, t = 1, method = NULL, ...)

mat

A square matrix

t

An optional scaling factor for mat. If a vector is supplied, then an array of matrices is returned with different scaling factors.

method

Under the default of NULL, this simply wraps the expm function from the expm package. This is recommended. Options to expm can be supplied to MatrixExp , including method.

Otherwise, for backwards compatibility, the following options, which use code in the msm package, are available: "pade" for a Pade approximation method, "series" for the power series approximation, or "analytic" for the analytic formulae for simpler Markov model intensity matrices (see below). These options are only used if mat has repeated eigenvalues, thus the usual eigen-decomposition method cannot be used.

...

Arguments to pass to expm .

ptnum (numeric) Patient identification number

age (numeric) Recipient age at examination (years)

diam (numeric) Aortic diameter

state (numeric) State of aneurysm.

State 1 Aneurysm-free < 30 cm

State 2 Mild aneurysm 30-44 cm

State 3 Moderate aneurysm 45-54 cm

State 4 Severe aneurysm > 55 cm

boot.msm(
 x,
 stat = pmatrix.msm,
 B = 1000,
 file = NULL,
 cores = NULL,
 remove.errors = TRUE
)

x

A fitted msm model, as output by msm .

stat

A function to call on each refitted msm model. By default this is pmatrix.msm , returning the transition probability matrix in one time unit. If NULL then no function is computed.

B

Number of bootstrap resamples.

file

Name of a file in which to save partial results after each replicate. This is saved using save and can be restored using load , producing an object called boot.list containing the partial results. Not supported when using parallel processing.

cores

Number of processor cores to use for parallel processing. Requires the doParallel package to be installed. If not specified, parallel processing is not used. If cores is set to the string "default", the default methods of makeCluster (on Windows) or registerDoParallel (on Unix-like) are used.

remove.errors

If TRUE then bootstrap refits which resulted in an error are removed from the returned list, and a message is returned which states the proportion of failed fits and the first error message. If FALSE, then the error message for failed refits is placed in the corresponding component of the returned list.

## Not run: 
 ## Psoriatic arthritis example
 data(psor)
 psor.q <- rbind(c(0,0.1,0,0),c(0,0,0.1,0),c(0,0,0,0.1),c(0,0,0,0))
 psor.msm <- msm(state ~ months, subject=ptnum, data=psor, qmatrix =
 psor.q, covariates = ~ollwsdrt+hieffusn,
 constraint = list(hieffusn=c(1,1,1),ollwsdrt=c(1,1,2)),
 control = list(REPORT=1,trace=2), method="BFGS")
 ## Bootstrap the baseline transition intensity matrix. This will take a long time.
 q.list <- boot.msm(psor.msm, function(x)x$Qmatrices$baseline)
 ## Manipulate the resulting list of matrices to calculate bootstrap standard errors.
 apply(array(unlist(q.list), dim=c(4,4,5)), c(1,2), sd)
 ## Similarly calculate a bootstrap 95% confidence interval
 apply(array(unlist(q.list), dim=c(4,4,5)), c(1,2),
 function(x)quantile(x, c(0.025, 0.975)))
 ## Bootstrap standard errors are larger than the asymptotic standard
 ## errors calculated from the Hessian
 psor.msm$QmatricesSE$baseline
## End(Not run)

ptnum (numeric) Patient identification number

time (numeric) Months after transplant

state (numeric) BOS state entered at this time

PTNUM (numeric) Patient identification number

age (numeric) Recipient age at examination (years)

years (numeric) Examination time (years after transplant)

dage (numeric) Age of heart donor (years)

sex (numeric) sex (0=male, 1=female)

pdiag (factor) Primary diagnosis (reason for transplant)

IHD=ischaemic heart disease, IDC=idiopathic dilated cardiomyopathy.

cumrej (numeric) Cumulative number of acute rejection episodes

state (numeric) State at the examination.

State 1 represents no CAV, state 2 is mild/moderate CAV

and state 3 is severe CAV. State 4 indicates death.

firstobs (numeric) 0 = record represents an angiogram or date of death.

1 = record represents transplant (patient's first observation)

statemax (numeric) Maximum observed state so far for this patient (added in version 1.5.1)

ncens

The number of distinct values used for censored observations in the state data supplied to msm .

censor

A vector of length ncens, giving the labels used for censored states in the data.

states

A vector obtained by unlist()ing a list with ncens elements, each giving the set of true states that an observation with this label could be.

index

Index into states for the first state corresponding to each censor, plus an extra length(states)+1.

## S3 method for class 'msm'
coef(object, ...)

object

A fitted multi-state model object, as returned by msm .

...

(unused) further arguments passed to or from other methods.

crudeinits.msm(
 formula,
 subject,
 qmatrix,
 data = NULL,
 censor = NULL,
 censor.states = NULL
)

formula

A formula giving the vectors containing the observed states and the corresponding observation times. For example,

state ~ time

Observed states should be in the set 1, ...{}, n, where n is the number of states. Note hidden Markov models are not supported by this function.

subject

Vector of subject identification numbers for the data specified by formula. If missing, then all observations are assumed to be on the same subject. These must be sorted so that all observations on the same subject are adjacent.

qmatrix

Matrix of indicators for the allowed transitions. An initial value will be estimated for each value of qmatrix that is greater than zero. Transitions are taken as disallowed for each entry of qmatrix that is 0.

data

An optional data frame in which the variables represented by subject and state can be found.

censor

A state, or vector of states, which indicates censoring. See msm .

censor.states

Specifies the underlying states which censored observations can represent. See msm .

data(cav)
twoway4.q <- rbind(c(-0.5, 0.25, 0, 0.25), c(0.166, -0.498, 0.166, 0.166),
c(0, 0.25, -0.5, 0.25), c(0, 0, 0, 0))
statetable.msm(state, PTNUM, data=cav)
crudeinits.msm(state ~ years, PTNUM, data=cav, qmatrix=twoway4.q)

deltamethod(g, mean, cov, ses = TRUE)

g

A formula representing the transformation. The variables must be labelled x1, x2,...{} For example,

~ 1 / (x1 + x2)

If the transformation returns a vector, then a list of formulae representing (g_1, g_2, \ldots) can be provided, for example

list( ~ x1 + x2, ~ x1 / (x1 + x2) )

mean

The estimated mean of X

cov

The estimated covariance matrix of X

ses

If TRUE, then the standard errors of g_1(X), g_2(X),\ldots are returned. Otherwise the covariance matrix of g(X) is returned.

## Simple linear regression, E(y) = alpha + beta x 
x <- 1:100
y <- rnorm(100, 4*x, 5)
toy.lm <- lm(y ~ x)
estmean <- coef(toy.lm)
estvar <- summary(toy.lm)$cov.unscaled * summary(toy.lm)$sigma^2
## Estimate of (1 / (alphahat + betahat))
1 / (estmean[1] + estmean[2])
## Approximate standard error
deltamethod (~ 1 / (x1 + x2), estmean, estvar) 
## We have a variable z we would like to use within the formula.
z <- 1
## deltamethod (~ z / (x1 + x2), estmean, estvar) will not work.
## Instead, build up the formula as a string, and convert to a formula.
form <- sprintf("~ %f / (x1 + x2)", z)
form
deltamethod(as.formula(form), estmean, estvar)

draic.msm(
 msm.full,
 msm.coarse,
 likelihood.only = FALSE,
 information = c("expected", "observed"),
 tl = 0.95
)
drlcv.msm(
 msm.full,
 msm.coarse,
 tl = 0.95,
 cores = NULL,
 verbose = TRUE,
 outfile = NULL
)

msm.full

Model on the bigger state space.

msm.coarse

Model on the smaller state space.

The two models must both be non-hidden Markov models without censored states.

The two models must be fitted to the same datasets, except that the state space of the coarse model must be an aggregated version of the state space of the full model. That is, every state in the full dataset must correspond to a unique state in the coarse dataset. For example, for the full state variable c(1,1,2,2,3,4), the corresponding coarse states could be c(1,1,2,2,2,3), but not c(1,2,3,4,4,4).

The structure of allowed transitions in the coarse model must also be a collapsed version of the big model structure, but no check is currently made for this in the code.

To use these functions, all objects which were used in the calls to fit msm.full and msm.coarse must be in the working environment, for example, datasets and definitions of transition matrices.

likelihood.only

Don't calculate Hessians and trace term (DRAIC).

information

Use observed or expected information in the DRAIC trace term. Expected is the default, and much faster, though is only available for models fitted to pure panel data (all obstype=1 in the call to msm , thus not exact transition times or exact death times)

tl

Width of symmetric tracking interval, by default 0.95 for a 95% interval.

cores

Number of processor cores to use in drlcv for cross-validation by parallel processing. Requires the doParallel package to be installed. If not specified, parallel processing is not used. If cores is set to the string "default", the default methods of makeCluster (on Windows) or registerDoParallel (on Unix-like) are used.

verbose

Print intermediate results of each iteration of cross-validation to the console while running. May not work with parallel processing.

outfile

Output file to print intermediate results of cross-validation. Useful to track execution speed when using parallel processing, where output to the console may not work.

npars

Number of covariate effect parameters. This is defined as the number of covariates on misclassification (with factors expanded as contrasts) multiplied by the number of allowed misclassifications in the model.

ndpars

Number of distinct covariate effect parameters, as npars, but after any equality constraints have been applied.

ncovs

Number of covariates on misclassification, with factors expanded as contrasts.

constr

List of equality constraints on these covariate effects, as supplied in the miscconstraint argument to msm .

covlabels

Names / labels of these covariates in the model matrix (see model.matrix.msm ).

inits

Initial values for these covariate effects, as a vector formed from the misccovinits list supplied to msm .

covmeans

Means of these covariates in the data (excluding data not required to fit the model, such as observations with missing data in other elements or subjects' last observations). This includes means of 0/1 factor contrasts as well as continuous covariates (for historic reasons, which may not be sensible).

efpt.msm(
 x = NULL,
 qmatrix = NULL,
 tostate,
 start = "all",
 covariates = "mean",
 ci = c("none", "normal", "bootstrap"),
 cl = 0.95,
 B = 1000,
 cores = NULL,
 ...
)

x

A fitted multi-state model, as returned by msm .

qmatrix

Instead of x, you can simply supply a transition intensity matrix in qmatrix.

tostate

State, or set of states supplied as a vector, for which to estimate the first passage time into. Can be integer, or character matched to the row names of the Q matrix.

start

Starting state (integer). By default (start="all"), this will return a vector of expected passage times from each state in turn.

Alternatively, this can be used to obtain the expected first passage time from a set of states, rather than single states. To achieve this, state is set to a vector of weights, with length equal to the number of states in the model. These weights should be proportional to the probability of starting in each of the states in the desired set, so that weights of zero are supplied for other states. The function will calculate the weighted average of the expected passage times from each of the corresponding states.

covariates

Covariate values defining the intensity matrix for the fitted model x, as supplied to qmatrix.msm .

ci

If "normal", then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

If "none" (the default) then no confidence interval is calculated.

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 boot.msm for more details.

...

Arguments to pass to MatrixExp .

twoway4.q <- rbind(c(-0.5, 0.25, 0, 0.25), c(0.166, -0.498, 0.166, 0.166),
 c(0, 0.25, -0.5, 0.25), c(0, 0, 0, 0))
efpt.msm(qmatrix=twoway4.q, tostate=3)
# given in state 1, expected time to reaching state 3 is infinite
# since may die (state 4) before entering state 3
# If we remove the death state from the model, EFPTs become finite
Q <- twoway4.q[1:3,1:3]; diag(Q) <- 0; diag(Q) <- -rowSums(Q)
efpt.msm(qmatrix=Q, tostate=3)
# Suppose we cannot die or regress while in state 2, can only go to state 3
Q <- twoway4.q; Q[2,4] <- Q[2,1] <- 0; diag(Q) <- 0; diag(Q) <- -rowSums(Q)
efpt.msm(qmatrix=Q, tostate=3)
# The expected time from 2 to 3 now equals the mean sojourn time in 2.
-1/Q[2,2]
# Calculate cumulative distribution of the first passage time
# into state 3 for the following three-state model
Q <- twoway4.q[1:3,1:3]; diag(Q) <- 0; diag(Q) <- -rowSums(Q)
# Firstly form a model where the desired hitting state is absorbing
Q[3,] <- 0
MatrixExp(Q, t=10)[,3]
ppass.msm(qmatrix=Q, tot=10)
# Given in state 1 at time 0, P(hit 3 by time 10) = 0.479
MatrixExp(Q, t=50)[,3] # P(hit 3 by time 50) = 0.98
ppass.msm(qmatrix=Q, tot=50)

ematrix.msm(
 x,
 covariates = "mean",
 ci = c("delta", "normal", "bootstrap", "none"),
 cl = 0.95,
 B = 1000,
 cores = NULL
)

x

A fitted multi-state model, as returned by msm

covariates

The covariate values for which to estimate the misclassification probability matrix. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

list (age = 60, sex = 1)

ci

If "delta" (the default) then confidence intervals are calculated by the delta method, or by simple transformation of the Hessian in the very simplest cases.

If "normal", then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the multinomial-logit-transformed misclassification probabilities and covariate effects, then transforming back.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs

cores

Number of cores to use for bootstrapping using parallel processing. See boot.msm for more details.

estimate

Estimated misclassification probability matrix. The rows correspond to true states, and columns observed states.

SE

Corresponding approximate standard errors.

L

Lower confidence limits.

U

Upper confidence limits.

nstates

Number of states (same as qmodel$nstates).

npars

Number of allowed misclassifications, equal to sum(imatrix).

imatrix

Indicator matrix for allowed misclassifications. This has (r,s) entry 1 if misclassification of true state r as observed state s is possible. diagonal entries are arbitrarily set to 0.

ematrix

Matrix of initial values for the misclassification probabilities, supplied as the ematrix argument of msm .

inits

Vector of these initial values, reading across rows of qmatrix and excluding the diagonal and disallowed transitions.

constr

Indicators for equality constraints on baseline misclassification probabilities, taken from the econstraint argument to msm , and mapped if necessary to the set (1,2,3,...)

ndpars

Number of distinct misclassification probabilities, after applying equality constraints.

nipars

Number of initial state occupancy probabilities being estimated. This is zero if est.initprobs=FALSE, otherwise equal to the number of states.

initprobs

Initial state occupancy probabilities, as supplied to msm (initial values before estimation, if est.initprobs=TRUE.)

est.initprobs

Are initial state occupancy probabilities estimated (TRUE or FALSE), as supplied in the est.initprobs argument of msm .

ptnum (numeric) Patient identification number.

days (numeric) Examination time (days after transplant).

fev (numeric) Percentage of baseline FEV1. A code of 999 indicates the patient's date of death.

acute (numeric) 0/1 indicator for whether the patient suffered an acute infection or rejection

within 14 days of the visit.

hazard.msm(x, hazard.scale = 1, cl = 0.95)

x

Output from msm representing a fitted multi-state model.

hazard.scale

Vector with same elements as number of covariates on transition rates. Corresponds to the increase in each covariate used to calculate its hazard ratio. Defaults to all 1.

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

hmmCat(prob, basecat)
hmmIdent(x)
hmmUnif(lower, upper)
hmmNorm(mean, sd)
hmmLNorm(meanlog, sdlog)
hmmExp(rate)
hmmGamma(shape, rate)
hmmWeibull(shape, scale)
hmmPois(rate)
hmmBinom(size, prob)
hmmBetaBinom(size, meanp, sdp)
hmmNBinom(disp, prob)
hmmBeta(shape1, shape2)
hmmTNorm(mean, sd, lower = -Inf, upper = Inf)
hmmMETNorm(mean, sd, lower, upper, sderr, meanerr = 0)
hmmMEUnif(lower, upper, sderr, meanerr = 0)
hmmT(mean, scale, df)

prob

(hmmCat) Vector of probabilities of observing category 1, 2, ...{}, length(prob) respectively. Or the probability governing a binomial or negative binomial distribution.

basecat

(hmmCat) Category which is considered to be the "baseline", so that during estimation, the probabilities are parameterised as probabilities relative to this baseline category. By default, the category with the greatest probability is used as the baseline.

x

(hmmIdent) Code in the data which denotes the exactly-observed state.

lower

(hmmUnif,hmmTNorm,hmmMEUnif) Lower limit for an Uniform or truncated Normal distribution.

upper

(hmmUnif,hmmTNorm,hmmMEUnif) Upper limit for an Uniform or truncated Normal distribution.

mean

(hmmNorm,hmmLNorm,hmmTNorm) Mean defining a Normal, or truncated Normal distribution.

sd

(hmmNorm,hmmLNorm,hmmTNorm) Standard deviation defining a Normal, or truncated Normal distribution.

meanlog

(hmmNorm,hmmLNorm,hmmTNorm) Mean on the log scale, for a log Normal distribution.

sdlog

(hmmNorm,hmmLNorm,hmmTNorm) Standard deviation on the log scale, for a log Normal distribution.

rate

(hmmPois,hmmExp,hmmGamma) Rate of a Poisson, Exponential or Gamma distribution (see dpois , dexp , dgamma ).

shape

(hmmPois,hmmExp,hmmGamma) Shape parameter of a Gamma or Weibull distribution (see dgamma , dweibull ).

scale

(hmmGamma) Scale parameter of a Gamma distribution (see dgamma ), or unstandardised Student t distribution.

size

Order of a Binomial distribution (see dbinom ).

meanp

Mean outcome probability in a beta-binomial distribution

sdp

Standard deviation describing the overdispersion of the outcome probability in a beta-binomial distribution

disp

Dispersion parameter of a negative binomial distribution, also called size or order. (see dnbinom ).

shape1, shape2

First and second parameters of a beta distribution (see dbeta ).

sderr

(hmmMETNorm,hmmUnif) Standard deviation of the Normal measurement error distribution.

meanerr

(hmmMETNorm,hmmUnif) Additional shift in the measurement error, fixed to 0 by default. This may be modelled in terms of covariates.

df

Degrees of freedom of the Student t distribution.

PARAMETER NAME LINK FUNCTION

mean identity

meanlog identity

rate log

scale log

meanerr identity

meanp logit

prob logit or multinomial logit

hmmMV(...)

...

The number of arguments supplied should equal the maximum number of observations made at one time. Each argument represents the univariate distribution of that outcome conditionally on the hidden state, and should be the result of calling a univariate hidden Markov model constructor (see hmm-dists ).

## Simulate data from a Markov model 
nsubj <- 30; nobspt <- 5
sim.df <- data.frame(subject = rep(1:nsubj, each=nobspt),
 time = seq(0, 20, length=nobspt))
set.seed(1)
two.q <- rbind(c(-0.1, 0.1), c(0, 0))
dat <- simmulti.msm(sim.df[,1:2], qmatrix=two.q, drop.absorb=FALSE)
### EXAMPLE 1
## Generate two observations at each time from the same outcome
## distribution:
## Bin(40, 0.1) for state 1, Bin(40, 0.5) for state 2
dat$obs1[dat$state==1] <- rbinom(sum(dat$state==1), 40, 0.1)
dat$obs2[dat$state==1] <- rbinom(sum(dat$state==1), 40, 0.1)
dat$obs1[dat$state==2] <- rbinom(sum(dat$state==2), 40, 0.5)
dat$obs2[dat$state==2] <- rbinom(sum(dat$state==2), 40, 0.5)
dat$obs <- cbind(obs1 = dat$obs1, obs2 = dat$obs2)
## Fitted model should approximately recover true parameters 
msm(obs ~ time, subject=subject, data=dat, qmatrix=two.q,
 hmodel = list(hmmBinom(size=40, prob=0.2),
 hmmBinom(size=40, prob=0.2)))
### EXAMPLE 2
## Generate two observations at each time from different
## outcome distributions:
## Bin(40, 0.1) and Bin(40, 0.2) for state 1, 
dat$obs1 <- dat$obs2 <- NA
dat$obs1[dat$state==1] <- rbinom(sum(dat$state==1), 40, 0.1)
dat$obs2[dat$state==1] <- rbinom(sum(dat$state==1), 40, 0.2)
## Bin(40, 0.5) and Bin(40, 0.6) for state 2
dat$obs1[dat$state==2] <- rbinom(sum(dat$state==2), 40, 0.6)
dat$obs2[dat$state==2] <- rbinom(sum(dat$state==2), 40, 0.5)
dat$obs <- cbind(obs1 = dat$obs1, obs2 = dat$obs2)
## Fitted model should approximately recover true parameters 
msm(obs ~ time, subject=subject, data=dat, qmatrix=two.q, 
 hmodel = list(hmmMV(hmmBinom(size=40, prob=0.3),
 hmmBinom(size=40, prob=0.3)), 
 hmmMV(hmmBinom(size=40, prob=0.3),
 hmmBinom(size=40, prob=0.3))),
 control=list(maxit=10000))

hidden

TRUE for hidden Markov models, FALSE otherwise.

nstates

Number of states, the same as qmodel$nstates.

fitted

TRUE if the parameter values in pars are the maximum likelihood estimates, FALSE if they are the initial values.

models

The outcome distribution for each hidden state. A vector of length nstates whose rth entry is the index of the state r outcome distributions in the vector of supported distributions. The vector of supported distributions is given in full by msm:::.msm.HMODELS: the first few are 1 for categorical outcome, 2 for identity, 3 for uniform and 4 for normal.

labels

String identifying each distribution in models.

npars

Vector of length nstates giving the number of parameters in each outcome distribution, excluding covariate effects.

nipars

Number of initial state occupancy probabilities being estimated. This is zero if est.initprobs=FALSE, otherwise equal to the number of states.

totpars

Total number of parameters, equal to sum(npars).

pars

A vector of length totpars, made from concatenating a list of length nstates whose rth component is vector of the parameters for the state r outcome distribution.

plabs

List with the names of the parameters in pars.

parstate

A vector of length totpars, whose ith element is the state corresponding to the ith parameter.

firstpar

A vector of length nstates giving the index in pars of the first parameter for each state.

locpars

Index in pars of parameters which can have covariates on them.

initprobs

Initial state occupancy probabilities, as supplied to msm (initial values before estimation, if est.initprobs=TRUE.)

est.initprobs

Are initial state occupancy probabilities estimated (TRUE or FALSE), as supplied in the est.initprobs argument of msm .

ncovs

Number of covariate effects per parameter in pars, with, e.g. factor contrasts expanded.

coveffect

Vector of covariate effects, of length sum(ncovs).

covlabels

Labels of these effects.

coveffstate

Vector indicating state corresponding to each element of coveffect.

ncoveffs

Number of covariate effects on HMM outcomes, equal to sum(ncovs).

nicovs

Vector of length nstates-1 giving the number of covariate effects on each initial state occupancy probability (log relative to the baseline probability).

icoveffect

Vector of length sum(nicovs) giving covariate effects on initial state occupancy probabilities.

nicoveffs

Number of covariate effects on initial state occupancy probabilities, equal to sum(nicovs).

constr

Constraints on (baseline) hidden Markov model outcome parameters, as supplied in the hconstraint argument of msm , excluding covariate effects, converted to a vector and mapped to the set 1,2,3,... if necessary.

covconstr

Vector of constraints on covariate effects in hidden Markov outcome models, as supplied in the hconstraint argument of msm , excluding baseline parameters, converted to a vector and mapped to the set 1,2,3,... if necessary.

ranges

Matrix of range restrictions for HMM parameters, including those given to the hranges argument to msm .

foundse

TRUE if standard errors are available for the estimates.

initpmat

Matrix of initial state occupancy probabilities with one row for each subject (estimated if est.initprobs=TRUE).

ci

Confidence intervals for baseline HMM outcome parameters.

covci

Confidence intervals for covariate effects in HMM outcome models.

hmodel2list(hmodel, hmmdist = TRUE)

hmodel

A list of class hmodel, as returned in the hmodel component of the fitted model object from msm .

hmmdist

TRUE or FALSE (see "Value" section).

## S3 method for class 'msm'
logLik(object, by.subject = FALSE, ...)

object

A fitted multi-state model object, as returned by msm .

by.subject

Return vector of subject-specific log-likelihoods, which should sum to the total log-likelihood.

...

(unused) further arguments passed to or from other methods.

lrtest.msm(...)

...

Two or more fitted multi-state models, as returned by msm , ordered by increasing numbers of parameters.

dmenorm(
 x,
 mean = 0,
 sd = 1,
 lower = -Inf,
 upper = Inf,
 sderr = 0,
 meanerr = 0,
 log = FALSE
)
pmenorm(
 q,
 mean = 0,
 sd = 1,
 lower = -Inf,
 upper = Inf,
 sderr = 0,
 meanerr = 0,
 lower.tail = TRUE,
 log.p = FALSE
)
qmenorm(
 p,
 mean = 0,
 sd = 1,
 lower = -Inf,
 upper = Inf,
 sderr = 0,
 meanerr = 0,
 lower.tail = TRUE,
 log.p = FALSE
)
rmenorm(n, mean = 0, sd = 1, lower = -Inf, upper = Inf, sderr = 0, meanerr = 0)
dmeunif(x, lower = 0, upper = 1, sderr = 0, meanerr = 0, log = FALSE)
pmeunif(
 q,
 lower = 0,
 upper = 1,
 sderr = 0,
 meanerr = 0,
 lower.tail = TRUE,
 log.p = FALSE
)
qmeunif(
 p,
 lower = 0,
 upper = 1,
 sderr = 0,
 meanerr = 0,
 lower.tail = TRUE,
 log.p = FALSE
)
rmeunif(n, lower = 0, upper = 1, sderr = 0, meanerr = 0)

x, q

vector of quantiles.

mean

vector of means.

sd

vector of standard deviations.

lower

lower truncation point.

upper

upper truncation point.

sderr

Standard deviation of measurement error distribution.

meanerr

Optional shift for the measurement error distribution.

log, log.p

logical; if TRUE, probabilities p are given as \log(p), or log density is returned.

lower.tail

logical; if TRUE (default), probabilities are P[X <= x], otherwise, P[X > x].

p

vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

## what does the distribution look like?
x <- seq(50, 90, by=1)
plot(x, dnorm(x, 70, 10), type="l", ylim=c(0,0.06)) ## standard Normal
lines(x, dtnorm(x, 70, 10, 60, 80), type="l") ## truncated Normal
## truncated Normal with small measurement error
lines(x, dmenorm(x, 70, 10, 60, 80, sderr=3), type="l")

## S3 method for class 'msm'
model.frame(formula, agg = FALSE, ...)
## S3 method for class 'msm'
model.matrix(object, model = "intens", state = 1, ...)

formula

A fitted multi-state model object, as returned by msm .

agg

Return the model frame in the efficient aggregated form used to calculate the likelihood internally for non-hidden Markov models. This has one row for each unique combination of from-state, to-state, time lag, covariate value and observation type. The variable named "(nocc)" counts how many observations of that combination there are in the original data.

...

Further arguments (not used).

object

A fitted multi-state model object, as returned by msm .

model

"intens" to return the design matrix for covariates on intensities, "misc" for misclassification probabilities, "hmm" for a general hidden Markov model, and "inits" for initial state probabilities in hidden Markov models.

state

State corresponding to the required covariate design matrix in a hidden Markov model.

msm(
 formula,
 subject = NULL,
 data = list(),
 qmatrix,
 gen.inits = FALSE,
 ematrix = NULL,
 hmodel = NULL,
 obstype = NULL,
 obstrue = NULL,
 covariates = NULL,
 covinits = NULL,
 constraint = NULL,
 misccovariates = NULL,
 misccovinits = NULL,
 miscconstraint = NULL,
 hcovariates = NULL,
 hcovinits = NULL,
 hconstraint = NULL,
 hranges = NULL,
 qconstraint = NULL,
 econstraint = NULL,
 initprobs = NULL,
 est.initprobs = FALSE,
 initcovariates = NULL,
 initcovinits = NULL,
 deathexact = NULL,
 death = NULL,
 exacttimes = FALSE,
 censor = NULL,
 censor.states = NULL,
 pci = NULL,
 phase.states = NULL,
 phase.inits = NULL,
 subject.weights = NULL,
 cl = 0.95,
 fixedpars = NULL,
 center = TRUE,
 opt.method = "optim",
 hessian = NULL,
 use.deriv = TRUE,
 use.expm = TRUE,
 analyticp = TRUE,
 na.action = na.omit,
 ...
)

formula

A formula giving the vectors containing the observed states and the corresponding observation times. For example,

state ~ time

Observed states should be numeric variables in the set 1, ...{}, n, where n is the number of states. Factors are allowed only if their levels are called "1", ...{}, "n".

The times can indicate different types of observation scheme, so be careful to choose the correct obstype.

For hidden Markov models, state refers to the outcome variable, which need not be a discrete state. It may also be a matrix, giving multiple observations at each time (see hmmMV ).

subject

Vector of subject identification numbers for the data specified by formula. If missing, then all observations are assumed to be on the same subject. These must be sorted so that all observations on the same subject are adjacent.

data

Optional data frame in which to interpret the variables supplied in formula, subject, covariates, misccovariates, hcovariates, obstype and obstrue.

qmatrix

Matrix which indicates the allowed transitions in the continuous-time Markov chain, and optionally also the initial values of those transitions. If an instantaneous transition is not allowed from state r to state s, then qmatrix should have (r,s) entry 0, otherwise it should be non-zero.

If supplying initial values yourself, then the non-zero entries should be those values. If using gen.inits=TRUE then the non-zero entries can be anything you like (conventionally 1). Any diagonal entry of qmatrix is ignored, as it is constrained to be equal to minus the sum of the rest of the row.

For example,

rbind( c( 0, 0.1, 0.01 ), c( 0.1, 0, 0.2 ), c( 0, 0, 0 ) )

represents a 'health - disease - death' model, with initial transition intensities 0.1 from health to disease, 0.01 from health to death, 0.1 from disease to health, and 0.2 from disease to death.

If the states represent ordered levels of severity of a disease, then this matrix should usually only allow transitions between adjacent states. For example, if someone was observed in state 1 ("mild") at their first observation, followed by state 3 ("severe") at their second observation, they are assumed to have passed through state 2 ("moderate") in between, and the 1,3 entry of qmatrix should be zero.

The initial intensities given here are with any covariates set to their means in the data (or set to zero, if center = FALSE). If any intensities are constrained to be equal using qconstraint, then the initial value is taken from the first of these (reading across rows).

gen.inits

If TRUE, then initial values for the transition intensities are generated automatically using the method in crudeinits.msm . The non-zero entries of the supplied qmatrix are assumed to indicate the allowed transitions of the model. This is not available for hidden Markov models, including models with misclassified states.

ematrix

If misclassification between states is to be modelled, this should be a matrix of initial values for the misclassification probabilities. The rows represent underlying states, and the columns represent observed states. If an observation of state s is not possible when the subject occupies underlying state r, then ematrix should have (r,s) entry 0. Otherwise ematrix should have (r,s) entry corresponding to the probability of observing s conditionally on occupying true state r. The diagonal of ematrix is ignored, as rows are constrained to sum to 1. For example,

rbind( c( 0, 0.1, 0 ), c( 0.1, 0, 0.1 ), c( 0, 0.1, 0 ) )

represents a model in which misclassifications are only permitted between adjacent states.

If any probabilities are constrained to be equal using econstraint, then the initial value is taken from the first of these (reading across rows).

For an alternative way of specifying misclassification models, see hmodel.

hmodel

Specification of the hidden Markov model (HMM). This should be a list of return values from HMM constructor functions. Each element of the list corresponds to the outcome model conditionally on the corresponding underlying state. Univariate constructors are described in thehmm-dists help page. These may also be grouped together to specify a multivariate HMM with a set of conditionally independent univariate outcomes at each time, as described in hmmMV .

For example, consider a three-state hidden Markov model. Suppose the observations in underlying state 1 are generated from a Normal distribution with mean 100 and standard deviation 16, while observations in underlying state 2 are Normal with mean 54 and standard deviation 18. Observations in state 3, representing death, are exactly observed, and coded as 999 in the data. This model is specified as

hmodel = list(hmmNorm(mean=100, sd=16), hmmNorm(mean=54, sd=18), hmmIdent(999))

The mean and standard deviation parameters are estimated starting from these initial values. If multiple parameters are constrained to be equal using hconstraint, then the initial value is taken from the value given on the first occasion that parameter appears in hmodel.

See the hmm-dists help page for details of the constructor functions for each univariate distribution.

A misclassification model, that is, a hidden Markov model where the outcomes are misclassified observations of the underlying states, can either be specified using a list of hmmCat or hmmIdent objects, or by using an ematrix.

For example,

ematrix = rbind( c( 0, 0.1, 0, 0 ), c( 0.1, 0, 0.1, 0 ), c( 0, 0.1, 0, 0), c( 0, 0, 0, 0) )

is equivalent to

hmodel = list( hmmCat(prob=c(0.9, 0.1, 0, 0)), hmmCat(prob=c(0.1, 0.8, 0.1, 0)), hmmCat(prob=c(0, 0.1, 0.9, 0)), hmmIdent())

obstype

A vector specifying the observation scheme for each row of the data. This can be included in the data frame data along with the state, time, subject IDs and covariates. Its elements should be either 1, 2 or 3, meaning as follows:

1

An observation of the process at an arbitrary time (a "snapshot" of the process, or "panel-observed" data). The states are unknown between observation times.

2

An exact transition time, with the state at the previous observation retained until the current observation. An observation may represent a transition to a different state or a repeated observation of the same state (e.g. at the end of follow-up). Note that if all transition times are known, more flexible models could be fitted with packages other than msm - see the note under exacttimes.

Note also that if the previous state was censored using censor, for example known only to be state 1 or state 2, then obstype 2 means that either state 1 is retained or state 2 is retained until the current observation - this does not allow for a change of state in the middle of the observation interval.

3

An exact transition time, but the state at the instant before entering this state is unknown. A common example is death times in studies of chronic diseases.

If obstype is not specified, this defaults to all 1. If obstype is a single number, all observations are assumed to be of this type. The obstype value for the first observation from each subject is not used.

This is a generalisation of the deathexact and exacttimes arguments to allow different schemes per observation. obstype overrides both deathexact and exacttimes.

exacttimes=TRUE specifies that all observations are of obstype 2.

deathexact = death.states specifies that all observations of death.states are of type 3. deathexact = TRUE specifies that all observations in the final absorbing state are of type 3.

obstrue

In misclassification models specified with ematrix, obstrue is a vector of logicals (TRUE or FALSE) or numerics (1 or 0) specifying which observations (TRUE, 1) are observations of the underlying state without error, and which (FALSE, 0) are realisations of a hidden Markov model.

In HMMs specified with hmodel, where the hidden state is known at some times, if obstrue is supplied it is assumed to contain the actual true state data. Elements of obstrue at times when the hidden state is unknown are set to NA. This allows the information from HMM outcomes generated conditionally on the known state to be included in the model, thus improving the estimation of the HMM outcome distributions.

HMMs where the true state is known to be within a specific set at specific times can be defined with a combination of censor and obstrue. In these models, a code is defined for the state outcome (see censor), and obstrue is set to 1 for observations where the true state is known to be one of the elements of censor.states at the corresponding time.

covariates

A formula or a list of formulae representing the covariates on the transition intensities via a log-linear model. If a single formula is supplied, like

covariates = ~ age + sex + treatment

then these covariates are assumed to apply to all intensities. If a named list is supplied, then this defines a potentially different model for each named intensity. For example,

covariates = list("1-2" = ~ age, "2-3" = ~ age + treatment)

specifies an age effect on the state 1 - state 2 transition, additive age and treatment effects on the state 2 - state 3 transition, but no covariates on any other transitions that are allowed by the qmatrix.

If covariates are time dependent, they are assumed to be constant in between the times they are observed, and the transition probability between a pair of times (t1, t2) is assumed to depend on the covariate value at t1.

covinits

Initial values for log-linear effects of covariates on the transition intensities. This should be a named list with each element corresponding to a covariate. A single element contains the initial values for that covariate on each transition intensity, reading across the rows in order. For a pair of effects constrained to be equal, the initial value for the first of the two effects is used.

For example, for a model with the above qmatrix and age and sex covariates, the following initialises all covariate effects to zero apart from the age effect on the 2-1 transition, and the sex effect on the 1-3 transition. covinits = list(sex=c(0, 0, 0.1, 0), age=c(0, 0.1, 0, 0))

For factor covariates, name each level by concatenating the name of the covariate with the level name, quoting if necessary. For example, for a covariate agegroup with three levels 0-15, 15-60, 60-, use something like

covinits = list("agegroup15-60"=c(0, 0.1, 0, 0), "agegroup60-"=c(0.1, 0.1, 0, 0))

If not specified or wrongly specified, initial values are assumed to be zero.

constraint

A list of one numeric vector for each named covariate. The vector indicates which covariate effects on intensities are constrained to be equal. Take, for example, a model with five transition intensities and two covariates. Specifying

constraint = list (age = c(1,1,1,2,2), treatment = c(1,2,3,4,5))

constrains the effect of age to be equal for the first three intensities, and equal for the fourth and fifth. The effect of treatment is assumed to be different for each intensity. Any vector of increasing numbers can be used as indicators. The intensity parameters are assumed to be ordered by reading across the rows of the transition matrix, starting at the first row, ignoring the diagonals.

Negative elements of the vector can be used to indicate that particular covariate effects are constrained to be equal to minus some other effects. For example:

constraint = list (age = c(-1,1,1,2,-2), treatment = c(1,2,3,4,5))

constrains the second and third age effects to be equal, the first effect to be minus the second, and the fifth age effect to be minus the fourth. For example, it may be realisitic that the effect of a covariate on the "reverse" transition rate from state 2 to state 1 is minus the effect on the "forward" transition rate, state 1 to state 2. Note that it is not possible to specify exactly which of the covariate effects are constrained to be positive and which negative. The maximum likelihood estimation chooses the combination of signs which has the higher likelihood.

For categorical covariates, defined as factors, specify constraints as follows:

list(..., covnameVALUE1 = c(...), covnameVALUE2 = c(...), ...)

where covname is the name of the factor, and VALUE1, VALUE2, ... are the labels of the factor levels (usually excluding the baseline, if using the default contrasts).

Make sure the contrasts option is set appropriately, for example, the default

options(contrasts=c(contr.treatment, contr.poly))

sets the first (baseline) level of unordered factors to zero, then the baseline level is ignored in this specification.

To assume no covariate effect on a certain transition, use the fixedpars argument to fix it at its initial value (which is zero by default) during the optimisation.

misccovariates

A formula representing the covariates on the misclassification probabilities, analogously to covariates, via multinomial logistic regression. Only used if the model is specified using ematrix, rather than hmodel.

This must be a single formula - lists are not supported, unlike covariates. If a different model on each probability is required, include all covariates in this formula, and use fixedpars to fix some of their effects (for particular probabilities) at their default initial values of zero.

misccovinits

Initial values for the covariates on the misclassification probabilities, defined in the same way as covinits. Only used if the model is specified using ematrix.

miscconstraint

A list of one vector for each named covariate on misclassification probabilities. The vector indicates which covariate effects on misclassification probabilities are constrained to be equal, analogously to constraint. Only used if the model is specified using ematrix.

hcovariates

List of formulae the same length as hmodel, defining any covariates governing the hidden Markov outcome models. The covariates operate on a suitably link-transformed linear scale, for example, log scale for a Poisson outcome model. If there are no covariates for a certain hidden state, then insert a NULL in the corresponding place in the list. For example, hcovariates = list(~acute + age, ~acute, NULL).

hcovinits

Initial values for the hidden Markov model covariate effects. A list of the same length as hcovariates. Each element is a vector with initial values for the effect of each covariate on that state. For example, the above hcovariates can be initialised with hcovariates = list(c(-8, 0), -8, NULL). Initial values must be given for all or no covariates, if none are given these are all set to zero. The initial value given in the hmodel constructor function for the corresponding baseline parameter is interpreted as the value of that parameter with any covariates fixed to their means in the data. If multiple effects are constrained to be equal using hconstraint, then the initial value is taken from the first of the multiple initial values supplied.

hconstraint

A named list. Each element is a vector of constraints on the named hidden Markov model parameter. The vector has length equal to the number of times that class of parameter appears in the whole model.

For example consider the three-state hidden Markov model described above, with normally-distributed outcomes for states 1 and 2. To constrain the outcome variance to be equal for states 1 and 2, and to also constrain the effect of acute on the outcome mean to be equal for states 1 and 2, specify

hconstraint = list(sd = c(1,1), acute=c(1,1))

Note this excludes initial state occupancy probabilities and covariate effects on those probabilities, which cannot be constrained.

hranges

Range constraints for hidden Markov model parameters. Supplied as a named list, with each element corresponding to the named hidden Markov model parameter. This element is itself a list with two elements, vectors named "lower" and "upper". These vectors each have length equal to the number of times that class of parameter appears in the whole model, and give the corresponding mininum amd maximum allowable values for that parameter. Maximum likelihood estimation is performed with these parameters constrained in these ranges (through a log or logit-type transformation). Lower bounds of -Inf and upper bounds of Inf can be given if the parameter is unbounded above or below.

For example, in the three-state model above, to constrain the mean for state 1 to be between 0 and 6, and the mean of state 2 to be between 7 and 12, supply

hranges=list(mean=list(lower=c(0, 7), upper=c(6, 12)))

These default to the natural ranges, e.g. the positive real line for variance parameters, and [0,1] for probabilities. Therefore hranges need not be specified for such parameters unless an even stricter constraint is desired. If only one limit is supplied for a parameter, only the first occurrence of that parameter is constrained.

Initial values should be strictly within any ranges, and not on the range boundary, otherwise optimisation will fail with a "non-finite value" error.

qconstraint

A vector of indicators specifying which baseline transition intensities are equal. For example,

qconstraint = c(1,2,3,3)

constrains the third and fourth intensities to be equal, in a model with four allowed instantaneous transitions. When there are covariates on the intensities and center=TRUE (the default), qconstraint is applied to the intensities with covariates taking the values of the means in the data. When center=FALSE, qconstraint is applied to the intensities with covariates set to zero.

econstraint

A similar vector of indicators specifying which baseline misclassification probabilities are constrained to be equal. Only used if the model is specified using ematrix, rather than hmodel.

initprobs

Only used in hidden Markov models. Underlying state occupancy probabilities at each subject's first observation. Can either be a vector of nstates elements with common probabilities to all subjects, or a nsubjects by nstates matrix of subject-specific probabilities. This refers to observations after missing data and subjects with only one observation have been excluded.

If these are estimated (see est.initprobs), then this represents an initial value, and defaults to equal probability for each state. Otherwise this defaults to c(1, rep(0, nstates-1)), that is, in state 1 with a probability of 1. Scaled to sum to 1 if necessary. The state 1 occupancy probability should be non-zero.

est.initprobs

Only used in hidden Markov models. If TRUE, then the underlying state occupancy probabilities at the first observation will be estimated, starting from a vector of initial values supplied in the initprobs argument. Structural zeroes are allowed: if any of these initial values are zero they will be fixed at zero during optimisation, even if est.initprobs=TRUE, and no covariate effects on them are estimated. The exception is state 1, which should have non-zero occupancy probability.

Note that the free parameters during this estimation exclude the state 1 occupancy probability, which is fixed at one minus the sum of the other probabilities.

initcovariates

Formula representing covariates on the initial state occupancy probabilities, via multinomial logistic regression. The linear effects of these covariates, observed at the individual's first observation time, operate on the log ratio of the state r occupancy probability to the state 1 occupancy probability, for each r = 2 to the number of states. Thus the state 1 occupancy probability should be non-zero. If est.initprobs is TRUE, these effects are estimated starting from their initial values. If est.initprobs is FALSE, these effects are fixed at theit initial values.

initcovinits

Initial values for the covariate effects initcovariates. A named list with each element corresponding to a covariate, as in covinits. Each element is a vector with (1 - number of states) elements, containing the initial values for the linear effect of that covariate on the log odds of that state relative to state 1, from state 2 to the final state. If initcovinits is not specified, all covariate effects are initialised to zero.

deathexact

Vector of indices of absorbing states whose time of entry is known exactly, but the individual is assumed to be in an unknown transient state ("alive") at the previous instant. This is the usual situation for times of death in chronic disease monitoring data. For example, if you specify deathexact = c(4, 5) then states 4 and 5 are assumed to be exactly-observed death states.

See the obstype argument. States of this kind correspond to obstype=3. deathexact = TRUE indicates that the final absorbing state is of this kind, and deathexact = FALSE or deathexact = NULL (the default) indicates that there is no state of this kind.

The deathexact argument is overridden by obstype or exacttimes.

Note that you do not always supply a deathexact argument, even if there are states that correspond to deaths, because they do not necessarily have obstype=3. If the state is known between the time of death and the previous observation, then you should specify obstype=2 for the death times, or exacttimes=TRUE if the state is known at all times, and the deathexact argument is ignored.

death

Old name for the deathexact argument. Overridden by deathexact if both are supplied. Deprecated.

exacttimes

By default, the transitions of the Markov process are assumed to take place at unknown occasions in between the observation times. If exacttimes is set to TRUE, then the observation times are assumed to represent the exact times of transition of the process. The subject is assumed to be in the same state between these times. An observation may represent a transition to a different state or a repeated observation of the same state (e.g. at the end of follow-up). This is equivalent to every row of the data having obstype = 2. See the obstype argument. If both obstype and exacttimes are specified then exacttimes is ignored.

Note that the complete history of the multi-state process is known with this type of data. The models which msm fits have the strong assumption of constant (or piecewise-constant) transition rates. Knowing the exact transition times allows more realistic models to be fitted with other packages. For example parametric models with sojourn distributions more flexible than the exponential can be fitted with the flexsurv package, or semi-parametric models can be implemented with survival in conjunction with mstate.

censor

A state, or vector of states, which indicates censoring. Censoring means that the observed state is known only to be one of a particular set of states. For example, censor=999 indicates that all observations of 999 in the vector of observed states are censored states. By default, this means that the true state could have been any of the transient (non-absorbing) states. To specify corresponding true states explicitly, use a censor.states argument.

Note that in contrast to the usual terminology of survival analysis, here it is the state which is considered to be censored, rather than the event time. If at the end of a study, an individual has not died, but their true state is known, then censor is unnecessary, since the standard multi-state model likelihood is applicable. Also a "censored" state here can be at any time, not just at the end.

For hidden Markov models, censoring may indicate either a set of possible observed states, or a set of (hidden) true states. The later case is specified by setting the relevant elements of obstrue to 1 (and NA otherwise).

Note in particular that general time-inhomogeneous Markov models with piecewise constant transition intensities can be constructed using the censor facility. If the true state is unknown on occasions when a piecewise constant covariate is known to change, then censored states can be inserted in the data on those occasions. The covariate may represent time itself, in which case the pci option to msm can be used to perform this trick automatically, or some other time-dependent variable.

Not supported for multivariate hidden Markov models specified with hmmMV .

censor.states

Specifies the underlying states which censored observations can represent. If censor is a single number (the default) this can be a vector, or a list with one element. If censor is a vector with more than one element, this should be a list, with each element a vector corresponding to the equivalent element of censor. For example

censor = c(99, 999), censor.states = list(c(2,3), c(3,4))

means that observations coded 99 represent either state 2 or state 3, while observations coded 999 are really either state 3 or state 4.

pci

Model for piecewise-constant intensities. Vector of cut points defining the times, since the start of the process, at which intensities change for all subjects. For example

pci = c(5, 10)

specifies that the intensity changes at time points 5 and 10. This will automatically construct a model with a categorical (factor) covariate called timeperiod, with levels "[-Inf,5)", "[5,10)" and "[10,Inf)", where the first level is the baseline. This covariate defines the time period in which the observation was made. Initial values and constraints on covariate effects are specified the same way as for a model with a covariate of this name, for example,

covinits = list("timeperiod[5,10)"=c(0.1,0.1), "timeperiod[10,Inf)"=c(0.1,0.1))

Thus if pci is supplied, you cannot have a previously-existing variable called timeperiod as a covariate in any part of a msm model.

To assume piecewise constant intensities for some transitions but not others with pci, use the fixedpars argument to fix the appropriate covariate effects at their default initial values of zero.

Internally, this works by inserting censored observations in the data at times when the intensity changes but the state is not observed.

If the supplied times are outside the range of the time variable in the data, pci is ignored and a time-homogeneous model is fitted.

After fitting a time-inhomogeneous model, qmatrix.msm can be used to obtain the fitted intensity matrices for each time period, for example,

qmatrix.msm(example.msm, covariates=list(timeperiod="[5,Inf)"))

This facility does not support interactions between time and other covariates. Such models need to be specified "by hand", using a state variable with censored observations inserted. Note that the data component of the msm object returned from a call to msm with pci supplied contains the states with inserted censored observations and time period indicators. These can be used to construct such models.

Note that you do not need to use pci in order to model the effect of a time-dependent covariate in the data. msm will automatically assume that covariates are piecewise-constant and change at the times when they are observed. pci is for when you want all intensities to change at the same pre-specified times for all subjects.

pci is not supported for multivariate hidden Markov models specified with hmmMV . An approximate equivalent can be constructed by creating a variable in the data to represent the time period, and treating that as a covariate using the covariates argument to msm. This will assume that the value of this variable is constant between observations.

phase.states

Indices of states which have a two-phase sojourn distribution. This defines a semi-Markov model, in which the hazard of an onward transition depends on the time spent in the state.

This uses the technique described by Titman and Sharples (2009). A hidden Markov model is automatically constructed on an expanded state space, where the phases correspond to the hidden states. The "tau" proportionality constraint described in this paper is currently not supported.

Covariates, constraints, deathexact and censor are expressed with respect to the expanded state space. If not supplied by hand, initprobs is defined automatically so that subjects are assumed to begin in the first of the two phases.

Hidden Markov models can additionally be given phased states. The user supplies an outcome distribution for each original state using hmodel, which is expanded internally so that it is assumed to be the same within each of the phased states. initprobs is interpreted on the expanded state space. Misclassification models defined using ematrix are not supported, and these must be defined using hmmCat or hmmIdent constructors, as described in the hmodel section of this help page. Or the HMM on the expanded state space can be defined by hand.

Output functions are presented as it were a hidden Markov model on the expanded state space, for example, transition probabilities between states, covariate effects on transition rates, or prevalence counts, are not aggregated over the hidden phases.

Numerical estimation will be unstable when there is weak evidence for a two-phase sojourn distribution, that is, if the model is close to Markov.

See d2phase for the definition of the two-phase distribution and the interpretation of its parameters.

This is an experimental feature, and some functions are not implemented. Please report any experiences of using this feature to the author!

phase.inits

Initial values for phase-type models. A list with one component for each "two-phased" state. Each component is itself a list of two elements. The first of these elements is a scalar defining the transition intensity from phase 1 to phase 2. The second element is a matrix, with one row for each potential destination state from the two-phased state, and two columns. The first column is the transition rate from phase 1 to the destination state, and the second column is the transition rate from phase 2 to the destination state. If there is only one destination state, then this may be supplied as a vector.

In phase type models, the initial values for transition rates out of non-phased states are taken from the qmatrix supplied to msm, and entries of this matrix corresponding to transitions out of phased states are ignored.

subject.weights

Name of a variable in the data (unquoted) giving weights to apply to each subject in the data when calculating the log-likelihood as a weighted sum over subjects. These are taken from the first observation for each subject, and any weights supplied for subsequent observations are not used.

Weights at the observation level are not supported.

cl

Width of symmetric confidence intervals for maximum likelihood estimates, by default 0.95.

fixedpars

Vector of indices of parameters whose values will be fixed at their initial values during the optimisation. These are given in the order: transition intensities (reading across rows of the transition matrix), covariates on intensities (ordered by intensities within covariates), hidden Markov model parameters, including misclassification probabilities or parameters of HMM outcome distributions (ordered by parameters within states), hidden Markov model covariate parameters (ordered by covariates within parameters within states), initial state occupancy probabilities (excluding the first probability, which is fixed at one minus the sum of the others).

If there are equality constraints on certain parameters, then fixedpars indexes the set of unique parameters, excluding those which are constrained to be equal to previous parameters.

To fix all parameters, specify fixedpars = TRUE.

This can be useful for profiling likelihoods, and building complex models stage by stage.

center

If TRUE (the default, unless fixedpars=TRUE) then covariates are centered at their means during the maximum likelihood estimation. This usually improves stability of the numerical optimisation.

opt.method

If "optim", "nlm" or "bobyqa", then the corresponding R function will be used for maximum likelihood estimation. optim is the default. "bobyqa" requires the package minqa to be installed. See the help of these functions for further details. Advanced users can also add their own optimisation methods, see the source for optim.R in msm for some examples.

If "fisher", then a specialised Fisher scoring method is used (Kalbfleisch and Lawless, 1985) which can be faster than the generic methods, though less robust. This is only available for Markov models with panel data (obstype=1), that is, not for models with censored states, hidden Markov models, exact observation or exact death times (obstype=2,3).

hessian

If TRUE then standard errors and confidence intervals are obtained from a numerical estimate of the Hessian (the observed information matrix). This is the default when maximum likelihood estimation is performed. If all parameters are fixed at their initial values and no optimisation is performed, then this defaults to FALSE. If requested, the actual Hessian is returned in x$paramdata$opt$hessian, where x is the fitted model object.

If hessian is set to FALSE, then standard errors and confidence intervals are obtained from the Fisher (expected) information matrix, if this is available. This may be preferable if the numerical estimation of the Hessian is computationally intensive, or if the resulting estimate is non-invertible or not positive definite.

use.deriv

If TRUE then analytic first derivatives are used in the optimisation of the likelihood, where available and an appropriate quasi-Newton optimisation method, such as BFGS, is being used. Analytic derivatives are not available for all models.

use.expm

If TRUE then any matrix exponentiation needed to calculate the likelihood is done using the expm package. Otherwise the original routines used in msm 1.2.4 and earlier are used. Set to FALSE for backward compatibility, and let the package maintainer know if this gives any substantive differences.

analyticp

By default, the likelihood for certain simpler 3, 4 and 5 state models is calculated using an analytic expression for the transition probability (P) matrix. For all other models, matrix exponentiation is used to obtain P. To revert to the original method of using the matrix exponential for all models, specify analyticp=FALSE. See the PDF manual for a list of the models for which analytic P matrices are implemented.

na.action

What to do with missing data: either na.omit to drop it and carry on, or na.fail to stop with an error. Missing data includes all NAs in the states, times, subject or obstrue, all NAs at the first observation for a subject for covariates in initcovariates, all NAs in other covariates (excluding the last observation for a subject), all NAs in obstype (excluding the first observation for a subject), and any subjects with only one observation (thus no observed transitions).

...

Optional arguments to the general-purpose optimisation routine, optim by default. For example method="Nelder-Mead" to change the optimisation algorithm from the "BFGS" method that msm calls by default.

It is often worthwhile to normalize the optimisation using control=list(fnscale = a), where a is the a number of the order of magnitude of the -2 log likelihood.

If 'false' convergence is reported and the standard errors cannot be calculated due to a non-positive-definite Hessian, then consider tightening the tolerance criteria for convergence. If the optimisation takes a long time, intermediate steps can be printed using the trace argument of the control list. See optim for details.

For the Fisher scoring method, a control list can be supplied in the same way, but the only supported options are reltol, trace and damp. The first two are used in the same way as for optim . If the algorithm fails with a singular information matrix, adjust damp from the default of zero (to, e.g. 1). This adds a constant identity matrix multiplied by damp to the information matrix during optimisation.

### Heart transplant data
### For further details and background to this example, see
### Jackson (2011) or the PDF manual in the doc directory.
print(cav[1:10,])
twoway4.q <- rbind(c(-0.5, 0.25, 0, 0.25), c(0.166, -0.498, 0.166, 0.166),
c(0, 0.25, -0.5, 0.25), c(0, 0, 0, 0))
statetable.msm(state, PTNUM, data=cav)
crudeinits.msm(state ~ years, PTNUM, data=cav, qmatrix=twoway4.q)
cav.msm <- msm( state ~ years, subject=PTNUM, data = cav,
 qmatrix = twoway4.q, deathexact = 4, 
 control = list ( trace = 2, REPORT = 1 ) )
cav.msm
qmatrix.msm(cav.msm)
pmatrix.msm(cav.msm, t=10)
sojourn.msm(cav.msm)

msm.form.qoutput(x, covariates = "mean", cl = 0.95, digits = 4, ...)
msm.form.eoutput(x, covariates = "mean", cl = 0.95, digits = 4, ...)

x

A fitted multi-state model object, as returned by msm .

covariates

Covariate values defining the "baseline" parameters (see qmatrix.msm ).

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

digits

Minimum number of significant digits for the formatted character matrix returned as an attribute. This is passed to format . Defaults to 4.

...

Other arguments to be passed to format .

call

The original call to msm , as returned by match.call .

Qmatrices

A list of matrices. The first component, labelled logbaseline, is a matrix containing the estimated transition intensities on the log scale with any covariates fixed at their means in the data (or at zero, if center=FALSE). The component labelled baseline is the equivalent on the untransformed scale. Each remaining component is a matrix giving the linear effects of the labelled covariate on the matrix of log intensities. To extract an estimated intensity matrix on the natural scale, at an arbitrary combination of covariate values, use the function qmatrix.msm .

QmatricesSE

The standard error matrices corresponding to Qmatrices.

QmatricesL, QmatricesU

Corresponding lower and upper symmetric confidence limits, of width 0.95 unless specified otherwise by the cl argument.

Ematrices

A list of matrices. The first component, labelled logitbaseline, is the estimated misclassification probability matrix (expressed as as log odds relative to the probability of the true state) with any covariates fixed at their means in the data (or at zero, if center=FALSE). The component labelled baseline is the equivalent on the untransformed scale. Each remaining component is a matrix giving the linear effects of the labelled covariate on the matrix of logit misclassification probabilities. To extract an estimated misclassification probability matrix on the natural scale, at an arbitrary combination of covariate values, use the function ematrix.msm .

EmatricesSE

The standard error matrices corresponding to Ematrices.

EmatricesL, EmatricesU

Corresponding lower and upper symmetric confidence limits, of width 0.95 unless specified otherwise by the cl argument.

minus2loglik

Minus twice the maximised log-likelihood.

deriv

Derivatives of the minus twice log-likelihood at its maximum.

estimates

Vector of untransformed maximum likelihood estimates returned from optim . Transition intensities are on the log scale and misclassification probabilities are given as log odds relative to the probability of the true state.

estimates.t

Vector of transformed maximum likelihood estimates with intensities and probabilities on their natural scales.

fixedpars

Indices of estimates which were fixed during the maximum likelihood estimation.

center

Indicator for whether the estimation was performed with covariates centered on their means in the data.

covmat

Covariance matrix corresponding to estimates.

ci

Matrix of confidence intervals corresponding to estimates.t

opt

Return value from the optimisation routine (such as optim or nlm ), giving information about the results of the optimisation.

foundse

Logical value indicating whether the Hessian was positive-definite at the supposed maximum of the likelihood. If not, the covariance matrix of the parameters is unavailable. In these cases the optimisation has probably not converged to a maximum.

data

A list giving the data used for the model fit, for use in post-processing. To extract it, use the methods model.frame.msm or model.matrix.msm .

The format of this element changed in version 1.4 of msm, so that it now contains a model.frame object mf with all the variables used in the model. The previous format (an ad-hoc list of vectors and matrices) can be obtained with the function recreate.olddata(msmobject), where msmobject is the object returned by msm.

qmodel

A list of objects representing the transition matrix structure and options for likelihood calculation. See qmodel.object for documentation of the components.

emodel

A list of objects representing the misclassification model structure, for models specified using the ematrix argument to msm . See emodel.object .

qcmodel

A list of objects representing the model for covariates on transition intensities. See qcmodel.object .

ecmodel

A list of objects representing the model for covariates on transition intensities. See ecmodel.object .

hmodel

A list of objects representing the hidden Markov model structure. See hmodel.object .

cmodel

A list giving information about censored states. See cmodel.object .

pci

Cut points for time-varying intensities, as supplied to msm , but excluding any that are outside the times observed in the data.

paramdata

A list giving information about the parameters of the multi-state model. See paramdata.object .

cl

Confidence interval width, as supplied to msm .

covariates

Formula for covariates on intensities, as supplied to msm .

misccovariates

Formula for covariates on misclassification probabilities, as supplied to msm .

hcovariates

Formula for covariates on hidden Markov model outcomes, as supplied to msm .

initcovariates

Formula for covariates on initial state occupancy probabilities in hidden Markov models, as supplied to msm .

sojourn

A list as returned by sojourn.msm , with components:

mean = estimated mean sojourn times in the transient states, with covariates fixed at their means (if center=TRUE) or at zero (if center=FALSE).

se = corresponding standard errors.

msm2Surv(data, subject, time, state, covs = NULL, Q)

data

Data frame in the format expected by a msm model fit with exacttimes=TRUE or all obstype=2. Each row represents an observation of a state, and the time variable contains the exact and complete transition times of the underlying process. This is explained in more detail in the help page for msm , section obstype=2.

subject

Name of the subject ID in the data (character format, i.e. quoted).

time

Name of the time variable in the data (character).

state

Name of the state variable in the data (character).

covs

Vector of covariate names to carry through (character). If not supplied, this is taken to be all remaining variables in the data.

Q

Transition intensity matrix. This should have number of rows and number of columns both equal to the number of states. If an instantaneous transition is not allowed from state r to state s, then Q should have (r,s) entry 0, otherwise it should be non-zero. The diagonal entries are ignored.

subj days status age treat

1 0 1 66 1

1 27 2 66 1

1 75 3 66 1

1 97 4 66 1

1 1106 4 69 1

2 0 1 49 0

2 90 2 49 0

2 1037 2 51 0

id from to Tstart Tstop time status age treat trans

1 1 2 0 27 27 1 66 1 1

1 1 4 0 27 27 0 66 1 2

1 2 3 27 75 48 1 66 1 3

1 2 4 27 75 48 0 66 1 4

1 3 4 75 97 22 1 69 1 5

2 1 2 0 90 90 1 49 0 1

2 1 4 0 90 90 0 49 0 2

2 2 3 90 1037 947 0 49 0 3

2 2 4 90 1037 947 0 49 0 4

id

Subject ID

from

Starting state of the transition

to

Finishing state of the transition

Tstart

The starting time of the transition

Tstop

The finishing time of the transition

time

The time difference = Tstop - Tstart

status

Event or censoring indicator, with 1 indicating an observed transition, and 0 indicating censoring

trans

Transition number

msmdat <- data.frame(
 subj = c(1, 1, 1, 1, 1, 2, 2, 2),
 days = c(0, 27, 75, 97, 1106, 0, 90, 1037),
 status = c(1, 2, 3, 4, 4, 1, 2, 2),
 age = c(66, 66, 66, 66, 69, 49, 49, 51),
 treat = c(1, 1, 1, 1, 1, 0, 0, 0)
)
# transitions only allowed to next state up or state 4
Q <- rbind(c(1, 1, 0, 1), 
 c(0, 1, 1, 1),
 c(0, 0, 1, 1),
 c(0, 0, 0, 0))
dat <- msm2Surv(data=msmdat, subject="subj", time="days", state="status", 
 Q=Q)
dat
attr(dat, "trans")

odds.msm(x, odds.scale = 1, cl = 0.95)

x

Output from msm representing a fitted multi-state model.

odds.scale

Vector with same elements as number of covariates on misclassification probabilities. Corresponds to the increase in each covariate used to calculate its odds ratio. Defaults to all 1.

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

inits

Vector of initial values for distinct parameters which are being estimated. These have been transformed to the real line (e.g. by log), and exclude parameters being fixed at their initial values, parameters defined to be always fixed (e.g. binomial denominators) and parameters constrained to equal previous ones.

plabs

Names of parameters in allinits.

allinits

Vector of parameter values before estimation, including those which are fixed or constrained to equal other parameters, and transformed to the real line.

hmmpars

Indices of allinits which represent baseline parameters of hidden Markov outcome models (thus excluding covariate effects in HMMs and initial state occupancy probabilities).

fixed

TRUE if all parameters are fixed, FALSE otherwise.

fixedpars

Indices of parameters in allinits which are fixed, either by definition or as requested by the user in the fixedpars argument to msm . Excludes parameters fixed by constraining to equal other parameters.

notfixed

Indices of parameters which are not fixed by the definition of fixedpars.

optpars

Indices of parameters in allinits being estimated, thus those included in inits.

auxpars

Indices of "auxiliary" parameters which are always fixed, for example, binomial denominators (hmmBinom ) and the which parameter in hmmIdent .

constr

Vector of integers, of length npars, indicating which sets of parameters are constrained to be equal to each other. If two of these integers are equal the corresponding parameters are equal. A negative element indicates that parameter is defined to be minus some other parameter (this is used for covariate effects on transition intensities).

npars

Total number of parameters, equal to length(allinits).

nfix

Number of fixed parameters, equal to length(fixedpars).

nopt

Number of parameters being estimated, equal to length(inits) and length(optpars).

ndup

Number of parameters defined as duplicates of previous parameters by equality constraints (currently unused).

ranges

Matrix of defined ranges for each parameter on the natural scale (e.g. 0 to infinity for rate parameters).

opt

Object returned by the optimisation routine (such as optim ).

foundse

TRUE if standard errors are available after optimisation. If FALSE the optimisation probably hasn't converged.

lik

Minus twice the log likelihood at the parameter estimates.

deriv

Derivatives of the minus twice log likelihood at the parameter estimates, if available.

information

Corresponding expected information matrix at the parameter estimates, if available.

params

Vector of parameter values after maximum likelihood estimation, corresponding to allinits, still on the real-line transformed scale.

covmat

Covariance matrix corresponding to params.

ci

Matrix of confidence intervals corresponding to params, with nominal coverage (default 0.95) defined by the cl argument of msm .

estimates.t

Vector of parameter estimates, as params but with parameters on their natural scales.

pearson.msm(
 x,
 transitions = NULL,
 timegroups = 3,
 intervalgroups = 3,
 covgroups = 3,
 groups = NULL,
 boot = FALSE,
 B = 500,
 next.obstime = NULL,
 N = 100,
 indep.cens = TRUE,
 maxtimes = NULL,
 pval = TRUE
)

x

A fitted multi-state model, as returned by msm .

transitions

This should be an integer vector indicating which interval transitions should be grouped together in the contingency table. Its length should be the number of allowed interval transitions, excluding transitions from absorbing states to absorbing states.

The allowed interval transitions are the set of pairs of states (a,b) for which it is possible to observe a at one time and b at any later time. For example, in a "well-disease-death" model with allowed instantaneous 1-2, 2-3 transitions, there are 5 allowed interval transitions. In numerical order, these are 1-1, 1-2, 1-3, 2-2 and 2-3, excluding absorbing-absorbing transitions.

Then, to group transitions 1-1,1-2 together, and transitions 2-2,2-3 together, specify

transitions = c(1,1,2,3,3).

Only transitions from the same state may be grouped. By default, each interval transition forms a separate group.

timegroups

Number of groups based on quantiles of the time since the start of the process.

intervalgroups

Number of groups based on quantiles of the time interval between observations, within time groups

covgroups

Number of groups based on quantiles of \sum_r q_{irr}, where q_{irr} are the diagonal entries of the transition intensity matrix for the ith transition. These are a function of the covariate effects and the covariate values at the ith transition: q_{irr} is minus the sum of the off-diagonal entries q_{rs}^{(0)} exp (\beta_{rs}^T z_i) on the rth row.

Thus covgroups summarises the impact of covariates at each observation, by calculating the overall rate of progression through states at that observation.

For time-inhomogeneous models specified using the pci argument to msm , if the only covariate is the time period, covgroups is set to 1, since timegroups ensures that transitions are grouped by time.

groups

A vector of arbitrary groups in which to categorise each transition. This can be an integer vector or a factor. This can be used to diagnose specific areas of poor fit. For example, the contingency table might be grouped by arbitrary combinations of covariates to detect types of individual for whom the model fits poorly.

The length of groups should be x$data$n, the number of observations used in the model fit, which is the number of observations in the original dataset with any missing values excluded. The value of groups at observation i is used to categorise the transition which ends at observation i. Values of groups at the first observation for each subject are ignored.

boot

Estimate an "exact" p-value using a parametric bootstrap.

All objects used in the original call to msm which produced x, such as the qmatrix, should be in the working environment, or else an “object not found” error will be given. This enables the original model to be refitted to the replicate datasets.

Note that groups cannot be used with bootstrapping, as the simulated observations will not be in the same categories as the original observations.

B

Number of bootstrap replicates.

next.obstime

This is a vector of length x$data$n (the number of observations used in the model fit) giving the time to the next scheduled observation following each time point. This is only used when times to death are known exactly.

For individuals who died (entered an absorbing state) before the next scheduled observation, and the time of death is known exactly, next.obstime would be greater than the observed death time.

If the individual did not die, and a scheduled observation did follow that time point, next.obstime should just be the same as the time to that observation.

next.obstime is used to determine a grouping of the time interval between observations, which should be based on scheduled observations. If exact times to death were used in the grouping, then shorter intervals would contain excess deaths, and the goodness-of-fit statistic would be biased.

If next.obstime is unknown, it is multiply-imputed using a product-limit estimate based on the intervals to observations other than deaths. The resulting tables of transitions are averaged over these imputations. This may be slow.

N

Number of imputations for the estimation of the distribution of the next scheduled observation time, when there are exact death times.

indep.cens

If TRUE, then times to censoring are included in the estimation of the distribution to the next scheduled observation time. If FALSE, times to censoring are assumed to be systematically different from other observation times.

maxtimes

A vector of length x$data$n, or a common scalar, giving an upper bound for the next scheduled observation time. Used in the multiple imputation when times to death are known exactly. If a value greater than maxtimes is simulated, then the next scheduled observation is taken as censored. This should be supplied, if known. If not supplied, this is taken to be the maximum interval occurring in the data, plus one time unit. For observations which are not exact death times, this should be the time since the previous observation.

pval

Calculate a p-value using the improved approximation of Titman (2009). This is optional since it is not needed during bootstrapping, and it is computationally non-trivial. Only available currently for non-hidden Markov models for panel data without exact death times. Also not available for models with censoring, including time-homogeneous models fitted with the pci option to msm .

list("\"test\"")

the fourth element of the list, is a data frame with one row containing the Pearson-type goodness-of-fit test statistic stat. The test statistic is the sum of the deviances. For panel-observed data without exact death times, misclassification or censored observations, p is the p-value for the test statistic calculated using the improved approximation of Titman (2009).

For these models, for comparison with older versions of the package, test also presents p.lower and p.upper, which are theoretical lower and upper limits for the p-value of the test statistic, based on chi-squared distributions with df.lower and df.upper degrees of freedom, respectively. df.upper is the number of independent cells in the contingency table, and df.lower is df.upper minus the number of estimated parameters in the model.

list("\"intervalq\"")

(not printed by default) contains the definition of the grouping of the intervals between observations. These groups are defined by quantiles within the groups corresponding to the time since the start of the process.

list("\"sim\"")

If there are exact death times, this contains simulations of the contingency tables and test statistics for each imputation of the next scheduled sampling time. These are averaged over to produce the presented tables and test statistic. This element is not printed by default.

With exact death times, the null variance of the test statistic (formed by taking mean of simulated test statistics) is less than twice the mean (Titman, 2008), and the null distribution is not chi-squared. In this case, p.upper is an upper limit for the true asymptotic p-value, but p.lower is not a lower limit, and is not presented.

list("\"boot\"")

If the bootstrap has been used, the element will contain the bootstrap replicates of the test statistics (not printed by default).

list("\"lambda\"")

If the Titman (2009) p-value has been calculated, this contains the weights defining the null distribution of the test statistic as a weighted sum of chi-squared(1) random variables (not printed by default).

psor.q <- rbind(c(0,0.1,0,0),c(0,0,0.1,0),c(0,0,0,0.1),c(0,0,0,0))
psor.msm <- msm(state ~ months, subject=ptnum, data=psor,
 qmatrix = psor.q, covariates = ~ollwsdrt+hieffusn,
 constraint = list(hieffusn=c(1,1,1),ollwsdrt=c(1,1,2)))
pearson.msm(psor.msm, timegroups=2, intervalgroups=2, covgroups=2)
# More 1-2, 1-3 and 1-4 observations than expected in shorter time
# intervals - the model fits poorly.
# A random effects model might accommodate such fast progressors.

dpexp(x, rate = 1, t = 0, log = FALSE)
ppexp(q, rate = 1, t = 0, lower.tail = TRUE, log.p = FALSE)
qpexp(p, rate = 1, t = 0, lower.tail = TRUE, log.p = FALSE)
rpexp(n = 1, rate = 1, t = 0, start = min(t))

x, q

vector of quantiles.

rate

vector of rates.

t

vector of the same length as rate, giving the times at which the rate changes. The values of t should be in increasing order.

log, log.p

logical; if TRUE, probabilities p are given as log(p), or log density is returned.

lower.tail

logical; if TRUE (default), probabilities are P[X <= x], otherwise, P[X > x].

p

vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

start

numeric scalar; delayed entry time. The random deviates will be left truncated from this start time.

x <- seq(0.1, 50, by=0.1)
rate <- c(0.1, 0.2, 0.05, 0.3)
t <- c(0, 10, 20, 30)
## standard exponential distribution
plot(x, dexp(x, 0.1), type="l")
## distribution with piecewise constant rate
lines(x, dpexp(x, rate, t), type="l", lty=2)
## standard exponential distribution
plot(x, pexp(x, 0.1), type="l")
## distribution with piecewise constant rate
lines(x, ppexp(x, rate, t), type="l", lty=2)

phasemeans.msm(
 x,
 covariates = "mean",
 ci = c("none", "normal", "bootstrap"),
 cl = 0.95,
 B = 1000,
 cores = NULL
)

x

A fitted multi-state model, as returned by msm .

covariates

Covariate values, see qmatrix.msm .

ci

If "none" (the default) no confidence intervals are calculated. Otherwise "normal", or "boot" as described by qmatrix.msm .

cl

Width of the symmetric confidence interval, relative to 1.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs.

cores

Number of cores to use for bootstrapping using parallel processing. See boot.msm for more details.

## S3 method for class 'msm'
plot(
 x,
 from = NULL,
 to = NULL,
 range = NULL,
 covariates = "mean",
 legend.pos = NULL,
 xlab = "Time",
 ylab = "Fitted survival probability",
 lwd = 1,
 ...
)

x

Output from msm , representing a fitted multi-state model object.

from

States from which to consider survival. Defaults to the complete set of transient states.

to

Absorbing state to consider. Defaults to the highest-labelled absorbing state.

range

Vector of two elements, giving the range of times to plot for.

covariates

Covariate values for which to evaluate the expected probabilities. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

list (age = 60, sex = 1)

legend.pos

Vector of the x and y position, respectively, of the legend.

xlab

x axis label.

ylab

y axis label.

lwd

Line width. See par .

...

Other arguments to be passed to the generic plot and lines functions.

## S3 method for class 'prevalence.msm'
plot(
 x,
 mintime = NULL,
 maxtime = NULL,
 timezero = NULL,
 initstates = NULL,
 interp = c("start", "midpoint"),
 censtime = Inf,
 subset = NULL,
 covariates = "population",
 misccovariates = "mean",
 piecewise.times = NULL,
 piecewise.covariates = NULL,
 xlab = "Times",
 ylab = "Prevalence (%)",
 lwd.obs = 1,
 lwd.exp = 1,
 lty.obs = 1,
 lty.exp = 2,
 col.obs = "blue",
 col.exp = "red",
 legend.pos = NULL,
 ...
)

x

A fitted multi-state model produced by msm .

mintime

Minimum time at which to compute the observed and expected prevalences of states.

maxtime

Maximum time at which to compute the observed and expected prevalences of states.

timezero

Initial time of the Markov process. Expected values are forecasted from here. Defaults to the minimum of the observation times given in the data.

initstates

Optional vector of the same length as the number of states. Gives the numbers of individuals occupying each state at the initial time, to be used for forecasting expected prevalences. The default is those observed in the data. These should add up to the actual number of people in the study at the start.

interp

Interpolation method for observed states, see prevalence.msm .

censtime

Subject-specific maximum follow-up times, see prevalence.msm .

subset

Vector of the subject identifiers to calculated observed prevalences for.

covariates

Covariate values for which to forecast expected state occupancy. See prevalence.msm — if this function runs too slowly, as it may if there are continuous covariates, replace covariates="population" with covariates="mean".

misccovariates

(Misclassification models only) Values of covariates on the misclassification probability matrix. See prevalence.msm .

piecewise.times

Times at which piecewise-constant intensities change. See prevalence.msm .

piecewise.covariates

Covariates on which the piecewise-constant intensities depend. See prevalence.msm .

xlab

x axis label.

ylab

y axis label.

lwd.obs

Line width for observed prevalences. See par .

lwd.exp

Line width for expected prevalences. See par .

lty.obs

Line type for observed prevalences. See par .

lty.exp

Line type for expected prevalences. See par .

col.obs

Line colour for observed prevalences. See par .

col.exp

Line colour for expected prevalences. See par .

legend.pos

Vector of the x and y position, respectively, of the legend.

...

Further arguments to be passed to the generic plot function.

## S3 method for class 'survfit.msm'
plot(
 x,
 from = 1,
 to = NULL,
 range = NULL,
 covariates = "mean",
 interp = c("start", "midpoint"),
 ci = c("none", "normal", "bootstrap"),
 B = 100,
 legend.pos = NULL,
 xlab = "Time",
 ylab = "Survival probability",
 lty = 1,
 lwd = 1,
 col = "red",
 lty.ci = 2,
 lwd.ci = 1,
 col.ci = "red",
 mark.time = TRUE,
 col.surv = "blue",
 lty.surv = 2,
 lwd.surv = 1,
 survdata = FALSE,
 ...
)

x

Output from msm , representing a fitted multi-state model object.

from

Non-absorbing state from which to consider survival. Defaults to state 1. The fitted probabilities will then be calculated as the transition probabilities from this state to to. The empirical survival curve plots survival from the first observation of from (where this exists) to the first entry time into to.

to

Absorbing state to consider. Defaults to the highest-labelled absorbing state.

range

Vector of two elements, giving the range of times to plot for.

covariates

Covariate values for which to evaluate the expected probabilities. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

list (age = 60, sex = 1)

but note the empirical curve is plotted for the full population. To consider subsets for the empirical curve, set survdata=TRUE to extract the survival data and build a survival plot by hand using plot.survfit .

interp

If interp="start" (the default) then the entry time into the absorbing state is assumed to be the time it is first observed in the data.

If interp="midpoint" then the entry time into the absorbing state is assumed to be halfway between the time it is first observed and the previous observation time. This is generally more reasonable for "progressive" models with observations at arbitrary times.

ci

If "none" (the default) no confidence intervals are plotted. If "normal" or "bootstrap", confidence intervals are plotted based on the respective method in pmatrix.msm . This is very computationally-intensive, since intervals must be computed at a series of times.

B

Number of bootstrap or normal replicates for the confidence interval. The default is 100 rather than the usual 1000, since these plots are for rough diagnostic purposes.

legend.pos

Vector of the x and y position, respectively, of the legend.

xlab

x axis label.

ylab

y axis label.

lty

Line type for the fitted curve. See par .

lwd

Line width for the fitted curve. See par .

col

Colour for the fitted curve. See par .

lty.ci

Line type for the fitted curve confidence limits. See par .

lwd.ci

Line width for the fitted curve confidence limits. See par .

col.ci

Colour for the fitted curve confidence limits. See par .

mark.time

Mark the empirical survival curve at each censoring point, see lines.survfit .

col.surv

Colour for the empirical survival curve, passed to lines.survfit . See par .

lty.surv

Line type for the empirical survival curve, passed to lines.survfit . See par .

lwd.surv

Line width for the empirical survival curve, passed to lines.survfit . See par .

survdata

Set to TRUE to return the survival data frame constructed when plotting the empirical curve. This can be used for constructing survival plots by hand using plot.survfit .

...

Other arguments to be passed to the plot function which draws the fitted curve, or the lines.survfit function which draws the empirical curve.

plotprog.msm(
 formula,
 subject,
 data,
 legend.pos = NULL,
 xlab = "Time",
 ylab = "1 - incidence probability",
 lwd = 1,
 xlim = NULL,
 mark.time = TRUE,
 ...
)

formula

A formula giving the vectors containing the observed states and the corresponding observation times. For example,

state ~ time

Observed states should be in the set 1, ...{}, n, where n is the number of states.

subject

Vector of subject identification numbers for the data specified by formula. If missing, then all observations are assumed to be on the same subject. These must be sorted so that all observations on the same subject are adjacent.

data

An optional data frame in which the variables represented by state, time and subject can be found.

legend.pos

Vector of the x and y position, respectively, of the legend.

xlab

x axis label.

ylab

y axis label.

lwd

Line width. See par .

xlim

x axis limits, e.g. c(0,10) for an axis ranging from 0 to 10. Default is the range of observation times.

mark.time

Mark the empirical survival curve at each censoring point, see lines.survfit .

...

Other arguments to be passed to the plot and lines.survfit functions.

pmatrix.msm(
 x = NULL,
 t = 1,
 t1 = 0,
 covariates = "mean",
 ci = c("none", "normal", "bootstrap"),
 cl = 0.95,
 B = 1000,
 cores = NULL,
 qmatrix = NULL,
 ...
)

x

A fitted multi-state model, as returned by msm .

t

The time interval to estimate the transition probabilities for, by default one unit.

t1

The starting time of the interval. Used for models x with piecewise-constant intensities fitted using the pci option to msm . The probabilities will be computed on the interval [t1, t1+t].

covariates

The covariate values at which to estimate the transition probabilities. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

list (age = 60, sex = 1)

If some covariates are specified but not others, the missing ones default to zero.

For time-inhomogeneous models fitted using the pci option to msm , "covariates" here include only those specified using the covariates argument to msm , and exclude the artificial covariates representing the time period.

For time-inhomogeneous models fitted "by hand" by using a time-dependent covariate in the covariates argument to msm , the function pmatrix.piecewise.msm should be used to to calculate transition probabilities.

ci

If "normal", then calculate a confidence interval for the transition probabilities by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then calculating the resulting transition probability matrix for each replicate. See, e.g. Mandel (2013) for a discussion of this approach.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

If "none" (the default) then no confidence interval is calculated.

cl

Width of the symmetric confidence interval, relative to 1.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs

cores

Number of cores to use for bootstrapping using parallel processing. See boot.msm for more details.

qmatrix

A transition intensity matrix. Either this or a fitted model x must be supplied. No confidence intervals are available if qmatrix is supplied.

...

Optional arguments to be passed to MatrixExp to control the method of computing the matrix exponential.

pmatrix.piecewise.msm(
 x = NULL,
 t1,
 t2,
 times,
 covariates = NULL,
 ci = c("none", "normal", "bootstrap"),
 cl = 0.95,
 B = 1000,
 cores = NULL,
 qlist = NULL,
 ...
)

x

A fitted multi-state model, as returned by msm . This should be a non-homogeneous model, whose transition intensity matrix depends on a time-dependent covariate.

t1

The start of the time interval to estimate the transition probabilities for.

t2

The end of the time interval to estimate the transition probabilities for.

times

Cut points at which the transition intensity matrix changes.

covariates

A list with number of components one greater than the length of times. Each component of the list is specified in the same way as the covariates argument to pmatrix.msm . The components correspond to the covariate values in the intervals

(t1, times[1]], (times[1], times[2]], ..., (times[length(times)], t2]

(assuming that all elements of times are in the interval (t1, t2)).

ci

If "normal", then calculate a confidence interval for the transition probabilities by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then calculating the resulting transition probability matrix for each replicate.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

If "none" (the default) then no confidence interval is calculated.

cl

Width of the symmetric confidence interval, relative to 1.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs

cores

Number of cores to use for bootstrapping using parallel processing. See boot.msm for more details.

qlist

A list of transition intensity matrices, of length one greater than the length of times. Either this or a fitted model x must be supplied. No confidence intervals are available if (just) qlist is supplied.

...

Optional arguments to be passed to MatrixExp to control the method of computing the matrix exponential.

## Not run: 
## In a clinical study, suppose patients are given a placebo in the
## first 5 weeks, then they begin treatment 1 at 5 weeks, and
## a combination of treatments 1 and 2 from 10 weeks.
## Suppose a multi-state model x has been fitted for the patients'
## progress, with treat1 and treat2 as time dependent covariates.
## Cut points for when treatment covariate changes
times <- c(0, 5, 10)
## Indicators for which treatments are active in the four intervals
## defined by the three cut points
covariates <- list( list (treat1=0, treat2=0), list (treat1=0, treat2=0), list(treat1=1, treat2=0),
list(treat1=1, treat2=1) )
## Calculate transition probabilities from the start of the study to 15 weeks
pmatrix.piecewise.msm(x, 0, 15, times, covariates)
## End(Not run)

pnext.msm(
 x,
 covariates = "mean",
 ci = c("normal", "bootstrap", "delta", "none"),
 cl = 0.95,
 B = 1000,
 cores = NULL
)

x

A fitted multi-state model, as returned by msm .

covariates

The covariate values at which to estimate the intensities. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

list (age = 60, sex = 1)

ci

If "normal" (the default) then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then transforming.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

If "delta" then confidence intervals are calculated based on the delta method SEs of the log rates, but this is not recommended since it may not respect the constraint that probabilities are less than one.

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs.

cores

Number of cores to use for bootstrapping using parallel processing. See boot.msm for more details.

ppass.msm(
 x = NULL,
 qmatrix = NULL,
 tot,
 start = "all",
 covariates = "mean",
 piecewise.times = NULL,
 piecewise.covariates = NULL,
 ci = c("none", "normal", "bootstrap"),
 cl = 0.95,
 B = 1000,
 cores = NULL,
 ...
)

x

A fitted multi-state model, as returned by msm .

qmatrix

Instead of x, you can simply supply a transition intensity matrix in qmatrix.

tot

Finite time to forecast the passage probabilites for.

start

Starting state (integer). By default (start="all"), this will return a matrix one row for each starting state.

Alternatively, this can be used to obtain passage probabilities from a set of states, rather than single states. To achieve this, state is set to a vector of weights, with length equal to the number of states in the model. These weights should be proportional to the probability of starting in each of the states in the desired set, so that weights of zero are supplied for other states. The function will calculate the weighted average of the passage probabilities from each of the corresponding states.

covariates

Covariate values defining the intensity matrix for the fitted model x, as supplied to qmatrix.msm .

piecewise.times

For models with time-dependent covariates, this defines the cut points in time at which the transition intensity matrix changes. This is not required for models fitted with the pci option to msm , which are handled automatically.

piecewise.covariates

For models with time-dependent covariates, this is the list of covariates for each time period defined by piecewise.times, in the format documented for the covariates argument to pmatrix.piecewise.msm . This is not required for models fitted with the pci option to msm , which are handled automatically.

ci

If "normal", then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

If "none" (the default) then no confidence interval is calculated.

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 boot.msm for more details.

...

Arguments to pass to MatrixExp .

Q <- rbind(c(-0.5, 0.25, 0, 0.25), c(0.166, -0.498, 0.166, 0.166),
 c(0, 0.25, -0.5, 0.25), c(0, 0, 0, 0))
## ppass[1,2](t) converges to 0.5 with t, since given in state 1, the
## probability of going to the absorbing state 4 before visiting state
## 2 is 0.5, and the chance of still being in state 1 at t decreases.
ppass.msm(qmatrix=Q, tot=2)
ppass.msm(qmatrix=Q, tot=20)
ppass.msm(qmatrix=Q, tot=100)
Q <- Q[1:3,1:3]; diag(Q) <- 0; diag(Q) <- -rowSums(Q)
## Probability of about 1/2 of visiting state 3 by time 10.5, the
## median first passage time
ppass.msm(qmatrix=Q, tot=10.5)
## Mean first passage time from state 2 to state 3 is 10.02: similar
## to the median
efpt.msm(qmatrix=Q, tostate=3)

prevalence.msm(
 x,
 times = NULL,
 timezero = NULL,
 initstates = NULL,
 covariates = "population",
 misccovariates = "mean",
 piecewise.times = NULL,
 piecewise.covariates = NULL,
 ci = c("none", "normal", "bootstrap"),
 cl = 0.95,
 B = 1000,
 cores = NULL,
 interp = c("start", "midpoint"),
 censtime = Inf,
 subset = NULL,
 plot = FALSE,
 ...
)

x

A fitted multi-state model produced by msm .

times

Series of times at which to compute the observed and expected prevalences of states.

timezero

Initial time of the Markov process. Expected values are forecasted from here. Defaults to the minimum of the observation times given in the data.

initstates

Optional vector of the same length as the number of states. Gives the numbers of individuals occupying each state at the initial time, to be used for forecasting expected prevalences. The default is those observed in the data. These should add up to the actual number of people in the study at the start.

covariates

Covariate values for which to forecast expected state occupancy. With the default covariates="population", expected prevalences are produced by summing model predictions over the covariates observed in the original data, for a fair comparison with the observed prevalences. This may be slow, particularly with continuous covariates.

Predictions for fixed covariates can be obtained by supplying covariate values in the standard way, as in qmatrix.msm . Therefore if covariates="population" is too slow, using the mean observed values through covariates="mean" may give a reasonable approximation.

This argument is ignored if piecewise.times is specified. If there are a mixture of time-constant and time-dependent covariates, then the values for all covariates should be supplied in piecewise.covariates.

misccovariates

(Misclassification models only) Values of covariates on the misclassification probability matrix for converting expected true to expected misclassified states. Ignored if covariates="population", otherwise defaults to the mean values of the covariates in the data set.

piecewise.times

Times at which piecewise-constant intensities change. See pmatrix.piecewise.msm for how to specify this. Ignored if covariates="population". This is only required for time-inhomogeneous models specified using explicit time-dependent covariates, and should not be used for models specified using "pci".

piecewise.covariates

Covariates on which the piecewise-constant intensities depend. See pmatrix.piecewise.msm for how to specify this. Ignored if covariates="population".

ci

If "normal", then calculate a confidence interval for the expected prevalences by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then calculating the expected prevalences for each replicate.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

If "none" (the default) then no confidence interval is calculated.

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 boot.msm for more details.

interp

Suppose an individual was observed in states S_{r-1} and S_r at two consecutive times t_{r-1} and t_r, and we want to estimate 'observed' prevalences at a time t between t_{r-1} and t_r.

If interp="start", then individuals are assumed to be in state S_{r-1} at time t, the same state as they were at t_{r-1}.

If interp="midpoint" then if t <= (t_{r-1} + t_r) / 2, the midpoint of t_{r-1} and t_r, the state at t is assumed to be S_{r-1}, otherwise S_{r}. This is generally more reasonable for "progressive" models.

censtime

Adjustment to the observed prevalences to account for limited follow-up in the data.

If the time is greater than censtime and the patient has reached an absorbing state, then that subject will be removed from the risk set. For example, if patients have died but would only have been observed up to this time, then this avoids overestimating the proportion of people who are dead at later times.

This can be supplied as a single value, or as a vector with one element per subject (after any subset has been taken), in the same order as the original data. This vector also only includes subjects with complete data, thus it excludes for example subjects with only one observation (thus no observed transitions), and subjects for whom every observation has missing values. (Note, to help construct this, the complete data used for the model fit can be accessed with model.frame(x), where x is the fitted model object)

This is ignored if it is less than the subject's maximum observation time.

subset

Subset of subjects to calculate observed prevalences for.

plot

Generate a plot of observed against expected prevalences. See plot.prevalence.msm

...

Further arguments to pass to plot.prevalence.msm .

Observed

Table of observed numbers of individuals in each state at each time

Observed percentages

Corresponding percentage of the individuals at risk at each time.

Expected

Table of corresponding expected numbers.

Expected percentages

Corresponding percentage of the individuals at risk at each time.

## S3 method for class 'msm'
print(x, covariates = NULL, digits = 4, ...)
printnew.msm(x, covariates = NULL, digits = 4, ...)

x

Output from msm , representing a fitted multi-state model object.

covariates

Covariates for which to print “baseline” transition intensities or misclassification probabilities. See qmatrix.msm for more details.

digits

Minimum number of significant digits, passed to format . Defaults to 4.

...

Other arguments to be passed to format .

printold.msm(x, ...)

x

Output from msm , representing a fitted multi-state model object.

...

Other arguments to be passed to format .

ptnum (numeric) Patient identification number

months (numeric) Examination time in months

state (numeric) Clinical state of PsA. Patients in states 1, 2, 3 and 4

have 0, 1 to 4, 5 to 9 and 10 or more damaged joints,

respectively.

hieffusn (numeric) Presence of five or more effusions

ollwsdrt (character) Erythrocyte sedimentation rate of less than 15 mm/h

## Four-state progression-only model with high effusion and low
## sedimentation rate as covariates on the progression rates. High
## effusion is assumed to have the same effect on the 1-2, 2-3, and 3-4
## progression rates, while low sedimentation rate has the same effect
## on the 1-2 and 2-3 intensities, but a different effect on the 3-4. 
data(psor)
psor.q <- rbind(c(0,0.1,0,0),c(0,0,0.1,0),c(0,0,0,0.1),c(0,0,0,0))
psor.msm <- msm(state ~ months, subject=ptnum, data=psor, 
 qmatrix = psor.q, covariates = ~ollwsdrt+hieffusn,
 constraint = list(hieffusn=c(1,1,1),ollwsdrt=c(1,1,2)),
 fixedpars=FALSE, control = list(REPORT=1,trace=2), method="BFGS")
qmatrix.msm(psor.msm)
sojourn.msm(psor.msm)
hazard.msm(psor.msm)

npars

Number of covariate effect parameters. This is defined as the number of covariates on intensities (with factors expanded as contrasts) multiplied by the number of allowed transitions in the model.

Note if msm was called with covariates set to a list of different covariates for different intensities, then this will include covariate effects that are implicitly defined as zero by this list. The information in paramdata objects can be used to identify wich ones are fixed at zero.

This also includes any timeperiod covariates in a time-inhomogeneous model defined by the pci option to msm .

ndpars

Number of distinct covariate effect parameters, as npars, but after any equality constraints have been applied.

ncovs

Number of covariates on intensities, with factors expanded as contrasts.

constr

List of equality constraints on these covariate effects, as supplied in the constraint argument to msm .

covlabels

Names / labels of these covariates in the model matrix (see model.matrix.msm ).

inits

Initial values for these covariate effects, as a vector formed from the covinits list supplied to msm .

covmeans

Means of these covariates in the data (excluding data not required to fit the model, such as observations with missing data in other elements or subjects' last observations). This includes means of 0/1 factor contrasts as well as continuous covariates (for historic reasons, which may not be sensible).

qgeneric(pdist, p, special = NULL, ...)

pdist

Probability distribution function, for example, pnorm for the normal distribution, which must be defined in the current workspace. This should accept and return vectorised parameters and values. It should also return the correct values for the entire real line, for example a positive distribution should have pdist(x)==0 for x<0.

p

Vector of probabilities to find the quantiles for.

special

Vector of character strings naming arguments of the distribution function that should not be vectorised over. Used, for example, for the rate and t arguments in qpexp .

...

The remaining arguments define parameters of the distribution pdist. These MUST be named explicitly.

This may also contain the standard arguments log.p (logical; default FALSE, if TRUE, probabilities p are given as log(p)), and lower.tail (logical; if TRUE (default), probabilities are P[X <= x] otherwise, P[X > x].).

If the distribution is bounded above or below, then this should contain arguments lbound and ubound respectively, and these will be returned if p is 0 or 1 respectively. Defaults to -Inf and Inf respectively.

qnorm(c(0.025, 0.975), 0, 1)
qgeneric(pnorm, c(0.025, 0.975), mean=0, sd=1) # must name the arguments

qmatrix.msm(
 x,
 covariates = "mean",
 sojourn = FALSE,
 ci = c("delta", "normal", "bootstrap", "none"),
 cl = 0.95,
 B = 1000,
 cores = NULL
)

x

A fitted multi-state model, as returned by msm .

covariates

The covariate values at which to estimate the intensity matrix. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula. Or more clearly, a named list,

list (age = 60, sex = 1)

If some covariates are specified but not others, the missing ones default to zero.

With covariates="mean", for factor / categorical variables, the mean of the 0/1 dummy variable for each factor level is used, representing an average over all values in the data, rather than a specific factor level.

sojourn

Set to TRUE if the estimated sojourn times and their standard errors should also be returned.

ci

If "delta" (the default) then confidence intervals are calculated by the delta method, or by simple transformation of the Hessian in the very simplest cases. Normality on the log scale is assumed.

If "normal", then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then transforming.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs.

cores

Number of cores to use for bootstrapping using parallel processing. See boot.msm for more details.

estimate

Estimated transition intensity matrix.

SE

Corresponding approximate standard errors.

L

Lower confidence limits

U

Upper confidence limits

nstates

Number of states

iso

Label for which basic structure the model is isomorphic to in the list of structures for which analytic formulae for the transition probabilities are implemented in the source file src/analyticp.c. This list is given by the internal object msm:::.msm.graphs which is defined and documented in the source file R/constants.R.

iso is 0 if the analytic P matrix is not implemented for this structure, or if analytic P matrix calculations are disabled using use.analyticp=FALSE in the call to msm .

perm

Permutation required to convert the base isomorphism into the structure of this model. A vector of integers whose rth element is the state number in the base structure representing state r in the current structure.

qperm

Inverse permutation: vector whose rth element is the state number in the current structure representing the rth state in the base structure.

npars

Number of allowed instantaneous transitions, equal to sum(imatrix).

imatrix

Indicator matrix for allowed instantaneous transitions. This has (r,s) entry 1 if the transition from r to s is permitted in continuous time, and 0 otherwise. The diagonal entries are arbitrarily set to 0.

qmatrix

Matrix of initial values for the transition intensities, supplied as the qmatrix argument of msm .

inits

Vector of these initial values, reading across rows of qmatrix and excluding the diagonal and disallowed transitions.

constr

Indicators for equality constraints on baseline intensities, taken from the qconstraint argument to msm , and mapped if necessary to the set (1,2,3,...).

ndpars

Number of distinct allowed instantaneous transitions, after applying equality constraints.

expm

Use expm package to calculate matrix exponentials for likelihoods, as supplied to the use.expm argument of msm . TRUE or FALSE.

qratio.msm(
 x,
 ind1,
 ind2,
 covariates = "mean",
 ci = c("delta", "normal", "bootstrap", "none"),
 cl = 0.95,
 B = 1000,
 cores = NULL
)

x

A fitted multi-state model, as returned by msm .

ind1

Pair of numbers giving the indices in the intensity matrix of the numerator of the ratio, for example, c(1,2).

ind2

Pair of numbers giving the indices in the intensity matrix of the denominator of the ratio, for example, c(2,1).

covariates

The covariate values at which to estimate the intensities. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

list (age = 60, sex = 1)

ci

If "delta" (the default) then confidence intervals are calculated by the delta method.

If "normal", then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then transforming.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs

cores

Number of cores to use for bootstrapping using parallel processing. See boot.msm for more details.

recreate.olddata(x)

x

Object returned by the msm function, representing a fitted multi-state model.

scoreresid.msm(x, plot = FALSE)

x

A fitted multi-state model, as returned by msm .

plot

If TRUE, display a simple plot of the residuals in subject order, labelled by subject identifiers

sim.msm(
 qmatrix,
 maxtime,
 covs = NULL,
 beta = NULL,
 obstimes = 0,
 start = 1,
 mintime = 0
)

qmatrix

The transition intensity matrix of the Markov process. The diagonal of qmatrix is ignored, and computed as appropriate so that the rows sum to zero. For example, a possible qmatrix for a three state illness-death model with recovery is:

rbind( c( 0, 0.1, 0.02 ), c( 0.1, 0, 0.01 ), c( 0, 0, 0 ) )

maxtime

Maximum time for the simulated process.

covs

Matrix of time-dependent covariates, with one row for each observation time and one column for each covariate.

beta

Matrix of linear covariate effects on log transition intensities. The rows correspond to different covariates, and the columns to the transition intensities. The intensities are ordered by reading across rows of the intensity matrix, starting with the first, counting the positive off-diagonal elements of the matrix.

obstimes

Vector of times at which the covariates are observed.

start

Starting state of the process. Defaults to 1.

mintime

Starting time of the process. Defaults to 0.

states

Simulated states through which the process moves. This ends with either an absorption before obstime, or a transient state at obstime.

times

Exact times at which the process changes to the corresponding states

qmatrix

The given transition intensity matrix

qmatrix <- rbind(
 c(-0.2, 0.1, 0.1 ),
 c(0.5, -0.6, 0.1 ),
 c(0, 0, 0)
 )
sim.msm(qmatrix, 30)

simfitted.msm(x, drop.absorb = TRUE, drop.pci.imp = TRUE)

x

A fitted multi-state model object as returned by msm .

drop.absorb

Should repeated observations in an absorbing state be omitted. Use the default of TRUE to avoid warnings when using the simulated dataset for further msm fits. Or set to FALSE if exactly the same number of observations as the original data are needed.

drop.pci.imp

In time-inhomogeneous models fitted using the pci option to msm , censored observations are inserted into the data by msm at the times where the intensity changes, but dropped by default when simulating from the fitted model using this function. Set this argument to FALSE to keep these observations and the corresponding indicator variable.

simmulti.msm(
 data,
 qmatrix,
 covariates = NULL,
 death = FALSE,
 start,
 ematrix = NULL,
 misccovariates = NULL,
 hmodel = NULL,
 hcovariates = NULL,
 censor.states = NULL,
 drop.absorb = TRUE
)

data

A data frame with a mandatory column named time, representing observation times. The optional column named subject, corresponds to subject identification numbers. If not given, all observations are assumed to be on the same individual. Observation times should be sorted within individuals. The optional column named cens indicates the times at which simulated states should be censored. If cens==0 then the state is not censored, and if cens==k, say, then all simulated states at that time which are in the set censor.states are replaced by k. Other named columns of the data frame represent any covariates, which may be time-constant or time-dependent. Time-dependent covariates are assumed to be constant between the observation times.

qmatrix

The transition intensity matrix of the Markov process, with any covariates set to zero. The diagonal of qmatrix is ignored, and computed as appropriate so that the rows sum to zero. For example, a possible qmatrix for a three state illness-death model with recovery is:

rbind( c( 0, 0.1, 0.02 ), c( 0.1, 0, 0.01 ), c( 0, 0, 0 ) )

covariates

List of linear covariate effects on log transition intensities. Each element is a vector of the effects of one covariate on all the transition intensities. The intensities are ordered by reading across rows of the intensity matrix, starting with the first, counting the positive off-diagonal elements of the matrix.

For example, for a multi-state model with three transition intensities, and two covariates x and y on each intensity,

covariates=list(x = c(-0.3,-0.3,-0.3), y=c(0.1, 0.1, 0.1))

death

Vector of indices of the death states. A death state is an absorbing state whose time of entry is known exactly, but the individual is assumed to be in an unknown transient state ("alive") at the previous instant. This is the usual situation for times of death in chronic disease monitoring data. For example, if you specify death = c(4, 5) then states 4 and 5 are assumed to be death states.

death = TRUE indicates that the final state is a death state, and death = FALSE (the default) indicates that there is no death state.

start

A vector with the same number of elements as there are distinct subjects in the data, giving the states in which each corresponding individual begins. Or a single number, if all of these are the same. Defaults to state 1 for each subject.

ematrix

An optional misclassification matrix for generating observed states conditionally on the simulated true states. As defined in msm .

misccovariates

Covariate effects on misclassification probabilities via multinomial logistic regression. Linear effects operate on the log of each probability relative to the probability of classification in the correct state. In same format as covariates.

hmodel

An optional hidden Markov model for generating observed outcomes conditionally on the simulated true states. As defined in msm . Multivariate outcomes (hmmMV) are not supported.

hcovariates

List of the same length as hmodel, defining any covariates governing the hidden Markov outcome models. Unlike in the msm function, this should also define the values of the covariate effects. Each element of the list is a named vector of the initial values for each set of covariates for that state. For example, for a three-state hidden Markov model with two, one and no covariates on the state 1, 2 and 3 outcome models respectively,

hcovariates = list (c(acute=-8, age=0), c(acute=-8), NULL)

censor.states

Set of simulated states which should be replaced by a censoring indicator at censoring times. By default this is all transient states (representing alive, with unknown state).

drop.absorb

Drop repeated observations in the absorbing state, retaining only one.

subject

Subject identification indicators

time

Observation times

state

Simulated (true) state at the corresponding time

obs

Observed outcome at the corresponding time, if ematrix or hmodel was supplied

keep

Row numbers of the original data. Useful when drop.absorb=TRUE, to show which rows were not dropped

### Simulate 100 individuals with common observation times
sim.df <- data.frame(subject = rep(1:100, rep(13,100)), time = rep(seq(0, 24, 2), 100))
qmatrix <- rbind(c(-0.11, 0.1, 0.01 ),
 c(0.05, -0.15, 0.1 ),
 c(0.02, 0.07, -0.09))
simmulti.msm(sim.df, qmatrix)

sojourn.msm(
 x,
 covariates = "mean",
 ci = c("delta", "normal", "bootstrap", "none"),
 cl = 0.95,
 B = 1000
)

x

A fitted multi-state model, as returned by msm .

covariates

The covariate values at which to estimate the mean sojourn times. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

a list of values, with optional names. For example,

list(60, 1), where the order of the list follows the order of the covariates originally given in the model formula, or a named list, e.g.

list (age = 60, sex = 1)

ci

If "delta" (the default) then confidence intervals are calculated by the delta method, or by simple transformation of the Hessian in the very simplest cases.

If "normal", then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then transforming.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

cl

Width of the symmetric confidence interval to present. Defaults to 0.95.

B

Number of bootstrap replicates, or number of normal simulations from the distribution of the MLEs

estimates

Estimated mean sojourn times in the transient states.

SE

Corresponding standard errors.

L

Lower confidence limits.

U

Upper confidence limits.

statetable.msm(state, subject, data = NULL)

state

Observed states, assumed to be ordered by time within each subject.

subject

Subject identification numbers corresponding to state. If not given, all observations are assumed to be on the same subject.

data

An optional data frame in which the variables represented by subject and state can be found.

## Heart transplant data
data(cav)
## 148 deaths from state 1, 48 from state 2 and 55 from state 3.
statetable.msm(state, PTNUM, data=cav)

## S3 method for class 'msm'
summary(object, hazard.scale = 1, ...)

object

A fitted multi-state model object, as returned by msm .

hazard.scale

Vector with same elements as number of covariates on transition rates. Corresponds to the increase in each covariate used to calculate its hazard ratio. Defaults to all 1.

...

Further arguments passed to prevalence.msm .

prevalences

Output from prevalence.msm .

hazard

Output from hazard.msm .

hazard.scale

Value of the hazard.scale argument.

surface.msm(
 x,
 params = c(1, 2),
 np = 10,
 type = c("contour", "filled.contour", "persp", "image"),
 point = NULL,
 xrange = NULL,
 yrange = NULL,
 ...
)
## S3 method for class 'msm'
contour(x, ...)
## S3 method for class 'msm'
persp(x, ...)
## S3 method for class 'msm'
image(x, ...)

x

Output from msm , representing a fitted msm model.

params

Integer vector with two elements, giving the indices of the parameters to vary. All other parameters will be fixed. Defaults to c(1,2), representing the first two log transition intensities. See the fixedpars argument to msm for a definition of these indices.

np

Number of grid points to use in each direction, by default 10. An np x np grid will be used to evaluate the likelihood surface. If 100 likelihood function evaluations is slow, then reduce this.

type

Character string specifying the type of plot to produce.

point

Vector of length n, where n is the number of parameters in the model, including the parameters that will be varied here. This specifies the point at which to fix the likelihood. By default, this is the maximum likelihood estimates stored in the fitted model x, x$estimates.

xrange

Range to plot for the first varied parameter. Defaults to plus and minus two standard errors, obtained from the Hessian at the maximum likelihood estimate.

yrange

Range to plot for the second varied parameter. Defaults to plus and minus two standard errors, obtained from the Hessian at the maximum likelihood estimate.

...

Further arguments to be passed to the plotting function.

## S3 method for class 'msm'
tidy(x, ...)

x

Object returned by msm , representing a fitted multi-state model.

...

Other arguments (currently unused).

## S3 method for class 'msm.est'
tidy(x, ...)

x

Output of qmatrix.msm , pmatrix.msm , ematrix.msm , pnext.msm or ppass.msm , which all return objects of class "msm.est".

...

Further arguments (unused).

## S3 method for class 'msm.estbystate'
tidy(x, ...)

x

Output of totlos.msm , envisits.msm or efpt.msm , which return objects of class "msm.estbystate".

...

Further arguments (unused).

## S3 method for class 'msm.prevalence'
tidy(x, ...)

x

Output of prevalence.msm .

...

Further arguments (unused).

dtnorm(x, mean = 0, sd = 1, lower = -Inf, upper = Inf, log = FALSE)
ptnorm(
 q,
 mean = 0,
 sd = 1,
 lower = -Inf,
 upper = Inf,
 lower.tail = TRUE,
 log.p = FALSE
)
qtnorm(
 p,
 mean = 0,
 sd = 1,
 lower = -Inf,
 upper = Inf,
 lower.tail = TRUE,
 log.p = FALSE
)
rtnorm(n, mean = 0, sd = 1, lower = -Inf, upper = Inf)

x, q

vector of quantiles.

mean

vector of means.

sd

vector of standard deviations.

lower

lower truncation point.

upper

upper truncation point.

log

logical; if TRUE, return log density or log hazard.

lower.tail

logical; if TRUE (default), probabilities are P[X <= x], otherwise, P[X > x].

log.p

logical; if TRUE, probabilities p are given as log(p).

p

vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

x <- seq(50, 90, by=1)
plot(x, dnorm(x, 70, 10), type="l", ylim=c(0,0.06)) ## standard Normal distribution
lines(x, dtnorm(x, 70, 10, 60, 80), type="l") ## truncated Normal distribution

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 = NULL,
 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 multi-state model, as returned by msm .

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, t must be specified.

covariates

The covariate values to estimate for. This can either be:

the string "mean", denoting the means of the covariates in the data (this is the default),

the number 0, indicating that all the covariates should be set to zero,

or a list of values, with optional names. For example

list (60, 1)

where the order of the list follows the order of the covariates originally given in the model formula, or a named list,

list (age = 60, sex = 1)

piecewise.times

Times at which piecewise-constant intensities change. See pmatrix.piecewise.msm for how to specify this. This is only required for time-inhomogeneous models specified using explicit time-dependent covariates, and should not be used for models specified using "pci".

piecewise.covariates

Covariates on which the piecewise-constant intensities depend. See pmatrix.piecewise.msm for how to specify this.

num.integ

Use numerical integration instead of analytic solution (see below).

discount

Discount rate in continuous time.

env

Supplied to totlos.msm . If TRUE, return the expected number of visits to each state. If FALSE, return the total length of stay in each state. envisits.msm simply calls totlos.msm with env=TRUE.

ci

If "normal", then calculate a confidence interval by simulating B random vectors from the asymptotic multivariate normal distribution implied by the maximum likelihood estimates (and covariance matrix) of the log transition intensities and covariate effects, then calculating the total length of stay for each replicate.

If "bootstrap" then calculate a confidence interval by non-parametric bootstrap refitting. This is 1-2 orders of magnitude slower than the "normal" method, but is expected to be more accurate. See boot.msm for more details of bootstrapping in msm.

If "none" (the default) then no confidence interval is calculated.

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 boot.msm for more details.

...

Further arguments to be passed to the integrate function to control the numerical integration.

transient.msm(x = NULL, qmatrix = NULL)
absorbing.msm(x = NULL, qmatrix = NULL)

x

A fitted multi-state model as returned by msm .

qmatrix

A transition intensity matrix. The diagonal is ignored and taken to be minus the sum of the rest of the row.

d2phase(x, l1, mu1, mu2, log = FALSE)
p2phase(q, l1, mu1, mu2, lower.tail = TRUE, log.p = FALSE)
q2phase(p, l1, mu1, mu2, lower.tail = TRUE, log.p = FALSE)
r2phase(n, l1, mu1, mu2)
h2phase(x, l1, mu1, mu2, log = FALSE)

x, q

vector of quantiles.

l1

Intensity for transition between phase 1 and phase 2.

mu1

Intensity for transition from phase 1 to exit.

mu2

Intensity for transition from phase 2 to exit.

log

logical; if TRUE, return log density or log hazard.

lower.tail

logical; if TRUE (default), probabilities are P[X <= x], otherwise, P[X > x].

log.p

logical; if TRUE, probabilities p are given as log(p).

p

vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

updatepars.msm(x, pars)

x

A fitted multi-state model object, as returned by msm .

pars

Vector of new parameters, in their untransformed real-line parameterisations, to substitute for the maximum likelihood estimates corresponding to those in the estimates component of the fitted model object (msm.object ). The order of the parameters is documented in msm , argument fixedpars.

viterbi.msm(x, normboot = FALSE, newdata = NULL)

x

A fitted hidden Markov multi-state model, or a model with censored state observations, as produced by msm

normboot

If TRUE, then before running the algorithm, the maximum likelihood estimates of the model parameters are replaced by an alternative set of parameters drawn randomly from the asymptotic multivariate normal distribution of the MLEs.

newdata

An optional data frame containing observations on which to construct the Viterbi path and forward-backward probabilities. It must be in the same format as the data frame used to fit x. If NULL, the data frame used to fit x is used.