% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mssample.R
\name{mssample}
\alias{mssample}
\title{Sample paths through a multi-state model}
\usage{
mssample(
  Haz,
  trans,
  history = list(state = 1, time = 0, tstate = NULL),
  beta.state = NULL,
  clock = c("forward", "reset"),
  output = c("state", "path", "data"),
  tvec,
  cens = NULL,
  M = 10,
  do.trace = NULL
)
}
\arguments{
\item{Haz}{Cumulative hazards to be sampled from. These should be given as a
data frame with columns \code{time}, \code{Haz}, \code{trans}, for instance
as the \code{Haz} list element given by \code{\link{msfit}}.}

\item{trans}{Transition matrix describing the multi-state model.  See
\code{trans} in \code{\link{msprep}} for more detailed information}

\item{history}{A list with elements \code{state}, specifying the starting
state(s), \code{time}, the starting time(s), and \code{tstate}, a numeric
vector of length the number of states, specifying at what times states have
been visited, if appropriate. The default of \code{tstate} is \code{NULL};
more information can be found under Details.

The elements \code{state} and \code{time} may either be scalars or vectors,
in which case different sampled paths may start from different states or at
different times. By default, all sampled paths start from state 1 at time 0.}

\item{beta.state}{A matrix of dimension (no states) x (no transitions)
specifying estimated effects of times at which earlier states were reached
on subsequent transitions. If these are not in the model, the value
\code{NULL} (default) suffices; more information can be found under Details}

\item{clock}{Character argument, either \code{"forward"} (default) or
\code{"reset"}, specifying whether the time-scale of the cumulative hazards
is in forward time (\code{"forward"}) or duration in the present state
(\code{"reset"})}

\item{output}{One of \code{"state"}, \code{"path"}, or \code{"data"},
specifying whether states, paths, or data should be output.}

\item{tvec}{A numeric vector of time points at which the states or paths
should be evaluated. Ignored if \code{output}=\code{"data"}}

\item{cens}{An independent censoring distribution, given as a data frame
with time and Haz}

\item{M}{The number of sampled trajectories through the multi-state model.
The default is 10, since the procedure can become quite time-consuming}

\item{do.trace}{An integer, specifying that the replication number should be
written to the console every \code{do.trace} replications. Default is
\code{NULL} in which case no output is written to the console during the
simulation}
}
\value{
M simulated paths through the multi-state model given by
\code{trans} and \code{Haz}. It is either a data frame with columns
\code{time}, \code{pstate1}, ..., \code{pstateS} for S states when
\code{output="state"}, or with columns \code{time}, \code{ppath1},...,
\code{ppathP} for the P paths specified in \code{\link{paths}}(trans) when
\code{output="path"}. When \code{output="data"}, the sampled paths are
stored in an \code{"msdata"} object, a data frame in long format such as
that obtained by \code{\link{msprep}}. This may be useful for
(semi-)parametric bootstrap procedures, in which case \code{cens} may be
used as censoring distribution (assumed to be independent of all transition
times and independent of any covariates).
}
\description{
Given cumulative transition hazards sample paths through the multi-state
model.
}
\details{
The procedure is described in detail in Fiocco, Putter & van Houwelingen
(2008). The argument \code{beta.state} and the element \code{tstate} from
the argument \code{history} are meant to incorporate situations where the
time at which some previous states were visited may affect future transition
rates. The relation between time of visit of state \code{s} and transition
\code{k} is assumed to be linear on the log-hazards; the corresponding
regression coefficient is to be supplied as the (s,k)-element of
\code{beta.state}, which is 0 if no such effect has been included in the
model. If no such effects are present, then \code{beta.state}=\code{NULL}
(default) suffices. In the \code{tstate} element of \code{history}, the
\code{s}-th element is the time at which state \code{s} was visited. This is
only relevant for states which have been visited prior to the beginning of
sampling, i.e. before the \code{time} element of \code{history}; the
elements of \code{tstate} are internally updated when in the sampling
process new states are visited (only if \code{beta.state} is not \code{NULL}
to avoid unnecessary computations).
}
\examples{

# transition matrix for illness-death model
tmat <- trans.illdeath()
# data in wide format, for transition 1 this is dataset E1 of
# Therneau & Grambsch (T&G)
tg <- data.frame(illt=c(1,1,6,6,8,9),ills=c(1,0,1,1,0,1),
        dt=c(5,1,9,7,8,12),ds=c(1,1,1,1,1,1),
        x1=c(1,1,1,0,0,0),x2=c(6:1))
# data in long format using msprep
tglong <- msprep(time=c(NA,"illt","dt"),status=c(NA,"ills","ds"),
        data=tg,keep=c("x1","x2"),trans=tmat)
# expanded covariates
tglong <- expand.covs(tglong,c("x1","x2"))
# Cox model with different covariate
cx <- coxph(Surv(Tstart,Tstop,status)~x1.1+x2.2+strata(trans),
        data=tglong,method="breslow")
# new data, to check whether results are the same for transition 1 as T&G
newdata <- data.frame(trans=1:3,x1.1=c(0,0,0),x2.2=c(0,1,0),strata=1:3)
fit <- msfit(cx,newdata,trans=tmat)
tv <- unique(fit$Haz$time)
# mssample
set.seed(1234)
mssample(Haz=fit$Haz,trans=tmat,tvec=tv,M=100)
set.seed(1234)
paths(tmat)
mssample(Haz=fit$Haz,trans=tmat,tvec=tv,M=100,output="path")
set.seed(1234)
mssample(Haz=fit$Haz,trans=tmat,tvec=tv,M=100,output="data",do.trace=25)

}
\references{
Fiocco M, Putter H, van Houwelingen HC (2008). Reduced-rank
proportional hazards regression and simulation-based prediction for
multi-state models. \emph{Statistics in Medicine} \bold{27}, 4340--4358.
}
\author{
Marta Fiocco, Hein Putter \email{H.Putter@lumc.nl}
}
\keyword{datagen}
