Debian Codegraph @

man/msprep.Rd

raw
1 % Generated by roxygen2: do not edit by hand
2 % Please edit documentation in R/msprep.R
3 \name{msprep}
4 \alias{msprep}
5 \title{Function to prepare dataset for multi-state modeling in long format from
6 dataset in wide format}
7 \usage{
8 msprep(time, status, data, trans, start, id, keep)
9 }
10 \arguments{
11 \item{time}{Either 1) a matrix or data frame of dimension n x S (n being the
12 number of individuals and S the number of states in the multi-state model),
13 containing the times at which the states are visited or last follow-up time,
14 or 2) a character vector of length S containing the column names indicating
15 these times. In the latter cases, some elements of \code{time} may be NA,
16 see Details}
17
18 \item{status}{Either 1) a matrix or data frame of dimension n x S,
19 containing, for each of the states, event indicators taking the value 1 if
20 the state is visited or 0 if it is not (censored), or 2) a character vector
21 of length S containing the column names indicating these status variables.
22 In the latter cases, some elements of \code{status} may be NA, see Details}
23
24 \item{data}{Data frame (not a tibble) in wide format in which to interpret
25 \code{time}, \code{status}, \code{id} or \code{keep}, if appropriate}
26
27 \item{trans}{Transition matrix describing the states and transitions in the
28 multi-state model. If S is the number of states in the multi-state model,
29 \code{trans} should be an S x S matrix, with (i,j)-element a positive
30 integer if a transition from i to j is possible in the multi-state model,
31 \code{NA} otherwise. In particular, all diagonal elements should be
32 \code{NA}. The integers indicating the possible transitions in the
33 multi-state model should be sequentially numbered, 1,...,K, with K the
34 number of transitions}
35
36 \item{start}{List with elements \code{state} and \code{time}, containing
37 starting states and times of the subjects in the data. Default is
38 \code{NULL}, in which case all subjects start in state 1 at time 0. If a
39 single state and time are given this state and time is used for all
40 subjects, otherwise the length of \code{state} and \code{time} should equal
41 the number of subjects in \code{data}}
42
43 \item{id}{Either 1) a vector of length n containing the subject
44 identifications, or 2) a character string indicating the column name
45 containing these subject ids. If not provided, \code{"id"} will be assigned
46 with values 1,...,n}
47
48 \item{keep}{Either 1) a data frame or matrix with n rows or a numeric or
49 factor vector of length n containing covariate(s) that need to be retained
50 in the output dataset, or 2) a character vector containing the column names
51 of these covariates in \code{data}}
52 }
53 \value{
54 An object of class \code{"msdata"}, which is a data frame in long
55 (counting process) format containing the subject id, the covariates
56 (replicated per subject), and \item{from}{the starting state} \item{to}{the
57 receiving state} \item{trans}{the transition number} \item{Tstart}{the
58 starting time of the transition} \item{Tstop}{the stopping time of the
59 transition} \item{status}{status variable, with 1 indicating an event
60 (transition), 0 a censoring} The \code{"msdata"} object has the transition
61 matrix as \code{"trans"} attribute.
62 }
63 \description{
64 This function converts a dataset which is in wide format (one subject per
65 line, multiple columns indicating time and status for different states) into
66 a dataset in long format (one line for each transition for which a subject
67 is at risk). Selected covariates are replicated per subjects.
68 }
69 \details{
70 For \code{msprep}, the transition matrix should correspond to an
71 irreversible acyclic Markov chain. In particular, on the diagonals only
72 \code{NA}s are allowed.
73
74 The transition matrix, if irreversible and acyclic, will have starting
75 states, i.e. states into which no transitions are possible. For these
76 starting states \code{NA}s are allowed in the \code{time} and \code{status}
77 arguments, either as columns, when specified as matrix or data frame, or as
78 elements of the character vector when specified as character vector.
79
80 The function \code{msprep} uses a recursive algorithm through calls to the
81 recursive function \code{msprepEngine}. First, with the current transition
82 matrix, all starting states are detected (defined as states into which there
83 are no transitions). For each of these starting states, all subjects
84 starting from that state are selected and for each subject the next visited
85 state is detected by looking at all transitions from that starting state and
86 determining the smallest transition time with \code{status}=1. The recursive
87 \code{msprepEngine} is called again with the starting states deleted from
88 the transition matrix and with subjects deleted that either reached an
89 absorbing state or that were censored. For the remaining subjects the
90 starting states and times are updated in the next call. Datasets returned
91 from the \code{msprepEngine} calls are appended to the current dataset in
92 long format and finally sorted.
93
94 A warning is issued for a subject, if multiple transitions exist with the
95 same smallest transition time (and \code{status}=0). In such cases the next
96 transition cannot be determined unambiguously, and the state with the
97 smallest number is chosen. In our experience, occasionally the shortest
98 transition time has \code{status}=0, while a higher transition time has
99 \code{status}=1. Then this larger transition time and the corresponding
100 transition is selected. No warning is issued for these data inconsistencies.
101 }
102 \examples{
103
104 # transition matrix for illness-death model
105 tmat <- trans.illdeath()
106 # some data in wide format
107 tg <- data.frame(stt=rep(0,6),sts=rep(0,6),
108 illt=c(1,1,6,6,8,9),ills=c(1,0,1,1,0,1),
109 dt=c(5,1,9,7,8,12),ds=c(1,1,1,1,1,1),
110 x1=c(1,1,1,2,2,2),x2=c(6:1))
111 tg$x1 <- factor(tg$x1,labels=c("male","female"))
112 tg$patid <- factor(2:7,levels=1:8,labels=as.character(1:8))
113 # define time, status and covariates also as matrices
114 tt <- matrix(c(rep(NA,6),tg$illt,tg$dt),6,3)
115 st <- matrix(c(rep(NA,6),tg$ills,tg$ds),6,3)
116 keepmat <- data.frame(gender=tg$x1,age=tg$x2)
117 # data in long format using msprep
118 msprep(time=tt,status=st,trans=tmat,keep=as.matrix(keepmat))
119 msprep(time=c(NA,"illt","dt"),status=c(NA,"ills","ds"),data=tg,
120 id="patid",keep=c("x1","x2"),trans=tmat)
121 # Patient no 5, 6 now start in state 2 at time t=4 and t=10
122 msprep(time=tt,status=st,trans=tmat,keep=keepmat,
123 start=list(state=c(1,1,1,1,2,2),time=c(0,0,0,0,4,10)))
124
125 }
126 \references{
127 Putter H, Fiocco M, Geskus RB (2007). Tutorial in biostatistics:
128 Competing risks and multi-state models. \emph{Statistics in Medicine}
129 \bold{26}, 2389--2430.
130 }
131 \author{
132 Hein Putter \email{[email protected]} and Marta Fiocco
133 }
134 \keyword{datagen}