Debian Codegraph @

man/mssample.Rd

raw
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}