Help for package epitabulate

Title:

Tables for Epidemiological Analysis

Version:

0.1.0

Description:

Produces tables for descriptive epidemiological analysis. These tables include attack rates, case fatality ratios, and mortality rates (with appropriate confidence intervals), with additional functionality to calculate Mantel-Haenszel odds, risk, and incidence rate ratios. The methods implemented follow standard epidemiological approaches described in Rothman et al. (2008, ISBN:978-0-19-513554-2). This package is part of the 'R4EPIs' project https://R4EPI.github.io/sitrep/.

License:

GPL-3

URL:

https://R4EPI.github.io/epitabulate/, https://github.com/R4EPI/epitabulate/

BugReports:

https://github.com/R4EPI/epitabulate/issues

Imports:

binom, dplyr (≥ 1.0.2), epikit (≥ 0.1.2), forcats, glue, gtsummary, MASS, purrr, rlang (≥ 0.4.0), scales, stats, tibble (≥ 3.0.0), tidyr (≥ 1.0.0), tidyselect (≥ 1.0.0)

Suggests:

broom.helpers, cardx, covr, matchmaker (≥ 0.1.0), testthat

Encoding:

UTF-8

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-11-10 09:59:54 UTC; spina

Author:

Alexander Spina

[aut, cre], Zhian N. Kamvar

[aut], Amy Gimma [aut], Kate Doyle [ctb], Applied Epi Incorporated [cph], Medecins Sans Frontieres Operational Centre Amsterdam [fnd]

Maintainer:

Alexander Spina <aspina@appliedepi.org>

Repository:

CRAN

Date/Publication:

2025-11-13 18:50:02 UTC

Add attack rate statistics to a gtsummary table

Description

This function wraps gtsummary::add_stat() to calculate and display attack rates (cases per given population multiplier) with 95% confidence intervals, using the epitabulate::attack_rate() function internally.

Usage

add_ar(
  gts_object,
  case_var,
  population = NULL,
  multiplier = 10^4,
  drop_tblsummary_stat = FALSE
)

Arguments

gts_object

A gtsummary object created with functions such as gtsummary::tbl_summary()

case_var

A logical variable name in the data indicating case status (e.g. TRUE for cases).

population

Optional numeric vector giving the population size for the denominator. If NULL, the population is inferred from the data.

multiplier

Numeric multiplier used to scale the attack rate (e.g. 1 = proportion, 100 = percent, 10^4 = per 10,000).

drop_tblsummary_stat

Logical; if TRUE, removes the original tbl_summary statistic column (default = FALSE).

Value

A modified gtsummary object with additional columns showing the number of cases, population, attack rate, and 95% confidence interval.

Add case fatality rate (CFR) statistics to a gtsummary table

Description

This function wraps gtsummary::add_stat() to calculate and display case fatality rates (deaths among cases) with 95% confidence intervals, using the epitabulate::case_fatality_rate_df() function internally.

Usage

add_cfr(gts_object, deaths_var)

Arguments

gts_object

A gtsummary object created with functions such as gtsummary::tbl_summary() or gtsummary::tbl_cross().

deaths_var

A logical variable name in the data indicating death status (e.g. TRUE for death).

Value

A modified gtsummary object with additional columns showing the number of deaths, number of cases, case fatality rate, and 95% confidence interval.

A {gtsummary} wrapper function that takes a gtsummary univariate regression table and adds appropriate cross tabs by exposure and outcome

Description

A {gtsummary} wrapper function that takes a gtsummary univariate regression table and adds appropriate cross tabs by exposure and outcome

Usage

add_crosstabs(x, wide = FALSE)

Arguments

x

Object with class tbl_uvregression from the gtsummary tbl_uvregression function or tbl_cmh from the epitabulate tbl_cmh function.

wide

TRUE/FALSE to specify whether would like to have the output in wide format. Results in four columns rather than two, but in a single row. This is only works for dichotomous variables (yes/no, TRUE/FALSE, male/female), others will be dropped with a warning message. (Default is FALSE)

Value

A modified gtsummary table object (same class as input — e.g. "tbl_uvregression" or "tbl_cmh") containing additional cross-tabulated counts of outcomes and exposures. The structure depends on regression type:

For logistic models: adds case and control counts.
For Poisson models without offsets: adds total and case counts per exposure group (risk ratios).
For Poisson models with offsets: adds total person-time and case counts per exposure group (incidence rate ratios).
When wide = TRUE, dichotomous variables are reshaped to wide format with separate columns for exposed/unexposed counts.

References

Inspired by Daniel Sjoberg, see gtsummary github repo

Add mortality rate statistics to a gtsummary table

Description

This function wraps gtsummary::add_stat() to calculate and display mortality rates (deaths per given population multiplier) with 95% confidence intervals, using the epitabulate::mortality_rate() function internally.

Usage

add_mr(
  gts_object,
  deaths_var,
  population = NULL,
  multiplier = 10^4,
  drop_tblsummary_stat = FALSE
)

Arguments

gts_object

A gtsummary object created with functions such as gtsummary::tbl_summary() or gtsummary::tbl_cross().

deaths_var

A logical variable name in the data indicating death status (e.g. TRUE for death).

population

Optional numeric vector giving the population size for the denominator. If NULL, the population is inferred from the data.

multiplier

Numeric multiplier used to scale the mortality rate (e.g. 1 = proportion, 100 = percent, 10^4 = per 10,000).

drop_tblsummary_stat

Logical; if TRUE, removes the original tbl_summary statistic column (default = FALSE).

Value

A modified gtsummary object with additional columns showing the number of deaths, population, mortality rate, and 95% confidence interval.

Rates and Ratios

Description

Calculate attack rate, case fatality rate, and mortality rate

Usage

attack_rate(
  cases,
  population,
  conf_level = 0.95,
  multiplier = 100,
  mergeCI = FALSE,
  digits = 2
)

case_fatality_rate(
  deaths,
  population,
  conf_level = 0.95,
  multiplier = 100,
  mergeCI = FALSE,
  digits = 2
)

case_fatality_rate_df(
  x,
  deaths,
  group = NULL,
  conf_level = 0.95,
  multiplier = 100,
  mergeCI = FALSE,
  digits = 2,
  add_total = FALSE
)

mortality_rate(
  deaths,
  population,
  conf_level = 0.95,
  multiplier = 10^4,
  mergeCI = FALSE,
  digits = 2
)

Arguments

cases, deaths

number of cases or deaths in a population. For ⁠_df⁠ functions, this can be the name of a logical column OR an evaluated logical expression (see examples).

population

the number of individuals in the population.

conf_level

a number representing the confidence level for which to calculate the confidence interval. Defaults to 0.95, representing a 95% confidence interval using binom::binom.wilson()

multiplier

The base by which to multiply the output:

multiplier = 1: ratio between 0 and 1
multiplier = 100: proportion
multiplier = 10^4: x per 10,000 people

mergeCI

Whether or not to put the confidence intervals in one column (default is FALSE)

digits

if mergeCI = TRUE, this determines how many digits are printed

x

a data frame

group

the bare name of a column to use for stratifying the output

add_total

if group is not NULL, then this will add a row containing the total value across all groups.

Value

a data frame with five columns that represent the numerator, denominator, rate, lower bound, and upper bound.

attack_rate(): cases, population, ar, lower, upper
case_fatality_rate(): deaths, population, cfr, lower, upper

A gtsummary wrapper function that takes a gtsummary object and removes a column from the table body by column name

Description

A gtsummary wrapper function that takes a gtsummary object and removes a column from the table body by column name

Usage

gt_remove_stat(gts_object, col_name = "stat_0")

Arguments

gts_object

A data frame, passed by the gtsummary::add_stat function

col_name

the column name from the gtsummary object's table_body to remove

Value

a gtsummary object without the named column

A {gtsummary} wrapper function that takes a dataframe and produces crude, stratified and Cochran-Mantel-Haenszel estimates.

Description

A {gtsummary} wrapper function that takes a dataframe and produces crude, stratified and Cochran-Mantel-Haenszel estimates.

Usage

tbl_cmh(
  data,
  case,
  exposure,
  strata,
  measure,
  obstime = NULL,
  conf.level = 0.95
)

Arguments

data

A data frame

case

Name of a variable as your outcome of interest

exposure

Names of variables as exposures of interest. Can be multiple variables using tidyselect syntax.

strata

Name of a variable to be used for stratifying results. This gives you a table of crude measure, measures for each strata and the mantel-haeszel adjusted measure for each exposure variable

measure

Specify what you would like to calculated, options are "OR", "RR" or "IRR". Default is "OR". If "OR or "RR" are specified then a woolf test for homogeneity p-value is produced. This tests whether there is a significant difference in the estimates between strata.

obstime

A numeric variable containing the observation time for each individual

conf.level

Confidence level for confidence intervals (default 0.95)

Value

A gtsummary table of class "tbl_cmh" (and "gtsummary", "tbl_stack") containing:

Crude estimates of association (odds ratios, risk ratios, or rate ratios)
Stratified estimates for each level of the stratification variable
Cochran–Mantel–Haenszel (CMH) adjusted estimates with 95\
Woolf test p-values for assessing homogeneity across strata (when applicable)

References

Inspired by Daniel Sjoberg, see gtsummary github repo