Debian Codegraph @

man/expand.covs.msdata.Rd

raw
1 % Generated by roxygen2: do not edit by hand
2 % Please edit documentation in R/expand.covs.R
3 \name{expand.covs.msdata}
4 \alias{expand.covs.msdata}
5 \title{Expand covariates in multi-state dataset in long format}
6 \usage{
7 \method{expand.covs}{msdata}(data, covs, append = TRUE, longnames = TRUE, ...)
8 }
9 \arguments{
10 \item{data}{An object of class \code{"msdata"}, such as output by
11 \code{\link{msprep}}}
12
13 \item{covs}{A character vector containing the names of the covariates in
14 \code{data} to be expanded}
15
16 \item{append}{Logical value indicating whether or not the design matrix for
17 the expanded covariates should be appended to the data (default=\code{TRUE})}
18
19 \item{longnames}{Logical value indicating whether or not the labels are to
20 be used for the names of the expanded covariates that are categorical
21 (default=\code{TRUE}); in case of \code{FALSE} numbers from 1 up to the
22 number of contrasts are used}
23
24 \item{\dots}{Further arguments to be passed to or from other methods. They
25 are ignored in this function.}
26 }
27 \value{
28 An object of class 'msdata', containing the design matrix for the
29 transition- specific covariates, either on its own
30 (\code{append}=\code{FALSE}) or appended to the data
31 (\code{append}=\code{TRUE}).
32 }
33 \description{
34 Given a multi-state dataset in long format, and one or more covariates, this
35 function adds transition-specific covariates, expanding the original
36 covariate(s), to the dataset. The original dataset with the
37 transition-specific covariates appended is returned.
38 }
39 \details{
40 For a given basic covariate \code{Z}, the transition-specific covariate for
41 transition \code{s} is called \code{Z.s}. The concept of transition-specific
42 covariates in the context of multi-state models was introduced by Andersen,
43 Hansen & Keiding (1991), see also Putter, Fiocco & Geskus (2007). It is only
44 unambiguously defined for numeric covariates or for explicit codings. Then
45 it will take the value 0 for all rows in the long format dataframe for which
46 \code{trans} does not equal \code{s}. For the rows for which \code{trans}
47 equals \code{s}, the original value of \code{Z} is copied. In
48 \code{expand.covs}, when a given covariate is a factor, it will be expanded
49 on the design matrix given by
50 \code{\link[stats:model.matrix]{model.matrix}}. Missing values in the basic
51 covariates are allowed and result in missing values in the expanded
52 covariates.
53 }
54 \examples{
55
56 # transition matrix for illness-death model
57 tmat <- trans.illdeath()
58 # small data set in wide format
59 tg <- data.frame(illt=c(1,1,6,6,8,9),ills=c(1,0,1,1,0,1),
60 dt=c(5,1,9,7,8,12),ds=c(1,1,1,1,1,1),
61 x1=c(1,1,1,2,2,2),x2=c(6:1))
62 tg$x1 <- factor(tg$x1,labels=c("male","female"))
63 # data in long format using msprep
64 tglong <- msprep(time=c(NA,"illt","dt"),
65 status=c(NA,"ills","ds"),data=tg,
66 keep=c("x1","x2"),trans=tmat)
67 # expanded covariates
68 expand.covs(tglong,c("x1","x2"),append=FALSE)
69 expand.covs(tglong,"x1")
70 expand.covs(tglong,"x1",longnames=FALSE)
71
72 }
73 \references{
74 Andersen PK, Hansen LS, Keiding N (1991). Non- and
75 semi-parametric estimation of transition probabilities from censored
76 observation of a non-homogeneous Markov process. \emph{Scandinavian Journal
77 of Statistics} \bold{18}, 153--167.
78
79 Putter H, Fiocco M, Geskus RB (2007). Tutorial in biostatistics: Competing
80 risks and multi-state models. \emph{Statistics in Medicine} \bold{26},
81 2389--2430.
82 }
83 \author{
84 Hein Putter \email{[email protected]}
85 }
86 \keyword{datagen}