rifttable {rifttable}R Documentation

Results Tables for Epidemiology

Description

This function displays descriptive and inferential results for binary, continuous, and survival data in the format of a table stratified by exposure and, if requested, by effect modifiers.

This function is intended only for tabulations of final results. Model diagnostics for regression models need to be conducted separately.

Usage

rifttable(
  design,
  data,
  id = "",
  layout = "rows",
  factor = 1000,
  risk_percent = FALSE,
  risk_digits = dplyr::if_else(risk_percent == TRUE, true = 0, false = 2),
  diff_digits = 2,
  ratio_digits = 2,
  ratio_digits_decrease = c(`2.995` = -1, `9.95` = -2),
  rate_digits = 1,
  to = ", ",
  reference = "(reference)",
  type2_layout = "rows",
  overall = FALSE,
  exposure_levels = c("noempty", "nona", "all")
)

Arguments

design

Design matrix (data frame) that sets up the table. See Details. Must be provided.

data

Dataset to be used for all analyses. Must be provided unless the design was generated by table1_design.

id

Optional. Name of an id variable in the data that identifies clustered observations, for example if the data are in a long format with rows encoding time-varying covariates. See documentation for which estimators use this information. Defaults to "", i.e., each row is a unique individual.

layout

Optional. "rows" uses the design as rows and exposure categories as columns. "cols" is the opposite: design as columns and exposure categories as rows. Defaults to "rows".

factor

Optional. Used for type = "rates": Factor to multiply events per person-time by. Defaults to 1000.

risk_percent

Optional. Show risk and risk difference estimates in percentage points instead of proportions. Defaults to FALSE unless the design was generated by table1_design. In this latter case, if risk_percent is not provided, it will default to TRUE.

risk_digits

Optional. Number of decimal digits to show for risks/ cumulative incidence. Defaults to 2 for risk_percent = FALSE and to 0 for risk_percent = TRUE. Alternatively, digits can be specified directly for each row of the design.

diff_digits

Optional. Number of decimal digits to show for rounding of means and mean difference estimates. Defaults to 2. Alternatively, digits can be specified directly for each row of the design.

ratio_digits

Optional. Number of decimal digits to show for ratio estimates. Defaults to 2. Alternatively, digits can be specified directly for each row of the design.

ratio_digits_decrease

Optional. Lower limits of ratios above which fewer digits should be shown. Provide a named vector of the format, c(`3` = -1, `10` = -2) to reduce the number of rounding digits by 1 digit for ratios greater than 3 and by 2 digits for ratios greater than 10 (the default). To disable, set to NULL.

rate_digits

Optional. Number of decimal digits to show for rates. Defaults to 1. Alternatively, digits can be specified directly for each row of the design.

to

Optional. Separator between the lower and the upper bound of the 95% confidence interval (and interquartile range for medians). Defaults to ", ".

reference

Optional. Defaults to "(reference)". Alternative label for the reference category.

type2_layout

Optional. If a second estimate is requested via type2 in the design matrix, display it as rows below ("rows") or as columns ("columns") to the right. Defaults to "rows".

overall

Optional. Defaults to FALSE. Add a first column with unstratified estimates to an exposure-stratified table? Elements will be shown only for absolute estimates (e.g., type = "mean") and blank for comparative estimates (e.g., mean difference via type = "diff").

exposure_levels

Optional. Defaults to "noempty". Show only exposure levels that exist in the data or are NA ("noempty"); show only exposure levels that are neither NA nor empty ("nona"); or show all exposure levels even if they are NA or a factor level that does not occur in the data ("all").

Details

The main input parameter is the dataset design. Always required are the column type (the type of requested statistic, see below), as well as outcome for binary outcomes or time and event for survival outcomes:

Use tibble, tribble, and mutate to construct the design dataset, especially variables that are used repeatedly (e.g., exposure, time, event, or outcome). See examples.

If regression models cannot provide estimates in a stratum, e.g., because there are no events, then "--" will be printed. Accompanying warnings need to be suppressed manually, if appropriate, using suppressWarnings(rifttable(...)).

Value

Tibble. Get formatted output as a gt table by passing on to rt_gt.

References

Greenland S, Rothman KJ (2008). Introduction to Categorical Statistics. In: Rothman KJ, Greenland S, Lash TL. Modern Epidemiology, 3rd edition. Philadelpha, PA: Lippincott Williams & Wilkins. Page 242. (Poisson/large-sample approximation for variance of incidence rates)

Examples

# Load 'cancer' dataset from survival package (Used in all examples)
data(cancer, package = "survival")

# The exposure (here, 'sex') must be categorical
cancer <- cancer |>
  tibble::as_tibble() |>
  dplyr::mutate(
    sex = factor(
      sex,
      levels = 1:2,
      labels = c("Male", "Female")
    ),
    time = time / 365.25,
    status = status - 1
  )


# Example 1: Binary outcomes (use 'outcome' variable)
# Set table design
design1 <- tibble::tibble(
  label = c(
    "Outcomes",
    "Total",
    "Outcomes/Total",
    "Risk",
    "Risk (CI)",
    "Outcomes (Risk)",
    "Outcomes/Total (Risk)",
    "RR",
    "RD"
  )
) |>
  dplyr::mutate(
    type = label,
    exposure = "sex",
    outcome = "status"
  )

# Generate rifttable
rifttable(
  design = design1,
  data = cancer
)

# Use 'design' as columns (selecting RR and RD only)
rifttable(
  design = design1 |>
    dplyr::filter(label %in% c("RR", "RD")),
  data = cancer,
  layout = "cols"
)


# Example 2: Survival outcomes (use 'time' and 'event'),
#   with an effect modifier and a confounder
# Set table design
design2 <- tibble::tribble(
  # Elements that vary by row:
  ~label,                       ~stratum, ~confounders, ~type,
  "**Overall**",                NULL,     "",           "blank",
  "  Events",                   NULL,     "",           "events",
  "  Person-years",             NULL,     "",           "time",
  "  Rate/1000 py (95% CI)",    NULL,     "",           "rate (ci)",
  "  Unadjusted HR (95% CI)",   NULL,     "",           "hr",
  "  Age-adjusted HR (95% CI)", NULL,     "+ age",      "hr",
  "",                           NULL,     "",           "blank",
  "**Stratified models**",      NULL,     "",           "",
  "*ECOG PS1* (events/N)",      1,        "",           "events/total",
  "  Unadjusted",               1,        "",           "hr",
  "  Age-adjusted",             1,        "+ age",      "hr",
  "*ECOG PS2* (events/N)",      2,        "",           "events/total",
  "  Unadjusted",               2,        "",           "hr",
  "  Age-adjusted",             2,        "+ age",      "hr",
  "",                           NULL,     "",           "",
  "**Joint model**, age-adj.",  NULL,     "",           "",
  "  ECOG PS1",                 1,        "+ age",      "hr_joint",
  "  ECOG PS2",                 2,        "+ age",      "hr_joint"
) |>
  # Elements that are the same for all rows:
  dplyr::mutate(
    exposure = "sex",
    event = "status",
    time = "time",
    effect_modifier = "ph.ecog"
  )

# Generate rifttable
rifttable(
  design = design2,
  data = cancer |>
    dplyr::filter(ph.ecog %in% 1:2)
)


# Example 3: Get two estimates using 'type' and 'type2'
design3 <- tibble::tribble(
  ~label,     ~stratum, ~type,          ~type2,
  "ECOG PS1", 1,        "events/total", "hr",
  "ECOG PS2", 2,        "events/total", "hr"
) |>
  dplyr::mutate(
    exposure = "sex",
    event = "status",
    time = "time",
    confounders = "+ age",
    effect_modifier = "ph.ecog"
  )

rifttable(
  design = design3,
  data = cancer |>
    dplyr::filter(ph.ecog %in% 1:2)
)

rifttable(
  design = design3,
  data = cancer |>
    dplyr::filter(ph.ecog %in% 1:2),
  layout = "cols",
  type2_layout = "cols"
)


# Example 4: Continuous outcomes (use 'outcome' variable);
# request rounding to 1 decimal digit in some cases;
# add continuous trend (slope per one unit of the 'trend' variable)
tibble::tribble(
  ~label,                   ~stratum, ~type,        ~digits,
  "Marginal mean (95% CI)", NULL,     "mean (ci)",  1,
  "  Male",                 "Male",   "mean",       NA,
  "  Female",               "Female", "mean",       NA,
  "",                       NULL,     "",           NA,
  "Stratified model",       NULL,     "",           NA,
  "  Male",                 "Male",   "diff",       1,
  "  Female",               "Female", "diff",       1,
  "",                       NULL,     "",           NA,
  "Joint model",            NULL,     "",           NA,
  "  Male",                 "Male",   "diff_joint", NA,
  "  Female",               "Female", "diff_joint", NA
) |>
  dplyr::mutate(
    exposure = "ph.ecog_factor",
    trend = "ph.ecog",
    outcome = "age",
    effect_modifier = "sex"
  ) |>
  rifttable(
    data = cancer |>
      dplyr::filter(ph.ecog < 3) |>
      dplyr::mutate(ph.ecog_factor = factor(ph.ecog))
  )


# Example 5: Get formatted output for Example 2
rifttable(
  design = design2,
  data = cancer |>
    dplyr::filter(ph.ecog %in% 1:2)
) |>
  rt_gt()


[Package rifttable version 0.7.1 Index]