# Introduction to Formula Response Function Recur()

#### Wenjie Wang

#### 2020-07-07

    library(reda)
    packageVersion("reda")

    ## [1] '0.5.2'

# Overview

The `Recur()` function provides a flexible and widely applicable formula response interface for modeling recurrent event data with considerate data checking procedures. It combined the flexible interface of `reSurv()` (deprecated in reReg version 1.1.7) and the effective checking procedures embedded in the `Survr()` (deprecated in reda version 0.5.0).

# Function Interface

The function interface of `Recur()` is given below.

    Recur(time, id, event, terminal, origin, check = c("hard", "soft", "none"), ...)

A high-level introduction to each argument is as follows:

- `time`: event and censoring times
- `id`: subject’s id
- `event`: recurrent event indicator, cost, or type
- `terminal`: event indicator of terminal events
- `origin`: time origin of subjects
- `check`: how to run the data checking procedure
  - `"hard"`: throw errors if the `check_Recur()` finds any issue on the data structure
  - `"soft"`: throw warnings instead
  - `"none"`: not to run the checking procedure

More details of arguments are provided in the function documentation by `?Recur`.

# The `Recur` Object

The function `Recur()` returns an S4-class `Recur` object representing model response for recurrent event data. The `Recur` class object mainly contains a numerical matrix object (in the `.Data` slot) that serves as a model response matrix. The other slots are

- `ID`: a factor storing the original subject’s ID, which originally can be a character vector, a numeric vector, or a factor). It is needed to pinpoint data issues for particular subjects with their original ID’s.
- `ord`: indices that sort the response matrix (by rows) increasingly by `id`, `time2`, and `- event`. Sorting is often done in the model-fitting steps, where the indices stored in this slot can be used directly.
- `rev_ord`: indices that revert the increasingly sorted response matrix by `ord` to its original ordering. This slot is provided to easily revert the sorting.
- `first_idx`: indices that indicates the first record of each subject in the sorted matrix. It helps in the data checking produce and may be helpful in model-fitting step, such as getting the origin time.
- `last_idx`: indices that indicates the last record of each subject in the sorted matrix. Similar to `first_idx`, it helps in the data checking produce and may be helpful in the model-fitting step, such as locating the terminal events.
- `check`: a character string that records the specified `check` argument. It just records the option that users specified on data checking.

# Usage

Among all the arguments, only the argument `time` does not have default values and thus has to be specified by users.

## When only `time` is given

- The function assumes that each time point is specified for each subject.
- The `id` takes its default value: `seq_along(time)`.
- The `event` takes its default values: `0` (censoring) at the last record of each subject, and `1` (event) before censoring.
- Both `terminal` and `origin` take zero for all subjects by default.

    ex1 <- Recur(3:5)
    head(ex1)

         time1 time2 id event terminal origin
    [1,]     0     3  1     0        0      0
    [2,]     0     4  2     0        0      0
    [3,]     0     5  3     0        0      0

## When `time` and `id` are given

- The `event` takes its default values: `0` (censoring) at the last record of each subject, and `1` (event) before censoring.
- Both `terminal` and `origin` take zero for all subjects by default.

    ex2 <- Recur(6:1, id = rep(1:2, 3))
    head(ex2)

         time1 time2 id event terminal origin
    [1,]     4     6  1     0        0      0
    [2,]     3     5  2     0        0      0
    [3,]     2     4  1     1        0      0
    [4,]     1     3  2     1        0      0
    [5,]     0     2  1     1        0      0
    [6,]     0     1  2     1        0      0

    ## sort by id, time2, and - event
    head(ex2[ex2@ord, ])

         time1 time2 id event terminal origin
    [1,]     0     2  1     1        0      0
    [2,]     2     4  1     1        0      0
    [3,]     4     6  1     0        0      0
    [4,]     0     1  2     1        0      0
    [5,]     1     3  2     1        0      0
    [6,]     3     5  2     0        0      0

- The slot `ord` stores the indices that sort the response matrix by `id`, `time2`, and `- event`.

## Helper `%to%` for recurrent episodes

The function `Recur()` allows users to input recurrent episodes by `time1` and `time2`, which can be specified with help of `%to%` (or its alias `%2%`) in `Recur()`. For example,

    left <- c(1, 5, 7)
    right <- c(3, 7, 9)
    ex3 <- Recur(left %to% right, id = c("A1", "A1", "A2"))
    head(ex3)

         time1 time2 id event terminal origin
    [1,]     1     3  1     1        0      1
    [2,]     5     7  1     0        0      1
    [3,]     7     9  2     0        0      7

Internally, the function `%to%` returns a list with element named `"time1"` and `"time2"`. Therefore, it is equivalent to specify such a list.

    ex4 <- Recur(list(time1 = left, time2 = right), id = c("A1", "A1", "A2"))
    stopifnot(all.equal(ex3, ex4))

## About `origin` and `terminal`

- Both `origin` and `terminal` take a numeric vector.
- The length of specified vector can be one, equal to the number of subjects, or the number of `time`. Some simple examples are given below.

    ex5 <- Recur(3:5, origin = 1, terminal = 1)
    head(ex5)

         time1 time2 id event terminal origin
    [1,]     1     3  1     0        1      1
    [2,]     1     4  2     0        1      1
    [3,]     1     5  3     0        1      1

    ex6 <- Recur(3:5, id = c("A1", "A1", "A2"), origin = 1:2, terminal = c(0, 1))
    head(ex6)

         time1 time2 id event terminal origin
    [1,]     1     3  1     1        0      1
    [2,]     3     4  1     0        0      1
    [3,]     2     5  2     0        1      2

    ex7 <- Recur(3:5, id = c("A1", "A1", "A2"),
                 origin = c(1, 1, 2), terminal = c(0, 0, 1))
    stopifnot(all.equal(ex6, ex7))

- An error message will be thrown out if the length is inappropriate.

    try(Recur(1:10, origin = c(1, 2)))

    Error : Invalid length for `origin`. See '?Recur' for details.

    try(Recur(1:10, terminal = c(1, 2)))

    Error : Invalid length for 'terminal'.  See '?Recur' for details.

## Data Checking Rules

The `Recur()` (internally calls `check_Recur()` and) checks whether the specified data fits into the recurrent event data framework by several rules if `check = "hard"` or `check = "soft"`. The existing rules and the corresponding examples are given below.

1. Every subject must have one censoring not before any event time.

    try(Recur(1:5, id = c(rep("A1", 3), "A2", "A3"), event = c(0, 0, 1, 0, 0)))

    Error : Subjects having events at or after censoring: A1.

2. Every subject must have one terminal event time.

    try(Recur(1:3, id = rep("A1", 3), terminal = c(0, 1, 1)))

    Error : Subjects having multiple terminal events: A1.

3. Event or censoring times cannot be missing.

    try(Recur(c(1:2, NA), id = rep("A1", 3)))

    Error : Missing times! Please check subject: A1.

4. Event times cannot be earlier than the origin time.

    try(Recur(3:5, id = rep("A1", 3), origin = 10))

    Error : Event times must be >= origin. Please check subject: A1.

    try(Recur(3:5 %to% 1:3, id = rep("A1", 3)))

    Error : Event times must be >= origin. Please check subject: A1.

5. The recurrent episode cannot be overlapped.

    try(Recur(c(0, 3, 5) %to% c(1, 6, 10), id = rep("A1", 3)))

    Error : Recurrent episodes cannot be overlapped. Please check subject: A1.

6. However, recurrent episode without events is allowed for possible time-varying covariates and risk-free gaps.

    Recur(c(0, 2, 6) %to% c(1, 3, 8), id = rep("A1", 3), event = c(0, 1, 0))

    [1] A1: (0, 1+], (2, 3], (6, 8+]

# The `Show()` Method

A `show()` method is added for the `Recur` object in a similar fashion to the output of the function `survival:::print.Surv()`, which internally converts the input `Recur` object to character strings representing the recurrent episodes by a dedicated `as.character()` method. For each recurrent episode,

- Censoring not due to terminal is indicated by a trailing `+` sign;
- Censoring due to terminal is indicated by a trailing `*` sign;
- Otherwise, an event happens at the end of the recurrent episode.

For a concise printing, the `show()` method takes the `getOption("reda.Recur.maxPrint")` to limit the maximum number of recurrent episodes to be printed for each process. By default, `options(reda.Recur.maxPrint = 3)` is set.

## The Valve Seats Example

We may illustrate the results of the `show()` method by the example valve seats data, where terminal events are artificially added.

    set.seed(123)
    term_events <- rbinom(length(unique(valveSeats$ID)), 1, 0.5)
    with(valveSeats, Recur(Days, ID, No., term_events))

     [1] 251: (0, 761+]
     [2] 252: (0, 759*]
     [3] 327: (0, 98], (98, 667*]
     [4] 328: (0, 326], (326, 653], ..., (653, 667*]
     [5] 329: (0, 665+]
     [6] 330: (0, 84], (84, 667*]
     [7] 331: (0, 87], (87, 663*]
     [8] 389: (0, 646], (646, 653*]
     [9] 390: (0, 92], (92, 653*]
    [10] 391: (0, 651*]
    [11] 392: (0, 258], (258, 328], ..., (621, 650+]
    [12] 393: (0, 61], (61, 539], (539, 648*]
    [13] 394: (0, 254], (254, 276], ..., (640, 644*]
    [14] 395: (0, 76], (76, 538], (538, 642*]
    [15] 396: (0, 635], (635, 641*]
    [16] 397: (0, 349], (349, 404], ..., (561, 649+]
    [17] 398: (0, 631*]
    [18] 399: (0, 596*]
    [19] 400: (0, 120], (120, 479], (479, 614+]
    [20] 401: (0, 323], (323, 449], (449, 582+]
    [21] 402: (0, 139], (139, 139], (139, 589*]
    [22] 403: (0, 593+]
    [23] 404: (0, 573], (573, 589*]
    [24] 405: (0, 165], (165, 408], ..., (604, 606+]
    [25] 406: (0, 249], (249, 594*]
    [26] 407: (0, 344], (344, 497], (497, 613*]
    [27] 408: (0, 265], (265, 586], (586, 595+]
    [28] 409: (0, 166], (166, 206], ..., (348, 389+]
    [29] 410: (0, 601+]
    [30] 411: (0, 410], (410, 581], (581, 601+]
    [31] 412: (0, 611+]
    [32] 413: (0, 608+]
    [33] 414: (0, 587*]
    [34] 415: (0, 367], (367, 603+]
    [35] 416: (0, 202], (202, 563], ..., (570, 585*]
    [36] 417: (0, 587+]
    [37] 418: (0, 578*]
    [38] 419: (0, 578*]
    [39] 420: (0, 586*]
    [40] 421: (0, 585+]
    [41] 422: (0, 582*]

## On Missing times

The updated `show()` method preserves `NA`’s when `check = "none"`. However, `NA`’s will always appear because times are sorted internally.

    Recur(c(NA, 3:6, NA), id = rep(1:2, 3), check = "none")

    [1] 1: (0, 4], (4, 6], (6, NA+] 2: (0, 3], (3, 5], (5, NA+]

## Number of digits

The `show()` method takes the value of `options("digits") - 3` to determine the largest number of digits for printing.

    op <- options()
    getOption("digits")

    [1] 7

    Recur(pi, 1)

    [1] 1: (0.0000, 3.1416+]

    options(digits = 10)
    Recur(pi, 1)

    [1] 1: (0.0000000, 3.1415927+]

    options(op) # reset (all) initial options