R/tbl_hierarchical_incidence_rate.R
tbl_hierarchical_incidence_rate.RdA wrapper function for gtsummary::tbl_hierarchical() to calculate
exposure-adjusted incidence rates of adverse events (or other clinical
events) across a hierarchy.
The function calculates the incidence rate per specified person-time
dynamically. For subjects experiencing an event, Person-Years is calculated
from start_date to event_date. For subjects without an event, it is
calculated from start_date to end_date.
tbl_hierarchical_incidence_rate(
data,
denominator,
variables,
by = NULL,
id = "USUBJID",
start_date = "TRTSDT",
end_date = "TRTEDT",
event_date = "AESTDTC",
event_type = c("first_event", "all"),
n_person_time = 100,
unit_label = "years",
conf.level = 0.95,
conf.type = "normal",
digits = 2,
overall_row = TRUE,
spanning_label = "{level} \n(N = {n})",
label = NULL
)
# S3 method for class 'tbl_hierarchical_incidence_rate'
add_overall(
x,
last = FALSE,
col_label = "All Participants \n(N = {style_roche_number(N)})",
...
)(data.frame)
a data frame.
(data.frame, integer)
used to define the denominator and enhance the output.
The argument is required for tbl_hierarchical() and optional for tbl_hierarchical_count().
The denominator argument must be specified when id is used to calculate event rates.
(tidy-select)
A character vector or tidy-selector of hierarchical columns in data
(e.g., system organ class and preferred term).
(tidy-select)
A single column name in data to stratify the summary table by
(e.g., treatment arm).
(tidy-select)
argument used to subset data to identify rows in data to calculate
event rates in tbl_hierarchical().
(tidy-select)
A column name in denominator specifying the treatment start date.
(tidy-select)
A column name in denominator specifying the treatment end date or
follow-up cutoff.
(tidy-select)
A column name in data specifying the onset date of the event.
(string)
Type of the events to be counted. Can be "first_event" or "all".
Default is "first_event".
(numeric(1))
A numeric scalar multiplier to scale the incidence rate. Defaults to 100.
(string)
Label for the unit of estimated person-time output. Defaults to "years".
Known abbreviations ("years", "months", "weeks", "days") are parsed into
standard acronyms (e.g., "PY"). Custom strings will be formatted to
Title Case and prefixed with "Person-" (e.g., "decades" becomes
"Person-Decades").
(numeric(1))
Confidence level for the calculated interval. Default is 0.95. Passed
directly to cardx::ard_incidence_rate().
(string)
Confidence interval type. Default is "normal". Passed directly to
cardx::ard_incidence_rate().
(numeric(1))
An integer specifying the number of decimal places to round the incidence
estimates, confidence intervals, and person-years to. Defaults to 2.
(logical(1))
Whether to include an overall summary row aggregating across all
hierarchical levels. Default is TRUE. The overall row label can be
customized via label = list("..ard_hierarchical_overall.." = "Custom Label").
(string)
A glue-style template for the per-arm spanning headers when
by is supplied. Available substitutions are {level} (the arm level) and
{n} (the arm participant count). Default is "{level} \\n(N = {n})",
matching the column-header convention used elsewhere in the package.
(formula-list-selector)
used to override default labels in hierarchical table, e.g. list(AESOC = "System Organ Class").
The default for each variable is the column label attribute, attr(., 'label').
If no label has been set, the column name is used.
(tbl_hierarchical_incidence_rate)
A table created with tbl_hierarchical_incidence_rate().
(logical(1))
When add_overall() is used, whether to place the overall columns after
(TRUE) or before (FALSE) the stratified columns. Default is FALSE.
(string)
A glue-style template for the overall spanning header added by
add_overall(). Resolved against the column header context (e.g. {N},
{n}). Default is "All Participants \\n(N = {style_roche_number(N)})".
These dots are for future extensions and must be empty.
a gtsummary table of class "tbl_hierarchical_incidence_rate".
# Dummy denominator dataset with treatment start and end dates
adsl <- data.frame(
USUBJID = paste0("PT", sprintf("%02d", 1:5)),
ARM = c("Treatment", "Treatment", "Placebo", "Placebo", "Placebo"),
TRTSDT = as.Date(rep("2023-01-01", 5)),
TRTEDT = as.Date(c(
"2023-12-31", "2023-06-30", "2023-12-31", "2023-08-15", "2023-10-31"
))
)
# Dummy AE dataset with onset dates (subset to first occurrences)
adae <- data.frame(
USUBJID = c("PT02", "PT05", "PT05"),
AESOC = c("Cardiac", "Nervous", "Cardiac"),
ARM = c("Treatment", "Placebo", "Placebo"),
AEDECOD = c("Tachycardia", "Headache", "Palpitations"),
AESTDTC = c("2023-04-15", "2023-09-10", "2023-10-01")
)
# Build the hierarchical incidence rate table
tbl_hierarchical_incidence_rate(
data = adae,
denominator = adsl,
variables = c(AESOC, AEDECOD),
by = ARM,
start_date = TRTSDT,
end_date = TRTEDT,
event_date = AESTDTC,
n_person_time = 100,
unit_label = "years",
label = list(
AESOC = "MedDRA System Organ Class",
AEDECOD = "MedDRA Preferred Term",
"..ard_hierarchical_overall.." = "All Adverse Events"
)
)
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
# Custom overall row label
tbl_hierarchical_incidence_rate(
data = adae,
denominator = adsl,
variables = c(AESOC, AEDECOD),
by = ARM,
start_date = TRTSDT,
end_date = TRTEDT,
event_date = AESTDTC,
label = list("..ard_hierarchical_overall.." = "Any Adverse Event")
)
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
# Without the overall row
tbl_hierarchical_incidence_rate(
data = adae,
denominator = adsl,
variables = c(AESOC, AEDECOD),
by = ARM,
start_date = TRTSDT,
end_date = TRTEDT,
event_date = AESTDTC,
overall_row = FALSE
)
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
# Add an unstratified "Overall" column pooling all treatment arms
tbl_hierarchical_incidence_rate(
data = adae,
denominator = adsl,
variables = c(AESOC, AEDECOD),
by = ARM,
start_date = TRTSDT,
end_date = TRTEDT,
event_date = AESTDTC
) |>
add_overall()
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
# Customize the per-arm spanning headers with a glue template
tbl_hierarchical_incidence_rate(
data = adae,
denominator = adsl,
variables = c(AESOC, AEDECOD),
by = ARM,
start_date = TRTSDT,
end_date = TRTEDT,
event_date = AESTDTC,
spanning_label = "{level} (N = {n})"
)
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI
No. of
Participants
with AE (%)
No. of
AEs
PY
AE Rate
per
100 PY
95% CI