Debian Codegraph @

man/crprep.default.Rd

raw
1 % Generated by roxygen2: do not edit by hand
2 % Please edit documentation in R/crprep.R
3 \name{crprep.default}
4 \alias{crprep.default}
5 \alias{crprep}
6 \title{Function to create weighted data set for competing risks analyses}
7 \usage{
8 \method{crprep}{default}(
9 Tstop,
10 status,
11 data,
12 trans = 1,
13 cens = 0,
14 Tstart = 0,
15 id,
16 strata,
17 keep,
18 shorten = TRUE,
19 rm.na = TRUE,
20 origin = 0,
21 prec.factor = 1000,
22 ...
23 )
24 }
25 \arguments{
26 \item{Tstop}{Either 1) a vector containing the time at which the follow-up
27 is ended, or 2) a character string indicating the column name in \code{data}
28 that contains the end times (see Details).}
29
30 \item{status}{Either 1) a vector describing status at end of follow-up,
31 having the same length as \code{Tstop}, or 2) a character string indicating
32 the column name that contains this information.}
33
34 \item{data}{Data frame in which to interpret \code{Tstart}, \code{status},
35 \code{Tstart}, \code{id}, \code{strata} and \code{keep}, if given as
36 character value (specification 2, "by name").}
37
38 \item{trans}{Values of \code{status} for which weights are to be calculated.}
39
40 \item{cens}{Value that denotes censoring in \code{status} column.}
41
42 \item{Tstart}{Either 1) a vector containing the time at which the follow-up
43 is started, having the same length as \code{Tstop}, or 2) a character string
44 indicating the column name that contains the entry times, or 3) one numeric
45 value in case it is the same for every subject. Default is 0.}
46
47 \item{id}{Either 1) a vector, having the same length as \code{Tstop},
48 containing the subject identifiers, or 2) a character string indicating the
49 column name containing these subject identifiers. If not provided, a column
50 \code{id} is created with subjects having values 1,...,n.}
51
52 \item{strata}{Either 1) a vector of the same length as \code{Tstop}, or 2) a
53 character string indicating the column name that contains this information.
54 Weights are calculated for per value in this vector.}
55
56 \item{keep}{Either 1) a data frame or matrix or a numeric or factor vector
57 containing covariate(s) that need to be retained in the output dataset.
58 Number of rows/length should correspond with \code{Tstop}, or 2) a character
59 vector containing the column names of these covariates in \code{data}.}
60
61 \item{shorten}{Logical. If true, number of rows in output is reduced by
62 collapsing rows within a subject in which weights do not change.}
63
64 \item{rm.na}{Logical. If true, rows for which \code{status} is missing are
65 deleted.}
66
67 \item{origin}{Substract origin time units from all Tstop and Tstart times.}
68
69 \item{prec.factor}{Factor by which to multiply the machine's precision.
70 Censoring and truncation times are shifted by prec.factor*precision if event
71 times and censoring/truncation times are equal.}
72
73 \item{\dots}{Further arguments to be passed to or from other methods. They
74 are ignored in this function.}
75 }
76 \value{
77 A data frame in long (counting process) format containing the
78 covariates (replicated per subject). The following column names are used:
79 \item{Tstart}{start dates of dataset} \item{Tstop}{stop dates of dataset}
80 \item{status}{status of the subject at the end of that row}
81 \item{weight.cens}{weights due to censoring mechanism}
82 \item{weight.trunc}{weights due to truncation mechanism (if present)}
83 \item{count}{row number within subject and event type under consideration}
84 \item{failcode}{event type under consideration}
85
86 The first column is the subject identifier. If the argument "id" is missing,
87 it has values 1:n and is named "id". Otherwise the information is taken from
88 the \code{id} argument.
89
90 Variables as specified in \code{strata} and/or \code{keep} are included as
91 well (see Details).
92 }
93 \description{
94 This function converts a dataset that is in short format (one subject per
95 line) into a counting process format with time-varying weights that correct
96 for right censored and left truncated data. With this data set, analyses
97 based on the subdistribution hazard can be performed.
98 }
99 \details{
100 For each event type as specified via \code{trans}, individuals with a
101 competing event remain in the risk set with weights that are determined by
102 the product-limit forms of the time-to-censoring and time-to-entry
103 estimates. Typically, their weights change over follow-up, and therefore
104 such individuals are split into several rows. Censoring weights are always
105 computed. Truncation weights are computed only if \code{Tstart} is
106 specified.
107
108 If several event types are specified at once, regression analyses using the
109 stacked format data set can be performed (see Putter et al. 2007 and Chapter
110 4 in Geskus 2016). The data set can also be used for a regression on the
111 cause-specific hazard by restricting to the subset \code{subset=count==0}.
112
113 Missing values are allowed in \code{Tstop}, \code{status}, \code{Tstart},
114 \code{strata} and \code{keep}. Rows for which \code{Tstart} or \code{Tstart}
115 is missing are deleted.
116
117 There are two ways to supply the data. If given "by value" (option 1), the
118 actual data vectors are used. If given "by name" (option 2), the column
119 names are specified, which are read from the data set in \code{data}. In
120 general, the second option is preferred.
121
122 If data are given by value, the following holds for the naming of the
123 columns in the output data set. If \code{keep}, \code{strata} or \code{id}
124 is a vector from a (sub)-list, e.g. obj$name2$name1, then the column name is
125 based on the most inner part (i.e.\ "name1"). If it is a vector of the form
126 obj[,"name1"], then the column is named "name1". For all other vector
127 specifications, the name is copied as is. If \code{keep} is a data.frame or
128 a named matrix, the same names are used for the covariate columns in the
129 output data set. If keep is a matrix without names, then the covariate
130 columns are given the names "V1" until "Vk".
131
132 The current function does not allow to create a weighted data set in which
133 the censoring and/or truncation mechanisms depend on covariates via a
134 regression model.
135 }
136 \examples{
137
138 data(aidssi)
139 aidssi.w <- crprep("time", "cause", data=aidssi, trans=c("AIDS","SI"),
140 cens="event-free", id="patnr", keep="ccr5")
141
142 # calculate cause-specific cumulative incidence, no truncation,
143 # compare with Cuminc (also from mstate)
144 ci <- Cuminc(aidssi$time, aidssi$status)
145 sf <- survfit(Surv(Tstart,Tstop,status=="AIDS")~1, data=aidssi.w,
146 weight=weight.cens, subset=failcode=="AIDS")
147 plot(sf, fun="event", mark.time=FALSE)
148 lines(CI.1~time,data=ci,type="s",col="red")
149 sf <- survfit(Surv(Tstart,Tstop,status=="SI")~1, data=aidssi.w,
150 weight=weight.cens, subset=failcode=="SI")
151 plot(sf, fun="event", mark.time=FALSE)
152 lines(CI.2~time,data=ci,type="s",col="red")
153
154 # Fine and Gray regression for cause 1
155 cw <- coxph(Surv(Tstart,Tstop,status=="AIDS")~ccr5, data=aidssi.w,
156 weight=weight.cens, subset=failcode=="AIDS")
157 cw
158 # This can be checked with the results of crr (cmprsk)
159 # crr(ftime=aidssi$time, fstatus=aidssi$status, cov1=as.numeric(aidssi$ccr5))
160
161 # Gray's log-rank test
162 aidssi.wCCR <- crprep("time", "cause", data=aidssi, trans=c("AIDS","SI"),
163 cens="event-free", id="patnr", strata="ccr5")
164 test.AIDS <- coxph(Surv(Tstart,Tstop,status=="AIDS")~ccr5, data=aidssi.wCCR,
165 weights=weight.cens, subset=failcode=="AIDS")
166 test.SI <- coxph(Surv(Tstart,Tstop,status=="SI")~ccr5, data=aidssi.wCCR,
167 weights=weight.cens, subset=failcode=="SI")
168 ## score test statistic and p-value
169 c(test.AIDS$score, 1-pchisq(test.AIDS$score,1)) # AIDS
170 c(test.SI$score, 1-pchisq(test.SI$score,1)) # SI
171 # This can be compared with the results of cuminc (cmprsk)
172 # with(aidssi, cuminc(time, status, group=ccr5)$Tests)
173 # Note: results are not exactly the same
174
175 }
176 \references{
177 Geskus RB (2011). Cause-Specific Cumulative Incidence Estimation
178 and the Fine and Gray Model Under Both Left Truncation and Right Censoring.
179 \emph{Biometrics} \bold{67}, 39--49.
180
181 Geskus, Ronald B. (2016). \emph{Data Analysis with Competing Risks and
182 Intermediate States.} CRC Press, Boca Raton.
183
184 Putter H, Fiocco M, Geskus RB (2007). Tutorial in biostatistics: Competing
185 risks and multi-state models. \emph{Statistics in Medicine} \bold{26},
186 2389--2430.
187 }
188 \author{
189 Ronald Geskus
190 }
191 \keyword{datagen}
192 \keyword{survival}