Constructors and methods for a right-censored data type. v_rcensored and rcen are synonyms that each create a new v_rcensored object subclassed from censored, vctrs_rcrd, and vctrs_vctr. Unlike other representations, such the survival package's Surv object, v_rcensored can be subset with [ and concatenated with c as you would any other vector. The type is implemented as a new_rcrd where the necessary data are contained in fields.

v_rcensored(
  outcomes = v_continuous_nonneg(),
  censors,
  end_time = Inf,
  internal_name = "",
  context,
  auto_compute_summary = auto_compute_default,
  extra_descriptors = list()
)

rcen(
  outcomes = v_continuous_nonneg(),
  censors,
  end_time = Inf,
  internal_name = "",
  context,
  auto_compute_summary = auto_compute_default,
  extra_descriptors = list()
)

is_rcensored(x)

# S3 method for v_rcensored
as.character(x, ...)

# S3 method for v_rcensored
as_canonical(x)

Arguments

outcomes

Either a v_continuous_nonneg vector or a list of v_continuous_nonneg vectors that define the outcomes. The order of this list defines the precedence of outcomes. That is,if the first outcome and second outcome occur at the same time, the first outcome is the reason for the outcome. Use Inf to indicate that an event has not been observed.

censors

A list of v_continuous_nonneg vectors that define the censor The order of this list defines the precedence of censoring That is, if the first censor and second censor occur at the same time, the first censor is the reason for the censoring. Use Inf to indicate that an event has not been observed.

end_time

A numeric scalar defining the end of follow-up.

internal_name

the internal name of the variable

context

a context

auto_compute_summary

an indicator of whether the data_summary is automatically computed whenever a vector is initialized, subset, or concatenated. Defaults to TRUE. If this option is set to FALSE, then get_data_summary is the only way to compute the summary. The data_summary_l lens will return an empty data_summary.

extra_descriptors

A list of descriptors functions appended to the default descriptors.

x

a logical vector or any vector that can be cast to a logical vector via vctrs::vec_cast() such as integer or numeric vectors with values in {0, 1}.

...

passed to other methods such as as.character

Details

as_canonical casts the vector to a list. See v_rcensored_accessors for functions to access components of a v_rcensored.

When printed, an open right triangle indicates an observation was censored. A closed right triangle indicates an observation reached end_time without being censored or having an outcome. No triangle indicates an observation that has at least one of the outcomes.

When constructing v_rcensored, the input must not contain NA values. Use Inf to indicate that an event has not been observed.

The levels/labels follow the following rules:

  1. If a named list (all elements must be uniquely named) is passed to outcomes (or censors) and all the vectors have short labels, then the list names are the levels and the short labels become the labels.

  2. If a named list is passed to outcomes (or censors) and any of the vectors are missing short labels, then the list names become the levels and the labels.

  3. If a unnamed list is passed and all the vectors have internal names and all the vectors have short labels, then the internal names are the levels and the short labels become the labels.

  4. If a unnamed list is passed and all the vectors have internal names any of the vectors are missing short labels, then the internal names become the levels and labels.

  5. Otherwise, as.character(1:length(x)) become the levels and labels, where length(x) is the number of list elements.

Examples

# Example censoring times data
ctimeA <- v_continuous_nonneg(c(5, 6, 10, 1, Inf, 19), internal_name = "cA")
ctimeB <- v_continuous_nonneg(c(4, 1, 15, Inf, Inf, 21), internal_name = "cB")

# Example outcome times data
otimeA <- v_continuous_nonneg(c(2, 6, 11, 12, Inf, 25), internal_name = "oA")
otimeB <- v_continuous_nonneg(c(1, Inf, 10, Inf, Inf, 23), internal_name = "oB")

# Constructor for the `v_rcensored` class. One can also use `rcen` which is a
# synonym for the `v_rcensored` function.
v <- v_rcensored(
  outcomes = list(ctimeA, ctimeB),
  censors = list(otimeA, otimeB),
  end_time = 15,
  internal_name = "v_example",
  context = context(
    short_label = "important_var",
    long_label  = "Very important variable"
  ),
  extra_descriptors = list()
)

# Helper functions and methods
is_rcensored(v)
#> [1] TRUE
as.character(v)
#> [1] "1▹"  "1 "  "10 " "1 "  "15▸" "15▸"
as_canonical(v)
#> $time
#> <continuous nonnegative[6]>
#> [1] 1  1  10 1  15 15
#> Mean = 7.167; SD = 6.998
#> 
#> $censored
#> <binary[6]>
#> [1] 1 0 0 0 0 0
#> Proportion = 0.167
#> 
#> $outcome
#> <binary[6]>
#> [1] 0 1 1 1 0 0
#> Proportion = 0.500
#> 
#> $censor_reason
#> <nominal[6]>
#> [1] oB   <NA> <NA> <NA> <NA> <NA>
#> Proportions: oA: 0% oB: 17% NA: 83%; Missing = 5
#> 
#> $outcome_reason
#> <nominal[6]>
#> [1] <NA> cB   cA   cA   <NA> <NA>
#> Proportions: cA: 33% cB: 17% NA: 50%; Missing = 3
#>