Package 'tidycmprsk' reference manual

Title:	Competing Risks Estimation
Description:	Provides an intuitive interface for working with the competing risk endpoints. The package wraps the 'cmprsk' package, and exports functions for univariate cumulative incidence estimates and competing risk regression. Methods follow those introduced in Fine and Gray (1999) <doi:10.1002/sim.7501>.
Authors:	Daniel D. Sjoberg [aut, cre, cph] , Teng Fei [aut]
Maintainer:	Daniel D. Sjoberg <[email protected]>
License:	AGPL (>= 3)
Version:	1.0.0.9001
Built:	2024-11-17 05:26:27 UTC
Source:	https://github.com/MSKCC-Epi-Bio/tidycmprsk

Additional Functions for `tbl_cuminc()`

Description

add_p() Add column with p-value comparing incidence across stratum
add_n() Add column with the total N, or N within stratum
add_nevent() Add column with the total number of events, or number of events within stratum
inline_text() Report statistics from a tbl_cuminc() table inline

Usage

## S3 method for class 'tbl_cuminc'
add_p(x, pvalue_fun = gtsummary::style_pvalue, ...)

## S3 method for class 'tbl_cuminc'
add_n(x, location = NULL, ...)

## S3 method for class 'tbl_cuminc'
add_nevent(x, location = NULL, ...)

## S3 method for class 'tbl_cuminc'
inline_text(x, time = NULL, column = NULL, outcome = NULL, level = NULL, ...)
## S3 method for class 'tbl_cuminc'
add_p(x, pvalue_fun = gtsummary::style_pvalue, ...)

## S3 method for class 'tbl_cuminc'
add_n(x, location = NULL, ...)

## S3 method for class 'tbl_cuminc'
add_nevent(x, location = NULL, ...)

## S3 method for class 'tbl_cuminc'
inline_text(x, time = NULL, column = NULL, outcome = NULL, level = NULL, ...)

Arguments

`x`	object of class 'tbl_cuminc'
`pvalue_fun`	function to style/format p-values. Default is `gtsummary::style_pvalue`
`...`	These dots are for future extensions and must be empty.
`location`	location to place Ns. When `"label"` total Ns are placed on each variable's label row. When `"level"` level counts are placed on the variable level for categorical variables, and total N on the variable's label row for continuous.
`time`	time of statistic to report
`column`	column name of the statistic to report
`outcome`	string indicating the outcome to select from. If `NULL`, the first outcome is used.
`level`	if estimates are stratified, level of the stratum to report

Example Output

Example 1

Example 2

p-values

The p-values reported in cuminc(), glance.tidycuminc() and add_p.tbl_cuminc() are Gray's test as described in Gray RJ (1988) A class of K-sample tests for comparing the cumulative incidence of a competing risk, Annals of Statistics, 16:1141-1154.

Examples

# Example 1 ----------------------------------
add_cuminc_ex1 <-
  cuminc(Surv(ttdeath, death_cr) ~ 1, trial) %>%
  tbl_cuminc(times = c(12, 24), label_header = "**Month {time}**") %>%
  add_nevent() %>%
  add_n()

# Example 2 ----------------------------------
add_cuminc_ex2 <-
  cuminc(Surv(ttdeath, death_cr) ~ trt, trial) %>%
  tbl_cuminc(times = c(12, 24),
             outcomes = c("death from cancer", "death other causes"),
             label_header = "**Month {time}**") %>%
  add_p() %>%
  add_nevent(location = c("label", "level")) %>%
  add_n(location = c("label", "level"))

# inline_text() ------------------------------
inline_text(add_cuminc_ex2, time = 12, level = "Drug A")
inline_text(add_cuminc_ex2, column = p.value)

# Example 1 ----------------------------------
add_cuminc_ex1 <-
  cuminc(Surv(ttdeath, death_cr) ~ 1, trial) %>%
  tbl_cuminc(times = c(12, 24), label_header = "**Month {time}**") %>%
  add_nevent() %>%
  add_n()

# Example 2 ----------------------------------
add_cuminc_ex2 <-
  cuminc(Surv(ttdeath, death_cr) ~ trt, trial) %>%
  tbl_cuminc(times = c(12, 24),
             outcomes = c("death from cancer", "death other causes"),
             label_header = "**Month {time}**") %>%
  add_p() %>%
  add_nevent(location = c("label", "level")) %>%
  add_n(location = c("label", "level"))

# inline_text() ------------------------------
inline_text(add_cuminc_ex2, time = 12, level = "Drug A")
inline_text(add_cuminc_ex2, column = p.value)

Functions for tidycrr objects

Description

Functions for tidycrr objects

Usage

## S3 method for class 'tidycrr'
coef(object, ...)

## S3 method for class 'tidycrr'
vcov(object, ...)

## S3 method for class 'tidycrr'
model.matrix(object, ...)

## S3 method for class 'tidycrr'
model.frame(formula, ...)

## S3 method for class 'tidycrr'
terms(x, ...)
## S3 method for class 'tidycrr'
coef(object, ...)

## S3 method for class 'tidycrr'
vcov(object, ...)

## S3 method for class 'tidycrr'
model.matrix(object, ...)

## S3 method for class 'tidycrr'
model.frame(formula, ...)

## S3 method for class 'tidycrr'
terms(x, ...)

Arguments

`...`	not used
`formula`	a formula
`x`, `object`	a tidycrr object

Value

coef vector, model matrix, model frame, terms object

Examples

mod <- crr(Surv(ttdeath, death_cr) ~ age + grade, trial)

coef(mod)

model.matrix(mod) %>% head()

model.frame(mod) %>% head()

terms(mod)
mod <- crr(Surv(ttdeath, death_cr) ~ age + grade, trial)

coef(mod)

model.matrix(mod) %>% head()

model.frame(mod) %>% head()

terms(mod)

Functions for tidycuminc objects

Description

Functions for tidycuminc objects

Usage

## S3 method for class 'tidycuminc'
model.frame(formula, ...)

## S3 method for class 'tidycuminc'
model.matrix(object, ...)
## S3 method for class 'tidycuminc'
model.frame(formula, ...)

## S3 method for class 'tidycuminc'
model.matrix(object, ...)

Arguments

`formula`	a formula
`...`	not used
`object`	a tidycuminc object

Value

a model frame, or model matrix

Examples

fit <- cuminc(Surv(ttdeath, death_cr) ~ trt, trial)

model.matrix(fit) %>% head()

model.frame(fit) %>% head()
fit <- cuminc(Surv(ttdeath, death_cr) ~ trt, trial)

model.matrix(fit) %>% head()

model.frame(fit) %>% head()

Broom methods for tidycrr objects

Description

Broom methods for tidycrr objects

Usage

## S3 method for class 'tidycrr'
tidy(x, exponentiate = FALSE, conf.int = FALSE, conf.level = x$conf.level, ...)

## S3 method for class 'tidycrr'
glance(x, ...)

## S3 method for class 'tidycrr'
augment(x, times = NULL, probs = NULL, newdata = NULL, ...)
## S3 method for class 'tidycrr'
tidy(x, exponentiate = FALSE, conf.int = FALSE, conf.level = x$conf.level, ...)

## S3 method for class 'tidycrr'
glance(x, ...)

## S3 method for class 'tidycrr'
augment(x, times = NULL, probs = NULL, newdata = NULL, ...)

Arguments

`x`	a tidycrr object
`exponentiate`	Logical indicating whether or not to exponentiate the coefficient estimates. Defaults to `FALSE`.
`conf.int`	Logical indicating whether or not to include a confidence interval in the tidied output. Defaults to `FALSE`.
`conf.level`	Level of the confidence interval. Default matches that in `crr(conf.level=)` (typically, 0.95)
`...`	not used
`times`	Numeric vector of times to obtain risk estimates at
`probs`	Numeric vector of quantiles to obtain estimates at
`newdata`	A `base::data.frame()` or `tibble::tibble()` containing all the original predictors used to create x. Defaults to `NULL`.

Value

a tibble

Examples

crr <- crr(Surv(ttdeath, death_cr) ~ age + grade, trial)

tidy(crr)

glance(crr)

augment(crr, times = 12)
crr <- crr(Surv(ttdeath, death_cr) ~ age + grade, trial)

tidy(crr)

glance(crr)

augment(crr, times = 12)

Broom methods for tidy cuminc objects

Description

Broom methods for tidy cuminc objects

Usage

## S3 method for class 'tidycuminc'
tidy(x, times = NULL, conf.int = TRUE, conf.level = x$conf.level, ...)

## S3 method for class 'tidycuminc'
glance(x, ...)
## S3 method for class 'tidycuminc'
tidy(x, times = NULL, conf.int = TRUE, conf.level = x$conf.level, ...)

## S3 method for class 'tidycuminc'
glance(x, ...)

Arguments

`x`	object of class 'tidycuminc'
`times`	Numeric vector of times to obtain risk estimates at
`conf.int`	Logical indicating whether or not to include a confidence interval in the tidied output. Defaults to `FALSE`.
`conf.level`	Level of the confidence interval. Default matches that in `cuminc(conf.level=)` (typically, 0.95)
`...`	not used

Value

a tibble

`tidy()` data frame

The returned tidy() data frame returns the following columns:

Column Name	Description
`outcome`	Competing Event Outcome
`time`	Numeric follow-up time
`estimate`	Risk estimate
`std.error`	Standard Error
`n.risk`	Number at risk at the specified time
`n.event`	If the `⁠times=⁠` argument is missing, then the number of events that occurred at time `t`. Otherwise, it is the cumulative number of events that have occurred since the last time listed.
`n.censor`	If the `⁠times=⁠` argument is missing, then the number of censored obs at time `t`. Otherwise, it is the cumulative number of censored obs that have occurred since the last time listed.
`cum.event`	Cumulative number of events at specified time
`cum.censor`	Cumulative number of censored observations at specified time

If tidy(time=) is specified, then n.event and n.censor are the cumulative number of events/censored in the interval. For example, if tidy(time = c(0, 12, 18)) is passed, n.event and n.censor at time = 18 are the cumulative number of events/censored in the interval ⁠(12, 18]⁠.

p-values

Confidence intervals

The confidence intervals for cumulative incidence estimates use the recommended method in Competing Risks: A Practical Perspective by Melania Pintilie.

$x^{exp(±z * se / (x * log(x)))}$

where $x$ is the cumulative incidence estimate, $se$ is the standard error estimate, and $z$ is the z-score associated with the confidence level of the interval, e.g. $z = 1.96$ for a 95% CI.

Examples

cuminc <- cuminc(Surv(ttdeath, death_cr) ~ trt, trial)

tidy(cuminc)

glance(cuminc)

# restructure glance to one line per outcome
glance(cuminc) %>%
  tidyr::pivot_longer(
    everything(),
    names_to = c(".value", "outcome_id"),
    names_pattern = "(.*)_(.*)"
  )
cuminc <- cuminc(Surv(ttdeath, death_cr) ~ trt, trial)

tidy(cuminc)

glance(cuminc)

# restructure glance to one line per outcome
glance(cuminc) %>%
  tidyr::pivot_longer(
    everything(),
    names_to = c(".value", "outcome_id"),
    names_pattern = "(.*)_(.*)"
  )

Competing Risks Regression

Description

Competing Risks Regression

Usage

## S3 method for class 'formula'
crr(formula, data, failcode = NULL, conf.level = 0.95, ...)

crr(x, ...)

## Default S3 method:
crr(x, ...)
## S3 method for class 'formula'
crr(formula, data, failcode = NULL, conf.level = 0.95, ...)

crr(x, ...)

## Default S3 method:
crr(x, ...)

Arguments

`formula`	formula with `Surv()` on LHS and covariates on RHS. The event status variable must be a factor, with the first level indicating 'censor' and subsequent levels the competing risks. The `Surv(time2=)` argument cannot be used.
`data`	data frame
`failcode`	Indicates event of interest. If `⁠failcode=⁠` is `NULL`, the first competing event will be used as the event of interest. Default is `NULL`.
`conf.level`	confidence level. Default is 0.95.
`...`	passed to methods
`x`	input object

Value

tidycrr object

Examples

crr(Surv(ttdeath, death_cr) ~ age + grade, trial)
crr(Surv(ttdeath, death_cr) ~ age + grade, trial)

Competing Risks Cumulative Incidence

Description

Competing Risks Cumulative Incidence

Usage

## S3 method for class 'formula'
cuminc(formula, data, strata, rho = 0, conf.level = 0.95, ...)

cuminc(x, ...)

## Default S3 method:
cuminc(x, ...)
## S3 method for class 'formula'
cuminc(formula, data, strata, rho = 0, conf.level = 0.95, ...)

cuminc(x, ...)

## Default S3 method:
cuminc(x, ...)

Arguments

`formula`	formula with `Surv()` on LHS and covariates on RHS. The event status variable must be a factor, with the first level indicating 'censor' and subsequent levels the competing risks. The `Surv(time2=)` argument cannot be used.
`data`	data frame
`strata`	stratification variable. Has no effect on estimates. Tests will be stratified on this variable. (all data in 1 stratum, if missing)
`rho`	Power of the weight function used in the tests.
`conf.level`	confidence level. Default is 0.95.
`...`	passed to methods
`x`	input object

Value

tidycuminc object

Confidence intervals

The confidence intervals for cumulative incidence estimates use the recommended method in Competing Risks: A Practical Perspective by Melania Pintilie.

$x^{exp(±z * se / (x * log(x)))}$

where $x$ is the cumulative incidence estimate, $se$ is the standard error estimate, and $z$ is the z-score associated with the confidence level of the interval, e.g. $z = 1.96$ for a 95% CI.

p-values

Examples

# calculate risk for entire cohort -----------
cuminc(Surv(ttdeath, death_cr) ~ 1, trial)

# calculate risk by treatment group ----------
cuminc(Surv(ttdeath, death_cr) ~ trt, trial)
# calculate risk for entire cohort -----------
cuminc(Surv(ttdeath, death_cr) ~ 1, trial)

# calculate risk by treatment group ----------
cuminc(Surv(ttdeath, death_cr) ~ trt, trial)

gtsummary methods

Description

These functions are S3 methods for working with crr() model results.

tbl_regression.tidycrr(): This function sets the tidycmprsk tidier for crr() models.
global_pvalue_fun.tidycrr(): This function ensures that gtsummary::add_global_p(anova_fun) uses the Wald test by default (instead of car::Anova(), which does not support this model type). The Wald test is executed with cardx::ard_aod_wald_test(), which wraps aod::wald.test().

Usage

## S3 method for class 'tidycrr'
tbl_regression(x, tidy_fun = tidycmprsk::tidy, ...)

## S3 method for class 'tidycrr'
global_pvalue_fun(x, type, ...)
## S3 method for class 'tidycrr'
tbl_regression(x, tidy_fun = tidycmprsk::tidy, ...)

## S3 method for class 'tidycrr'
global_pvalue_fun(x, type, ...)

Arguments

`x`	(`tidycrr`) `tidycmprsk::crr()` regression object
`tidy_fun`	(`function`) Tidier function for the model. Default is `tidycmprsk::tidy()`.
`...`	Additional arguments passed to `broom.helpers::tidy_plus_plus()`.
`type`	not used

Value

gtsummary table or data frame of results

Examples

crr(Surv(ttdeath, death_cr) ~ age + grade, trial) |>
  gtsummary::tbl_regression() |>
  gtsummary::add_global_p() |>
  gtsummary::as_gt()
crr(Surv(ttdeath, death_cr) ~ age + grade, trial) |>
  gtsummary::tbl_regression() |>
  gtsummary::add_global_p() |>
  gtsummary::as_gt()

Estimate subdistribution functions for crr objects

Description

Estimate subdistribution functions for crr objects

Usage

## S3 method for class 'tidycrr'
predict(object, times = NULL, probs = NULL, newdata = NULL, ...)
## S3 method for class 'tidycrr'
predict(object, times = NULL, probs = NULL, newdata = NULL, ...)

Arguments

`object`	a tidycrr object
`times`	Numeric vector of times to obtain risk estimates at
`probs`	Numeric vector of quantiles to obtain estimates at
`newdata`	A `base::data.frame()` or `tibble::tibble()` containing all the original predictors used to create x. Defaults to `NULL`.
`...`	not used

Value

named list of prediction estimates

Examples

crr(Surv(ttdeath, death_cr) ~ age, trial) %>%
  predict(times = 12, newdata = trial[1:10, ])
crr(Surv(ttdeath, death_cr) ~ age, trial) %>%
  predict(times = 12, newdata = trial[1:10, ])

Tabular Summary of Cumulative Incidence

Description

Tabular Summary of Cumulative Incidence

Usage

## S3 method for class 'tidycuminc'
tbl_cuminc(
  x,
  times = NULL,
  outcomes = NULL,
  statistic = "{estimate}% ({conf.low}%, {conf.high}%)",
  label = NULL,
  label_header = "**Time {time}**",
  estimate_fun = NULL,
  conf.level = x$conf.level,
  missing = NULL,
  ...
)

tbl_cuminc(x, ...)
## S3 method for class 'tidycuminc'
tbl_cuminc(
  x,
  times = NULL,
  outcomes = NULL,
  statistic = "{estimate}% ({conf.low}%, {conf.high}%)",
  label = NULL,
  label_header = "**Time {time}**",
  estimate_fun = NULL,
  conf.level = x$conf.level,
  missing = NULL,
  ...
)

tbl_cuminc(x, ...)

Arguments

`x`	a 'tidycuminc' object created with `cuminc()`
`times`	Numeric vector of times to obtain risk estimates at
`outcomes`	character vector of outcomes to include. Default is to include the first outcome.
`statistic`	string of statistic to report. Default is `"{estimate}% ({conf.low}%, {conf.high}%)"`
`label`	string indicating the variable label
`label_header`	string for the header labels; uses glue syntax. Default is `"Time {time}"`
`estimate_fun`	function that styles and formats the statistics. Default is `~gtsummary::style_sigfig(.x, scale = 100)`
`conf.level`	Level of the confidence interval. Default matches that in `cuminc(conf.level=)` (typically, 0.95)
`missing`	string to replace missing values with. Default is an em-dash, `"\U2014"`
`...`	not used

Example Output

Example 1

Example 2

Examples

# Example 1 ----------------------------------
tbl_cuminc_ex1 <-
  cuminc(Surv(ttdeath, death_cr) ~ 1, trial) %>%
  tbl_cuminc(times = c(12, 24), label_header = "**Month {time}**")

# Example 2 ----------------------------------
tbl_cuminc_ex2 <-
  cuminc(Surv(ttdeath, death_cr) ~ trt, trial) %>%
  tbl_cuminc(times = c(12, 24),
             outcomes = c("death from cancer", "death other causes"),
             label_header = "**Month {time}**")

# Example 1 ----------------------------------
tbl_cuminc_ex1 <-
  cuminc(Surv(ttdeath, death_cr) ~ 1, trial) %>%
  tbl_cuminc(times = c(12, 24), label_header = "**Month {time}**")

# Example 2 ----------------------------------
tbl_cuminc_ex2 <-
  cuminc(Surv(ttdeath, death_cr) ~ trt, trial) %>%
  tbl_cuminc(times = c(12, 24),
             outcomes = c("death from cancer", "death other causes"),
             label_header = "**Month {time}**")

Results from a simulated study of two chemotherapy agents

Description

A dataset containing the baseline characteristics of 200 patients who received Drug A or Drug B. Dataset also contains the outcome of tumor response to the treatment.

Usage

trial
trial

Format

A data frame with 200 rows–one row per patient

trt: Chemotherapy Treatment
age: Age
marker: Marker Level (ng/mL)
stage: T Stage
grade: Grade
response: Tumor Response
death: Patient Died
death_cr: Death Status
ttdeath: Months to Death/Censor

Package 'tidycmprsk'

Help Index

Additional Functions for tbl_cuminc()

Description

Usage

Arguments

Example Output

p-values

See Also

Examples

Functions for tidycrr objects

Description

Usage

Arguments

Value

Examples

Functions for tidycuminc objects

Description

Usage

Arguments

Value

Examples

Broom methods for tidycrr objects

Description

Usage

Arguments

Value

See Also

Examples

Broom methods for tidy cuminc objects

Description

Usage

Arguments

Value

tidy() data frame

p-values

Confidence intervals

See Also

Examples

Competing Risks Regression

Description

Usage

Arguments

Value

See Also

Examples

Competing Risks Cumulative Incidence

Description

Usage

Arguments

Value

Confidence intervals

p-values

See Also

Examples

gtsummary methods

Description

Usage

Arguments

Value

Examples

Estimate subdistribution functions for crr objects

Description

Usage

Arguments

Value

See Also

Examples

Tabular Summary of Cumulative Incidence

Description

Usage

Arguments

Example Output

See Also

Examples

Results from a simulated study of two chemotherapy agents

Description

Usage

Format

Additional Functions for `tbl_cuminc()`

`tidy()` data frame