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