| 1 |
% Generated by roxygen2: do not edit by hand |
| 2 |
% Please edit documentation in R/mssample.R |
| 3 |
\name{mssample} |
| 4 |
\alias{mssample} |
| 5 |
\title{Sample paths through a multi-state model} |
| 6 |
\usage{ |
| 7 |
mssample( |
| 8 |
Haz, |
| 9 |
trans, |
| 10 |
history = list(state = 1, time = 0, tstate = NULL), |
| 11 |
beta.state = NULL, |
| 12 |
clock = c("forward", "reset"), |
| 13 |
output = c("state", "path", "data"), |
| 14 |
tvec, |
| 15 |
cens = NULL, |
| 16 |
M = 10, |
| 17 |
do.trace = NULL |
| 18 |
) |
| 19 |
} |
| 20 |
\arguments{ |
| 21 |
\item{Haz}{Cumulative hazards to be sampled from. These should be given as a |
| 22 |
data frame with columns \code{time}, \code{Haz}, \code{trans}, for instance |
| 23 |
as the \code{Haz} list element given by \code{\link{msfit}}.} |
| 24 |
|
| 25 |
\item{trans}{Transition matrix describing the multi-state model. See |
| 26 |
\code{trans} in \code{\link{msprep}} for more detailed information} |
| 27 |
|
| 28 |
\item{history}{A list with elements \code{state}, specifying the starting |
| 29 |
state(s), \code{time}, the starting time(s), and \code{tstate}, a numeric |
| 30 |
vector of length the number of states, specifying at what times states have |
| 31 |
been visited, if appropriate. The default of \code{tstate} is \code{NULL}; |
| 32 |
more information can be found under Details. |
| 33 |
|
| 34 |
The elements \code{state} and \code{time} may either be scalars or vectors, |
| 35 |
in which case different sampled paths may start from different states or at |
| 36 |
different times. By default, all sampled paths start from state 1 at time 0.} |
| 37 |
|
| 38 |
\item{beta.state}{A matrix of dimension (no states) x (no transitions) |
| 39 |
specifying estimated effects of times at which earlier states were reached |
| 40 |
on subsequent transitions. If these are not in the model, the value |
| 41 |
\code{NULL} (default) suffices; more information can be found under Details} |
| 42 |
|
| 43 |
\item{clock}{Character argument, either \code{"forward"} (default) or |
| 44 |
\code{"reset"}, specifying whether the time-scale of the cumulative hazards |
| 45 |
is in forward time (\code{"forward"}) or duration in the present state |
| 46 |
(\code{"reset"})} |
| 47 |
|
| 48 |
\item{output}{One of \code{"state"}, \code{"path"}, or \code{"data"}, |
| 49 |
specifying whether states, paths, or data should be output.} |
| 50 |
|
| 51 |
\item{tvec}{A numeric vector of time points at which the states or paths |
| 52 |
should be evaluated. Ignored if \code{output}=\code{"data"}} |
| 53 |
|
| 54 |
\item{cens}{An independent censoring distribution, given as a data frame |
| 55 |
with time and Haz} |
| 56 |
|
| 57 |
\item{M}{The number of sampled trajectories through the multi-state model. |
| 58 |
The default is 10, since the procedure can become quite time-consuming} |
| 59 |
|
| 60 |
\item{do.trace}{An integer, specifying that the replication number should be |
| 61 |
written to the console every \code{do.trace} replications. Default is |
| 62 |
\code{NULL} in which case no output is written to the console during the |
| 63 |
simulation} |
| 64 |
} |
| 65 |
\value{ |
| 66 |
M simulated paths through the multi-state model given by |
| 67 |
\code{trans} and \code{Haz}. It is either a data frame with columns |
| 68 |
\code{time}, \code{pstate1}, ..., \code{pstateS} for S states when |
| 69 |
\code{output="state"}, or with columns \code{time}, \code{ppath1},..., |
| 70 |
\code{ppathP} for the P paths specified in \code{\link{paths}}(trans) when |
| 71 |
\code{output="path"}. When \code{output="data"}, the sampled paths are |
| 72 |
stored in an \code{"msdata"} object, a data frame in long format such as |
| 73 |
that obtained by \code{\link{msprep}}. This may be useful for |
| 74 |
(semi-)parametric bootstrap procedures, in which case \code{cens} may be |
| 75 |
used as censoring distribution (assumed to be independent of all transition |
| 76 |
times and independent of any covariates). |
| 77 |
} |
| 78 |
\description{ |
| 79 |
Given cumulative transition hazards sample paths through the multi-state |
| 80 |
model. |
| 81 |
} |
| 82 |
\details{ |
| 83 |
The procedure is described in detail in Fiocco, Putter & van Houwelingen |
| 84 |
(2008). The argument \code{beta.state} and the element \code{tstate} from |
| 85 |
the argument \code{history} are meant to incorporate situations where the |
| 86 |
time at which some previous states were visited may affect future transition |
| 87 |
rates. The relation between time of visit of state \code{s} and transition |
| 88 |
\code{k} is assumed to be linear on the log-hazards; the corresponding |
| 89 |
regression coefficient is to be supplied as the (s,k)-element of |
| 90 |
\code{beta.state}, which is 0 if no such effect has been included in the |
| 91 |
model. If no such effects are present, then \code{beta.state}=\code{NULL} |
| 92 |
(default) suffices. In the \code{tstate} element of \code{history}, the |
| 93 |
\code{s}-th element is the time at which state \code{s} was visited. This is |
| 94 |
only relevant for states which have been visited prior to the beginning of |
| 95 |
sampling, i.e. before the \code{time} element of \code{history}; the |
| 96 |
elements of \code{tstate} are internally updated when in the sampling |
| 97 |
process new states are visited (only if \code{beta.state} is not \code{NULL} |
| 98 |
to avoid unnecessary computations). |
| 99 |
} |
| 100 |
\examples{ |
| 101 |
|
| 102 |
# transition matrix for illness-death model |
| 103 |
tmat <- trans.illdeath() |
| 104 |
# data in wide format, for transition 1 this is dataset E1 of |
| 105 |
# Therneau & Grambsch (T&G) |
| 106 |
tg <- data.frame(illt=c(1,1,6,6,8,9),ills=c(1,0,1,1,0,1), |
| 107 |
dt=c(5,1,9,7,8,12),ds=c(1,1,1,1,1,1), |
| 108 |
x1=c(1,1,1,0,0,0),x2=c(6:1)) |
| 109 |
# data in long format using msprep |
| 110 |
tglong <- msprep(time=c(NA,"illt","dt"),status=c(NA,"ills","ds"), |
| 111 |
data=tg,keep=c("x1","x2"),trans=tmat) |
| 112 |
# expanded covariates |
| 113 |
tglong <- expand.covs(tglong,c("x1","x2")) |
| 114 |
# Cox model with different covariate |
| 115 |
cx <- coxph(Surv(Tstart,Tstop,status)~x1.1+x2.2+strata(trans), |
| 116 |
data=tglong,method="breslow") |
| 117 |
# new data, to check whether results are the same for transition 1 as T&G |
| 118 |
newdata <- data.frame(trans=1:3,x1.1=c(0,0,0),x2.2=c(0,1,0),strata=1:3) |
| 119 |
fit <- msfit(cx,newdata,trans=tmat) |
| 120 |
tv <- unique(fit$Haz$time) |
| 121 |
# mssample |
| 122 |
set.seed(1234) |
| 123 |
mssample(Haz=fit$Haz,trans=tmat,tvec=tv,M=100) |
| 124 |
set.seed(1234) |
| 125 |
paths(tmat) |
| 126 |
mssample(Haz=fit$Haz,trans=tmat,tvec=tv,M=100,output="path") |
| 127 |
set.seed(1234) |
| 128 |
mssample(Haz=fit$Haz,trans=tmat,tvec=tv,M=100,output="data",do.trace=25) |
| 129 |
|
| 130 |
} |
| 131 |
\references{ |
| 132 |
Fiocco M, Putter H, van Houwelingen HC (2008). Reduced-rank |
| 133 |
proportional hazards regression and simulation-based prediction for |
| 134 |
multi-state models. \emph{Statistics in Medicine} \bold{27}, 4340--4358. |
| 135 |
} |
| 136 |
\author{ |
| 137 |
Marta Fiocco, Hein Putter \email{[email protected]} |
| 138 |
} |
| 139 |
\keyword{datagen} |