Introduction to Formula Response Function Recur()

knitr::opts_chunk$set(comment = "")
head <- utils::head
library(reda)
packageVersion("reda")

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:

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

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

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

When time and id are given

ex2 <- Recur(6:1, id = rep(1:2, 3))
head(ex2)
## sort by id, time2, and - event
head(ex2[ex2@ord, ])

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)

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, check.attributes = FALSE))

About origin and terminal

ex5 <- Recur(3:5, origin = 1, terminal = 1)
head(ex5)
ex6 <- Recur(3:5, id = c("A1", "A1", "A2"), origin = 1:2, terminal = c(0, 1))
head(ex6)
ex7 <- Recur(3:5, id = c("A1", "A1", "A2"),
             origin = c(1, 1, 2), terminal = c(0, 0, 1))
stopifnot(all.equal(ex6, ex7, check.attributes = FALSE))
try(Recur(1:10, origin = c(1, 2)))
try(Recur(1:10, terminal = c(1, 2)))

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)))
  1. Every subject must have one terminal event time.
try(Recur(1:3, id = rep("A1", 3), terminal = c(0, 1, 1)))
  1. Event or censoring times cannot be missing.
try(Recur(c(1:2, NA), id = rep("A1", 3)))
  1. Event times cannot be earlier than the origin time.
try(Recur(3:5, id = rep("A1", 3), origin = 10))
try(Recur(3:5 %to% 1:3, id = rep("A1", 3)))
  1. The recurrent episode cannot be overlapped.
try(Recur(c(0, 3, 5) %to% c(1, 6, 10), id = rep("A1", 3)))
  1. 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))

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,

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

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")

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")
Recur(pi, 1)
options(digits = 10)
Recur(pi, 1)
options(op) # reset (all) initial options


Try the reda package in your browser

Any scripts or data that you put into this service are public.

reda documentation built on April 2, 2021, 5:07 p.m.