In stc04003/reReg: Recurrent Event Regression

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].

library(reReg)
packageVersion("reReg")

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

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
(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.

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().

summary(recur1)
summary(recur2)

Addendum

Readers are referred to a separate vignette on Recur() for a detailed introduction of Recur(). The reSurv() function is being deprecated in Version 1.2.0. In the current version, the reSurv() function can still be used, but the reSurv object will be automatically transformed to the corresponding Recur object.