Package 'msmbayes'

Canonical parameters, supplied in the order:

• sojourn rate in phase 1

• additive increments in sojourn rates for each successive phase

• probabilities (not rates) of absorption from each phase, for phase 1 up to the second last.

or a list with three components, one vector for each of these three parameter types.

"vector" or "list".

List with two components for progression and absorption rates, in increasing order of phase, or a vector with these concatenated.

Object returned by msmbayes.

Object returned by msmbayes.

"posterior" to return rvar objects containing posterior samples.

"mode" to return the output evaluated at the posterior mode of the basic parameters (only applicable if model was fitted with posterior mode optimisation).

Object returned by msmbayes.

Object returned by msmbayes.

Object returned by msmbayes.

Further arguments passed to both qdf, hr, loghr and edf.

Object returned by msmbayes.

Data frame with covariate values to predict for

(logical) Keep the integer column covid identifying unique covariate combinations.

Object returned by msmbayes.

Object returned by msmbayes.

Data frame with covariate values to predict for

If states="obs" (or "observed") then this describes mean sojourn times in the observable states. For phase-type models this is not generally equal to the sum of the phase-specific mean sojourn times, because an individual may transition out of the state before progressing to the next phase.

If states="phase" (or "true", or "latent") then for phase-type models, this describes mean sojourn times in the latent state space.

(logical) Keep the integer column covid identifying unique covariate combinations.

Data frame giving the observed data.

Character string naming the observed state variable in the data. This variable must either be an integer in 1,2,...,K, where K is the number of states, or a factor with these integers as level labels. If omitted, this is assumed to be "state".

Character string naming the observation time variable in the data. If omitted, this is assumed to be "time".

Character string naming the individual ID variable in the data. If omitted, this is assumed to be "subject".

Matrix indicating the transition structure. A zero entry indicates that instantaneous transitions from (row) to (column) are disallowed. An entry of 1 (or any other positive value) indicates that the instantaneous transition is allowed. The diagonal of Q is ignored.

There is no need to "guess" initial values and put them here, as is sometimes done in msm. Initial values for fitting are determined by Stan from the prior distributions, and the specific values supplied for positive entries of Q are disregarded.

Specification of covariates on transition intensities. This should be a list of formulae, or a single formula.

If a list is supplied, each formula should have a left-hand side that looks like Q(r,s), and a right hand side defining the regression model for the log of the transition intensity from state $r$ to state $s$.

For example,

covariates = list(Q(1,2) ~ age + sex, Q(2,1) ~ age)

specifies that the log of the 1-2 transition intensity is an additive linear function of age and sex, and the log 2-1 transition intensity is a linear function of age. You do not have to list all of the intensities here if some of them are not influenced by covariates.

If a single formula is supplied, this is assumed to apply to all intensities. If doing this, then take care with potential lack of identifiability of effects from sparse data.

In models with phase-type approximated states (specified with pastates), covariates are modelled through an accelerated failure time model. The effect is a multiplier on the scale parameter of the sojourn distribution. The covariate then has an identical multiplicative effect on all rates of transition between phases for a given state. The left hand side of the formula should contain scale instad of Q. For example, if state 1 has a phase type approximation, but state 2 is Markov, then we might supply covariates as:

covariates = list(scale(1) ~ age + sex, Q(2,1) ~ age)

In models with phase-type approximations and competing exit states, covariates on the relative risk of different exit states are specified with a formula with rrnext on the left hand side. For example in a model where state 1 has a phase-type approximation, and the next state could be either 2 or 3, a linear model on the log relative risk of transition to 3 (relative to the baseline 2) might be specified as:

covariates = list(scale(1) ~ age + sex, rrnext(1,3) ~ x + time)

In phase-type models specified with nphase, or misclassification models (specified with E), covariates on transition intensities are specified with Q(), where the numbers inside Q() refer to the latent state space.

This indicates which states (if any) are given a Weibull or Gamma sojourn distribution approximated by a phase-type model. Ignored if nphase is supplied.

"weibull" or "gamma", indicating the approximated sojourn distribution in the phased state. Either a vector of the same length as pastates, or just one to apply to all states.

Number of phases to use for each state given a phase-type Gamma or Weibull approximation. Vector of same length as pastates. Using more phases allows a wider range of shape parameters, (see Figure 2 of the msmbayes paper) but does not create extra parameters. Defaults to 3.

By default, msmbayes fits a (non-hidden) Markov model. If E is supplied, then a Markov model with misclassification is fitted, a type of hidden Markov model. E should then be a matrix indicating the structure of allowed misclassifications, where rows are the true states, and columns are the observed states. A zero entry in row $r$ and column $s$ indicates that true state $r$ cannot be observed as state $s$. A non-zero $(r,s)$ entry indicates that true state $r$ may be misclassified as $s$. The diagonal of E is ignored.

Misclassfication probabilities in Markov models are commonly not identifiable from data, particulary if the data are intermittently observed. Instead of estimating them, a Markov model with misclassification can be specified by supplying assumed misclassification probabilities in the Efix argument. This is a matrix with same dimensions as E. Any non-zero entries of Efix indicate the fixed known value for the corresponding misclassification probability. The $(r,s)$ entry of Efix is 0 for any error probabilities that are estimated from the data or not permitted.

Character string, giving a variable in the data which defines what a "row of the data" means. The variable must contain only the following values, which may be different in different rows:

1: Intermittent observation. The state is unknown between the previous observation and the current observation (other than any knowledge implied by the structure Q of permitted transitions).

2: Exact transition times. The state is constant at the previous observed value between the previous and current times in the data, and the transition to the current state is made exactly at the current time.

3: "Exact death times". A transition to the current state is made exactly at the current time, but the state in the period between the previous observation and this transition is unknown. Typical (but not necessary) for observations of death in epidemiological/clinical studies.

This is the same feature as in the msm package. If omitted, then all observations are assumed to be intermittent, with obstype 1.

Set to TRUE if death times are observed with the ⁠obstype 3⁠ scheme. This is a shortcut for including an obstype variable with 3 in the positions with the absorbing state, and 1 elsewhere. If there are multiple absorbing states, then this is taken to only apply to the last of them in the state space - use an obstype variable if you want it to apply to all absorbing states.

Only applicable to models with misclassification. A character string indicating a variable in the data whose value is 1 if the true state is known to equal the value in "state", and 0 otherwise.

A named list indicating the codes used for "censored" states. This is used when there are observations that are known to be one of a subset of states, but it is not known which. The names of the list indicate codes that may appear in the "state" variable. The values of the corresponding component indicate the subset which is represented by the code. For example

censor_states = list("99" = c(2,3), "999" = c(3,4))

means that a code of 99 in the "state" variable indicates "state is either 2 or 3 at this time", and a code of 999 indicates "state is either 3 or 4".

Note the names of the list must be quoted strings that are interpretable as integers, since the "state" variable must be an integer.

In misclassification models, the subset refers to values of the true state if obstrue is 1, or the observed state if obstrue is 0.

Unlike in msm, there is no censor argument, and a censor_states must be supplied if there are censored states.

Constraints that a covariate has an equal effect on a particular set of transition intensities. A list with one component for each covariate that has constraints. Each component is a list of sets (or a single set) of intensities where the effect of that covariate is equal. For example, to constrain the effect of age to be equal for transitions 1-2 and 2-3, and also equal for transitions 1-4 and 2-4, and the effect of sexMALE to be equal for transitions 1-2 and 2-3, specify

constraint = list(age = list(c("1-2","2-3"), c("1-4","2-4")), sex = list(c("1-2","2-3")))

This is the same feature as in msm, but with an easier interface. In msmbayes it is only supported for standard Markov models, not semi-Markov, phase-type or misclassification models.

Only required for models with phase-type sojourn distributions specified directly (not through pastates). nphase is a vector with one element per state, giving the number of phases per state. This element is 1 for states that do not have phase-type sojourn distributions.

A list specifying priors. Each component should be the result of a call to msmprior. Any parameters with priors not specified here are given default priors: normal with mean -2 and SD 2 for log intensities, normal with mean 0 and SD 10 for log hazard ratios, normal(0,1) for log odds parameters in misclassification models.

In phase-type approximation models, the default priors are normal with mean 2, SD 2 for scale parameters (i.e. the log inverse of the default prior for the rate), normal(0, SD=0.5) truncated on the supported region for log shape parameters, and normal(0,1) for log odds of transition (relative to first exit state) in structures with competing exit states.

See msmprior for more details.

If only one parameter is given a non-default prior, a single msmprior call can be supplied here instead of a list.

Maximum likelihood estimation can be performed by setting priors="mle", and using fit_method="optimize". This is equivalent to estimating the posterior mode with improper uniform priors on the unconstrained parameter space (i.e. positive parameters on the log scale). Uncertainty is then quantified by sampling from the multivariate normal defined by the Hessian at the mode . The sample can be summarised to produce confidence intervals, as in the ci="normal" method in the msm package. These are equivalent to credible intervals from a Laplace approximation to the posterior.

Probabilities of true states at a person's first observation time in a misclassification or model. If supplied, this should be a matrix with a row for each individual subject, and a column for each true state, or a vector with one element for each state that is assumed to apply to all individuals.

If not supplied, every person is assumed to be in state 1 with probability 1 in misclassification models, or phase 1 of the observed state with probability 1 in phase-type models. Note no warning is currently given if the first observed state would be impossible if the person was really in state 1.

This applies to both misclassification models, and phase-type models where a person's first observed state is phased. If the first observed state is not phased or misclassified, then this is ignored.

Synthetic data that represents prior information about the mean sojourn times. Experimental, undocumented feature.

Quoted string specifying the algorithm to fit the model. "sample" uses NUTS/HMC MCMC, via rstan::sampling(). This is the default unless priors="mle". Alternatives are

"optimize" to use posterior mode optimization (with respect to parameters on the log scale) followed by Laplace approximation around the mode (via rstan::optimizing()). This is the default if priors="mle".

"variational" to use variational Bayes (via rstan::vb()).

"pathfinder", to use the Pathfinder variational algorithm via cmdstanr. This requires cmdstan and cmdstanr to be installed. The first time this is run for a particular msmbayes model class, the Stan program for that class is compiled, which will take a extra minute or two. The next time, it will not need to be recompiled. This also assumes you have write permission to the place where msmbayes is installed.

Store a copy of the cleaned data in the returned object. FALSE by default.

Other arguments to be passed to the function from rstan or cmdstanr that fits the model. Note that initial values are determined by sampling from the prior (after dividing the prior SD 5), not using Stan's default, but this can be overridden here (currently not documented - this needs knowledge of the Stan variable names and formats)

Data frame giving the observed data.

Character string naming the observed state variable in the data. This variable must either be an integer in 1,2,...,K, where K is the number of states, or a factor with these integers as level labels. If omitted, this is assumed to be "state".

Character string naming the observation time variable in the data. If omitted, this is assumed to be "time".

Character string naming the individual ID variable in the data. If omitted, this is assumed to be "subject".

Matrix indicating the transition structure. A zero entry indicates that instantaneous transitions from (row) to (column) are disallowed. An entry of 1 (or any other positive value) indicates that the instantaneous transition is allowed. The diagonal of Q is ignored.

There is no need to "guess" initial values and put them here, as is sometimes done in msm. Initial values for fitting are determined by Stan from the prior distributions, and the specific values supplied for positive entries of Q are disregarded.

Specification of covariates on transition intensities. This should be a list of formulae, or a single formula.

If a list is supplied, each formula should have a left-hand side that looks like Q(r,s), and a right hand side defining the regression model for the log of the transition intensity from state $r$ to state $s$.

For example,

covariates = list(Q(1,2) ~ age + sex, Q(2,1) ~ age)

specifies that the log of the 1-2 transition intensity is an additive linear function of age and sex, and the log 2-1 transition intensity is a linear function of age. You do not have to list all of the intensities here if some of them are not influenced by covariates.

If a single formula is supplied, this is assumed to apply to all intensities. If doing this, then take care with potential lack of identifiability of effects from sparse data.

In models with phase-type approximated states (specified with pastates), covariates are modelled through an accelerated failure time model. The effect is a multiplier on the scale parameter of the sojourn distribution. The covariate then has an identical multiplicative effect on all rates of transition between phases for a given state. The left hand side of the formula should contain scale instad of Q. For example, if state 1 has a phase type approximation, but state 2 is Markov, then we might supply covariates as:

covariates = list(scale(1) ~ age + sex, Q(2,1) ~ age)

In models with phase-type approximations and competing exit states, covariates on the relative risk of different exit states are specified with a formula with rrnext on the left hand side. For example in a model where state 1 has a phase-type approximation, and the next state could be either 2 or 3, a linear model on the log relative risk of transition to 3 (relative to the baseline 2) might be specified as:

covariates = list(scale(1) ~ age + sex, rrnext(1,3) ~ x + time)

In phase-type models specified with nphase, or misclassification models (specified with E), covariates on transition intensities are specified with Q(), where the numbers inside Q() refer to the latent state space.

This indicates which states (if any) are given a Weibull or Gamma sojourn distribution approximated by a phase-type model. Ignored if nphase is supplied.

"weibull" or "gamma", indicating the approximated sojourn distribution in the phased state. Either a vector of the same length as pastates, or just one to apply to all states.

Number of phases to use for each state given a phase-type Gamma or Weibull approximation. Vector of same length as pastates. Using more phases allows a wider range of shape parameters, (see Figure 2 of the msmbayes paper) but does not create extra parameters. Defaults to 3.

Only required for models with phase-type sojourn distributions specified directly (not through pastates). nphase is a vector with one element per state, giving the number of phases per state. This element is 1 for states that do not have phase-type sojourn distributions.

By default, msmbayes fits a (non-hidden) Markov model. If E is supplied, then a Markov model with misclassification is fitted, a type of hidden Markov model. E should then be a matrix indicating the structure of allowed misclassifications, where rows are the true states, and columns are the observed states. A zero entry in row $r$ and column $s$ indicates that true state $r$ cannot be observed as state $s$. A non-zero $(r,s)$ entry indicates that true state $r$ may be misclassified as $s$. The diagonal of E is ignored.

A list specifying priors. Each component should be the result of a call to msmprior. Any parameters with priors not specified here are given default priors: normal with mean -2 and SD 2 for log intensities, normal with mean 0 and SD 10 for log hazard ratios, normal(0,1) for log odds parameters in misclassification models.

In phase-type approximation models, the default priors are normal with mean 2, SD 2 for scale parameters (i.e. the log inverse of the default prior for the rate), normal(0, SD=0.5) truncated on the supported region for log shape parameters, and normal(0,1) for log odds of transition (relative to first exit state) in structures with competing exit states.

See msmprior for more details.

If only one parameter is given a non-default prior, a single msmprior call can be supplied here instead of a list.

Maximum likelihood estimation can be performed by setting priors="mle", and using fit_method="optimize". This is equivalent to estimating the posterior mode with improper uniform priors on the unconstrained parameter space (i.e. positive parameters on the log scale). Uncertainty is then quantified by sampling from the multivariate normal defined by the Hessian at the mode . The sample can be summarised to produce confidence intervals, as in the ci="normal" method in the msm package. These are equivalent to credible intervals from a Laplace approximation to the posterior.

Number of samples to generate

Data frame giving the observed data.

Character string naming the observed state variable in the data. This variable must either be an integer in 1,2,...,K, where K is the number of states, or a factor with these integers as level labels. If omitted, this is assumed to be "state".

Character string naming the observation time variable in the data. If omitted, this is assumed to be "time".

Character string naming the individual ID variable in the data. If omitted, this is assumed to be "subject".

Matrix indicating the transition structure. A zero entry indicates that instantaneous transitions from (row) to (column) are disallowed. An entry of 1 (or any other positive value) indicates that the instantaneous transition is allowed. The diagonal of Q is ignored.

There is no need to "guess" initial values and put them here, as is sometimes done in msm. Initial values for fitting are determined by Stan from the prior distributions, and the specific values supplied for positive entries of Q are disregarded.

Specification of covariates on transition intensities. This should be a list of formulae, or a single formula.

If a list is supplied, each formula should have a left-hand side that looks like Q(r,s), and a right hand side defining the regression model for the log of the transition intensity from state $r$ to state $s$.

For example,

covariates = list(Q(1,2) ~ age + sex, Q(2,1) ~ age)

specifies that the log of the 1-2 transition intensity is an additive linear function of age and sex, and the log 2-1 transition intensity is a linear function of age. You do not have to list all of the intensities here if some of them are not influenced by covariates.

If a single formula is supplied, this is assumed to apply to all intensities. If doing this, then take care with potential lack of identifiability of effects from sparse data.

In models with phase-type approximated states (specified with pastates), covariates are modelled through an accelerated failure time model. The effect is a multiplier on the scale parameter of the sojourn distribution. The covariate then has an identical multiplicative effect on all rates of transition between phases for a given state. The left hand side of the formula should contain scale instad of Q. For example, if state 1 has a phase type approximation, but state 2 is Markov, then we might supply covariates as:

covariates = list(scale(1) ~ age + sex, Q(2,1) ~ age)

In models with phase-type approximations and competing exit states, covariates on the relative risk of different exit states are specified with a formula with rrnext on the left hand side. For example in a model where state 1 has a phase-type approximation, and the next state could be either 2 or 3, a linear model on the log relative risk of transition to 3 (relative to the baseline 2) might be specified as:

covariates = list(scale(1) ~ age + sex, rrnext(1,3) ~ x + time)

In phase-type models specified with nphase, or misclassification models (specified with E), covariates on transition intensities are specified with Q(), where the numbers inside Q() refer to the latent state space.

This indicates which states (if any) are given a Weibull or Gamma sojourn distribution approximated by a phase-type model. Ignored if nphase is supplied.

"weibull" or "gamma", indicating the approximated sojourn distribution in the phased state. Either a vector of the same length as pastates, or just one to apply to all states.

Number of phases to use for each state given a phase-type Gamma or Weibull approximation. Vector of same length as pastates. Using more phases allows a wider range of shape parameters, (see Figure 2 of the msmbayes paper) but does not create extra parameters. Defaults to 3.

Only required for models with phase-type sojourn distributions specified directly (not through pastates). nphase is a vector with one element per state, giving the number of phases per state. This element is 1 for states that do not have phase-type sojourn distributions.

By default, msmbayes fits a (non-hidden) Markov model. If E is supplied, then a Markov model with misclassification is fitted, a type of hidden Markov model. E should then be a matrix indicating the structure of allowed misclassifications, where rows are the true states, and columns are the observed states. A zero entry in row $r$ and column $s$ indicates that true state $r$ cannot be observed as state $s$. A non-zero $(r,s)$ entry indicates that true state $r$ may be misclassified as $s$. The diagonal of E is ignored.

A list specifying priors. Each component should be the result of a call to msmprior. Any parameters with priors not specified here are given default priors: normal with mean -2 and SD 2 for log intensities, normal with mean 0 and SD 10 for log hazard ratios, normal(0,1) for log odds parameters in misclassification models.

In phase-type approximation models, the default priors are normal with mean 2, SD 2 for scale parameters (i.e. the log inverse of the default prior for the rate), normal(0, SD=0.5) truncated on the supported region for log shape parameters, and normal(0,1) for log odds of transition (relative to first exit state) in structures with competing exit states.

See msmprior for more details.

If only one parameter is given a non-default prior, a single msmprior call can be supplied here instead of a list.

Maximum likelihood estimation can be performed by setting priors="mle", and using fit_method="optimize". This is equivalent to estimating the posterior mode with improper uniform priors on the unconstrained parameter space (i.e. positive parameters on the log scale). Uncertainty is then quantified by sampling from the multivariate normal defined by the Hessian at the mode . The sample can be summarised to produce confidence intervals, as in the ci="normal" method in the msm package. These are equivalent to credible intervals from a Laplace approximation to the posterior.

If complete_obs=FALSE (the default) intermittently-observed states are generated for the subjects and times supplied in the data argument, using msm::simmulti.msm. The returned object is a data frame made by appending these states to data.

If complete_obs=TRUE, one complete state transition history is generated using msm::sim.msm. The data argument should then consist of one row, with time giving the maximum observation time, and any covariates supplied, assumed to be time-constant. The returned object is a list.

If "orig" the covariates are in their original form that they were supplied as. If "design" (or any other value) the covariates are returned as a design matrix, i.e. with factors converted to numeric contrasts.

Data frame giving the observed data.

Character string naming the observed state variable in the data. This variable must either be an integer in 1,2,...,K, where K is the number of states, or a factor with these integers as level labels. If omitted, this is assumed to be "state".

Character string naming the observation time variable in the data. If omitted, this is assumed to be "time".

Character string naming the individual ID variable in the data. If omitted, this is assumed to be "subject".

Number of time intervals to bin the state observations into. The underlying distribution of states illustrated by the plot will be assumed constant within each interval.

Indices of any absorbing states. Individuals are assumed to stay in their absorbing state, and contribute one observation to each bin after their absorption time. By default, no states are assumed to be absorbing.

Vector of maximum intended follow-up times for the people in the data who entered absorbing states. This supposes that had the person not entered the absorbing state, they would not have been observed after this time.

If TRUE do a bar chart with the probabilities for different states stacked on top of each other, so the y-axis spans 0 to 1 exactly. This is more compact.

If FALSE, plot one panel per state, as is done in prevalence.msm. This is more convenient for constructing a check of the model fit.

Data frame giving the observed data.

Character string naming the observed state variable in the data. This variable must either be an integer in 1,2,...,K, where K is the number of states, or a factor with these integers as level labels. If omitted, this is assumed to be "state".

Character string naming the observation time variable in the data. If omitted, this is assumed to be "time".

Character string naming the individual ID variable in the data. If omitted, this is assumed to be "subject".

Number of time intervals to bin the state observations into. The underlying distribution of states illustrated by the plot will be assumed constant within each interval.

Indices of any absorbing states. Individuals are assumed to stay in their absorbing state, and contribute one observation to each bin after their absorption time. By default, no states are assumed to be absorbing.

Vector of maximum intended follow-up times for the people in the data who entered absorbing states. This supposes that had the person not entered the absorbing state, they would not have been observed after this time.

Character string indicating the model parameter to place the prior on. This should start with one of the following:

"logq". Log transition intensity. It should then two include indices indicating the transition, e.g. "logq(2,3)" for the log transition intensity from state 2 to state 3.

"q", Transition intensity (in the same format)

"time". Defined as 1/q. This can be interpreted as the mean time to the next transition to state $s$ for people in state $r$ (from the point of view of someone observing one person at a time, and switching to observing a different person if a competing transition happens). The same format as logq and q with two indices.

"loghr". Covariate effect on intensities of transition from states given a Markov model. The covariate name is supplied alongside the transition indices, e.g. "loghr(age,2,3)" for the effect of age on the log hazard ratio of transitioning from state 2 to state 3. For factor covariates, this should include the level, e.g. "loghr(sexMALE,2,3)" for level "MALE" of factor "sex".

"logtaf". Covariate effect on the sojourn time in states given a semi-Markov model with a phase-type approximation. This is specified with only one index, indicating the state, e.g. "loghr(age,2)". Note this is interpreted as a log hazard ratio for times to transitions on the latent space, but for the sojourn time on the observable space, this is a "time acceleration factor", such that an coefficent of log(2) increases the risk of the next transition through halving the expected sojourn time.

"hr". Hazard ratio.

"loe" Log odds of error (relative to no misclassification). "loe(1,2)" indicates the log odds of misclassification in state 2 for true state 1, relative to no misclassifiation.

"logshape" "logscale" Log shape or scale parameter for the sojourn distribution in a phase-type approximation model. The index indicates the state, e.g. logshape(2) and logscale(2) indicate the log shape and scale parameter for the sojourn distribution in state 2.

"logoddsnext". Log odds of transition to a destination state in a phase-type approximation model with competing destination states. These parameters are only used in phase-type approximation models where there are multiple potential states that an individual could transition to immediately on leaving the state that has a phase-type approximation sojourn distribution. These parameters are defined with two indices. For example, logoddsnext(1,2) is the log odds of transition to state 2 on leaving state 1. The odds is the probability of transition to state 2 divided by the probability of transition to the first out of the set of potential destination states.

Covariate effects on competing transitions out of semi-Markov states are specified with logrrnext. For example, "logrrnext(age,2,3)" for the effect of age on the relative rate of transition from state 2 to state 3, relative to the rate of transition from state 2 to the first competing destination state. These parameters are not applicable to semi-Markov states with only one potential next destination state.

In general, the indices or the covariate name can be omitted to indicate that the same prior will used for all transitions, or/and all covariates. This can be done with or without the brackets, e.g. "logq()" or "logq" are both understood.

Prior mean. This is only used for the parameters that have direct normal priors, that is logq, loghr, logtaf, logshape, logscale, loe, logoddsnext. That is, excluding time, q and hr, whose priors are defined by transformations of a normal distribution.

Prior standard deviation (only for parameters with direct normal priors)

Prior median

Prior lower 95% quantile

Prior upper 95% quantile

Second normalised moment

Number of phases

Value at which to evaluate the PDF, CDF, or hazard.

Progression rates. Either a vector of length nphase-1, or a matrix with npar rows and nphase-1 columns.

Absorption rates. Either a vector of length nphase, or a matrix with npar rows and nphase columns.

Vector of probabilities of occupying each phase at the start of the sojourn. By default, the first phase has probability 1.

If "analytic" then for nphase 5 or less, an analytic solution to the matrix exponential is employed in the calculation. For nphase 6 or more, or if method="mexp" the matrix exponential is determined using numerical methods, via expm::expm().

Value at which to evaluate the CDF.

If TRUE return P(X<x), else P(X>=x).

which moment to return from ncmoment_nphase

Number of random samples to generate.

Probability at which to evaluate the quantile

return log probability

Progression rates. Either a vector of length nphase-1, or a matrix with npar rows and nphase-1 columns.

Absorption rates. Either a vector of length nphase, or a matrix with npar rows and nphase columns.

Object returned by msmbayes.

Return parameters on log scale

Object returned by msmbayes.

prediction time or vector of prediction times

Data frame with covariate values to predict for

If states="obs" (or "observed") then this describes mean sojourn times in the observable states. For phase-type models this is not generally equal to the sum of the phase-specific mean sojourn times, because an individual may transition out of the state before progressing to the next phase.

If states="phase" (or "true", or "latent") then for phase-type models, this describes mean sojourn times in the latent state space.

Only used if there are no covariates supplied in new_data. Then if drop=TRUE this returns a nstates x nstates matrix, or if drop=FALSE this returns a 3D array with first dimension ncovs=1.

"posterior" to return rvar objects containing posterior samples.

"mode" to return the output evaluated at the posterior mode of the basic parameters (only applicable if model was fitted with posterior mode optimisation).

Object returned by msmbayes.

prediction time or vector of prediction times

Data frame with covariate values to predict for

If states="obs" (or "observed") then this describes mean sojourn times in the observable states. For phase-type models this is not generally equal to the sum of the phase-specific mean sojourn times, because an individual may transition out of the state before progressing to the next phase.

If states="phase" (or "true", or "latent") then for phase-type models, this describes mean sojourn times in the latent state space.

Object returned by msmbayes.

Data frame with covariate values to predict for

Object returned by msmbayes.

Data frame with covariate values to predict for

(logical) Keep the integer column covid identifying unique covariate combinations.

Object returned by msmbayes.

Data frame with covariate values to predict for

Lower-level alternative to specifying new_data, for developer use only. X is a numeric matrix formed from column-binding the covariate design matrices for each transition in turn.

Only used if there are no covariates supplied in new_data. Then if drop=TRUE this returns a nstates x nstates matrix, or if drop=FALSE this returns a 3D array with first dimension ncovs=1.

"posterior" to return rvar objects containing posterior samples.

"mode" to return the output evaluated at the posterior mode of the basic parameters (only applicable if model was fitted with posterior mode optimisation).

Intensity matrix on the observable state space. Only the rates for transitions out of Markov states are used, and values of rates for transitions out of the non-Markov state are ignored, unless there are competing next states. In that case the relative value of the intensities are interpreted as the transition probability to each next state. These transition probabilities are multiplied by the phase transition rates of the sojourn distribution in the non-Markov state to get the transition rates from the phases to the destination state.

This indicates which states (if any) are given a Weibull or Gamma sojourn distribution approximated by a phase-type model. Ignored if nphase is supplied.

shape parameter. This can be vectorised.

scale parameter. This can be vectorised.

parametric family approximated by the phase-type distribution: "weibull" or "gamma"

Only required for models with phase-type sojourn distributions specified directly (not through pastates). nphase is a vector with one element per state, giving the number of phases per state. This element is 1 for states that do not have phase-type sojourn distributions.

keep attributes indicating progression and absorption states

Object returned by msmbayes.

Shape parameter or vector)

Number of phases

Number of approximating phases

"weibull" or "gamma"

shape parameter. This can be vectorised.

scale parameter. This can be vectorised.

parametric family approximated by the phase-type distribution: "weibull" or "gamma"

Return the phase-type parameters in canonical form (phase 1 sojourn rate, sojourn rate increments in subsequent states, absorption probabilities). If FALSE then phase transition rates are returned.

Number of phases.

If TRUE then separate components are returned for progression and absorption rates. Otherwise, and by default, a vector (or matrix) is returned combining all rates. If a vector is supplied for shape or scale, the returned object (or the list components) is a matrix.

If shape or scale have both have one element, and drop=FALSE, a matrix with one row is returned.

Number of individuals.

Observation times, common between individuals.

Function to simulate from the sojourn distribution in state 2. By default this is the exponential.

Named list of arguments and their values to be passed to rfn1, specifying parameter values for the sojourn distribution.

Function to simulate from the sojourn distribution in state 2.

Named list of arguments and their values to be passed to rfn2, specifying parameter values for the sojourn distribution.

Object returned by msmbayes.

Time since state entry. A single time or a vector can be supplied.

State of interest (A single integer)

Data frame with covariate values to predict for

Only applicable to phase-type models. Method for computing the matrix exponential involved in the phase-type sojourn distribution. See pnphase.

Object returned by msmbayes.

Vector of probabilities at which to evaluate quantiles of the sojourn distribution

State of interest (A single integer)

Data frame with covariate values to predict for

Only applicable to phase-type models. Method for computing the matrix exponential involved in the phase-type sojourn distribution. See pnphase.

Data frame with covariate values to predict for

Data frame giving the observed data.

Character string naming the observed state variable in the data. This variable must either be an integer in 1,2,...,K, where K is the number of states, or a factor with these integers as level labels. If omitted, this is assumed to be "state".

Character string naming the individual ID variable in the data. If omitted, this is assumed to be "subject".

Character string naming the observation time variable in the data. If omitted, this is assumed to be "time".

Vector of names of covariates to summarise counts by.

Number of groups to summarise the time intervals by. The transitions are categorised into groups according to equally-spaced quantiles of the time interval length.

"long" to return one row per tostate (a pure "tidy data" format) or "wide" to return one column per tostate (like statetable.msm in msm).

Object returned by msmbayes.

Character string indicating the parameters to include in the summary. This can include:

q: transition intensities. In semi-Markov models specified with pastates these refer to the intensities of transition between the latent phases.

logq: log transition intensities

time: inverse transition intensities (mean time to event without competing risks)

mst: mean sojourn times

shape, scale: shape and/or scale for Weibull/Gamma phase-type approximations

logshape,logscale corresponding log shape or scale

pnext, logoddsnext next-state probabilites (or log odds) in phase-type approximation models

hr: hazard ratios on transition intensities, including effects on scale parameters in phase-type approximation models.

loghr: log hazard ratios

taf,logtaf: effects on scale parameters in semi-Markov phase-type approximations.

rrnext,logrrnext: effects on competing risk transition probabilities in semi-Markov phase-type approximations.

e: misclassification probabilities

This defaults to whichever of c("q","mst","hr","shape","scale","e") are included in the model.

Further arguments passed to both qdf, hr, loghr and edf.

Object returned by msmbayes.

End point of the time interval over which to measure length of stay in each state

Data frame with covariate values to predict for

Starting point of the time interval, by default 0

Vector giving distribution of states at time 0

Discount rate in continuous time

If states="obs" (or "observed") then this describes mean sojourn times in the observable states. For phase-type models this is not generally equal to the sum of the phase-specific mean sojourn times, because an individual may transition out of the state before progressing to the next phase.

If states="phase" (or "true", or "latent") then for phase-type models, this describes mean sojourn times in the latent state space.