/
reReg-Recur.Rmd
200 lines (167 loc) · 9.9 KB
/
reReg-Recur.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
---
title: "Creating `Recur` objects"
author: Sy Han (Steven) Chiou
date: "`r Sys.Date()`"
output:
rmarkdown::html_document:
toc: true
toc_depth: 2
toc_float: true
bibliography: ../inst/bib/reReg.bib
vignette: >
%\VignetteIndexEntry{Creating `Recur` objects}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}{inputenc}
---
```{r default, include = FALSE, collapse = TRUE}
library(knitr)
opts_chunk$set(prompt = TRUE, comment = "")
hook_output <- knit_hooks$get("output")
knit_hooks$set(output = function(x, options) {
lines <- options$output.lines
if (is.null(lines)) {
return(hook_output(x, options)) # pass to default hook
}
x <- unlist(strsplit(x, "\n"))
more <- "..."
if (length(lines)==1) { # first n lines
if (length(x) > lines) {
# truncate the output, but add ....
x <- c(head(x, lines), more)
}
} else {
x <- c(more, x[lines], more)
}
# paste these lines together
x <- paste(c(x, ""), collapse = "\n")
hook_output(x, options)
})
```
In this vignette, we demonstrate how to create a recurrent event object with the
`Recur()` function from the __`reda`__ package [@R:reda].
The `Recur()` function is imported when the __`reReg`__ package is loaded.
The `Recur` object bundles together a set of recurrent times, failure time, and censoring status,
with the convenience that it can be used as the response in model formula in the __`reReg`__ package.
We will illustrate the usage of `Recur()` with the `cgd` data set from the __`survival`__ [@R:survival]
and the `readmission` data set from the __`frailtypack`__
package [@rondeau2012frailtypack], [@gonzalez2005sex].
```{r load-pkg, message = FALSE}
library(reReg)
packageVersion("reReg")
```
```{r data}
data(readmission, package = "frailtypack")
head(readmission)
readmission <- subset(readmission, !(id %in% c(60, 109, 280)))
```
## The `Recur` interface
The `Recur()` function is modeled after the `Surv()` function in the __`survival`__ package [@R:survival].
The function interface of `Recur()` is
```{R}
args(Recur)
```
The six arguments are
* `time`: event and censoring times.
It can be a vector that represents the time of recurrent events and censoring,
or as a list of time intervals that contains the starting time and the ending time of the interval.
In the latter, the intervals are assumed to be open on the left and closed on the right,
where the right end points are the time of recurrent events and censoring.
* `id`: subject's id.
It can be numeric vector, character vector, or a factor vector.
If it is left unspecified, `Recur()` will assume that each row represents a subject.
* `event`: event indicator of recurrent events.
This is a numeric vector that represents the types of the recurrent events.
Logical vector is allowed and converted to numeric vector. Non-positive values are internally converted to zero indicating censoring status.
* `terminal`: event indicator of terminal events.
This is a numeric vector that represents the status of the terminal event. Logical vector is allowed and converted to numeric vector. Non-positive values are internally converted to zero indicating censoring status. If a scalar value is specified, all subjects will have the same status of terminal events at their last recurrent episodes. The length of the specified `terminal` should be equal to the number of subjects, or number of data rows. In the latter case, each subject may have at most one positive entry of `terminal` at the last recurrent episode.
* `origin`: time origin of subjects.
This is a numerical vector indicating the time origin of each subject. If a scalar value is specified, all subjects will have the same origin at the specified value. The length of the specified `origin` should be equal to the number of subjects, or number of data rows. In the latter case, different subjects may have different origins. However, one subject must have the same origin. In addition to numeric values, `Date` and `difftime` are also supported and converted to numeric values.
* `check`: indicates how to run the data checking procedure.
This is a character value specifying how to perform the checks for recurrent event data. Errors or warnings will be thrown, respectively, if the `check` is specified to be `"hard"` (default) or `"soft"`. If `check = "none"` is specified, no data checking procedure will be run.
## The `Recur` object
When the time origin is zero for all subjects as in the `readmission` data set,
the `time` argument can be specified with `time = t.stop` or with `time = t.start %to% t.stop`,
where the infix operator `%to%` is used to create a list of two elements containing the endpoints of the time intervals.
When `check = "hard"` or `check = "soft"`,
the `Recur()` function performs an internal check for possible issues on the data structure.
The `Recur()` function terminates and issues an error message once the check failed if
`check = "hard"` (default).
On the contrary, `Recur()` would proceed with a warning message when `check = "soft"`
or without a warning message when `check = "none"`.
The checking criterion includes the following:
\begin{enumerate}
\item Every subject must have one censoring time.
\item Each subject's censoring time must be greater than all recurrent event times.
\item Recurrent event and censoring times cannot be missing.
\item Recurrent event and censoring times cannot be earlier than the origin time.
\item When the `time` argument is a list, the time intervals cannot overlap.
\end{enumerate}
The `Recur()` function matches the arguments by position when the arguments' names are not specified.
Among all the arguments,
only the argument `time` does not have default values and has to be specified by users.
The default value for the argument `id` is `seq_along(time)`, thus,
`Recur()` assumes each row specifies the time point for each subject when `id` is not specified.
However, using the default value `id` defeats the purpose using recurrent event methods.
The default value for the argument `event` is a numerical vector,
where the values 0 and 1 are used to indicate whether the endpoint
of the time intervals in `time` is a
non-recurrent event or a recurrent event, respectively.
The `event` argument can accommodate more than one types of recurrent events;
in this case the reference level (value 0) is used to indicate non-recurrent event.
On the other hand, a zero vector is used as the default value for arguments
`terminal` and `orgin`.
The default values in `Recur()` are chosen so that `Recur()` can be conveniently adopted
in common situations.
For example, in situations where the recurrent events are observed continuously and
in the absence of terminal events,
the `event` and `terminal` arguments can be left unspecified.
In this case, the last entry within each subject will be treated as a censoring time.
One example is the `cgd` data from the __*survival*__ package,
where the recurrent event is the serious infection observed from
a placebo controlled trial of gamma interferon in chronic granulotamous disease.
A terminal event was not defined in the `cgd` data and
the patients were observed through the end of study.
For this dataset, the `Recur` object can be constructed as below:
```{R, output.lines = 1:10}
data(cgd, package = "survival")
(recur1 <- with(cgd, Recur(tstart %2% tstop, id)))
```
For each subject, the function `Recur()` prints intervals to represent the duration until the next event
(a recurrent event or a terminal event).
The `Recur` object for the `readmission` dataset can be constructed as below:
```{r Recur-obj-short2, eval = TRUE, output.lines = 1:10}
(recur2 <- with(readmission, Recur(t.stop, id, event, death)))
```
The `readmission` example above shows patient id \#1 experienced two hospital readmissions
with a terminal event at `t = 1037` (days).
The `+` at `t = 1037` indicates the terminal time was censored, e.g., this patient did not experience the event of interest (death) at `t = 1037`.
Similarly, patient id \#3 has one readmission and died at `t = 783` (days) as indicated by `*` at `783`.
On the other hand patient id \# 4 has more than 3 readmissions and was censored at `t = 2048` (days).
The readmission intervals was suppressed to prevent printing results wider than the screen allowance.
The number of intervals to be printed can be tuned using the `options` and argument `reda.Recur.maxPrint`.
## The `Recur` output
The `Recur()` returns an S4-class representing model response for recurrent event data.
The following shows the structure of the `Recur` object created for `cgd` data.
```{R}
str(recur1)
```
The slots of the `Recur` S4-class are
- `.Data`: a numerical matrix with columns `time1`, `time2`, `id`, `event`, `terminal`, and `origin`.
- `call`: a function call producing the `Recur` object.
- `ID`: a character string storing the original subject ID.
- `ord`: indices that sort the response matrix by rows. Sorting is in an increasing order by `id`, `time2`, and `-event`.
- `rev_ord`: indices that revert the increasingly sorted response matrix by `ord` to its original ordering.
- `first_idx`: indices that indicates the first record of each subject in the sorted matrix.
- `last_idx`: indices that indicates the last record of each subject in the sorted matrix.
- `check`: a character string that records the specified `check` argument in `Recur()`.
- `time_class`: a character string the original times if specified in calendar dates.
The summary for `Recur` object can be printed with `summary()`.
```{R}
summary(recur1)
summary(recur2)
```
## Addendum
Readers are referred to a separate [vignette on `Recur()`](https://wenjie-stat.me/reda/articles/reda-recur) for a detailed introduction of `Recur()`.
**<span style="color:red">The `reSurv()` function is being deprecated in Version 1.2.0.</span>**
In the current version, the `reSurv()` function can still be used, but the `reSurv` object will be automatically transformed to the corresponding `Recur` object.
## Reference