% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simul.R
\name{simmulti.msm}
\alias{simmulti.msm}
\title{Simulate multiple trajectories from a multi-state Markov model with
arbitrary observation times}
\usage{
simmulti.msm(
  data,
  qmatrix,
  covariates = NULL,
  death = FALSE,
  start,
  ematrix = NULL,
  misccovariates = NULL,
  hmodel = NULL,
  hcovariates = NULL,
  censor.states = NULL,
  drop.absorb = TRUE
)
}
\arguments{
\item{data}{A data frame with a mandatory column named \code{time},
representing observation times.  The optional column named \code{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 \code{cens}
indicates the times at which simulated states should be censored. If
\code{cens==0} then the state is not censored, and if \code{cens==k}, say,
then all simulated states at that time which are in the set
\code{censor.states} are replaced by \code{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.}

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

\code{rbind( c( 0, 0.1, 0.02 ), c( 0.1, 0, 0.01 ), c( 0, 0, 0 ) )}}

\item{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 \code{x} and \code{y} on each intensity,

\code{covariates=list(x = c(-0.3,-0.3,-0.3), y=c(0.1, 0.1, 0.1))}}

\item{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 \code{death = c(4, 5)} then
states 4 and 5 are assumed to be death states.

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

\item{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.}

\item{ematrix}{An optional misclassification matrix for generating observed
states conditionally on the simulated true states. As defined in
\code{\link{msm}}.}

\item{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 \code{covariates}.}

\item{hmodel}{An optional hidden Markov model for generating observed
outcomes conditionally on the simulated true states. As defined in
\code{\link{msm}}.  Multivariate outcomes (\code{hmmMV}) are not supported.}

\item{hcovariates}{List of the same length as \code{hmodel}, defining any
covariates governing the hidden Markov outcome models.  Unlike in the
\code{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,

\code{ hcovariates = list (c(acute=-8, age=0), c(acute=-8), NULL) }}

\item{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).}

\item{drop.absorb}{Drop repeated observations in the absorbing state,
retaining only one.}
}
\value{
A data frame with columns, \item{subject}{Subject identification
indicators} \item{time}{Observation times} \item{state}{Simulated (true)
state at the corresponding time} \item{obs}{Observed outcome at the
corresponding time, if \code{ematrix} or \code{hmodel} was supplied}
\item{keep}{Row numbers of the original data.  Useful when
\code{drop.absorb=TRUE}, to show which rows were not dropped} plus any
supplied covariates.
}
\description{
Simulate a number of individual realisations from a continuous-time Markov
process. Observations of the process are made at specified arbitrary times
for each individual, giving panel-observed data.
}
\details{
\code{\link{sim.msm}} is called repeatedly to produce a simulated trajectory
for each individual. The state at each specified observation time is then
taken to produce a new column \code{state}.  The effect of time-dependent
covariates on the transition intensity matrix for an individual is
determined by assuming that the covariate is a step function which remains
constant in between the individual's observation times.  If the subject
enters an absorbing state, then only the first observation in that state is
kept in the data frame. Rows corresponding to future observations are
deleted.  The entry times into states given in \code{death} are assumed to
be known exactly.
}
\examples{

### 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)

}
\seealso{
\code{\link{sim.msm}}
}
\author{
C. H. Jackson \email{chris.jackson@mrc-bsu.cam.ac.uk}
}
\keyword{datagen}
