Package 'gtregression'

Access fields on gtregression objects with '$'

Description

Works for any object from this package, since they all carry class '"gtregression"'. Returns NULL (quietly) if the field is not present.

Usage

## S3 method for class 'gtregression'
x$name

Arguments

x	A gtregression object.
name	Field name to access.

Details

Common fields: - table, table_display, table_body - models, model_summaries, reg_check - approach, format (or engine), source - parts, spanners (for merged tables) - by, levels (for descriptive tables)

---

Check collinearity using VIF for fitted models

Description

Computes Variance Inflation Factors (VIF) for fitted multivariable models returned by multi_reg() or related functions.

Usage

check_collinearity(model, format = c("flextable", "gt", "tibble"))

Arguments

model	A fitted model object returned by multi_reg(), stratified_multi_reg(), or compatible gtregression functions. Univariable model objects are rejected because VIF is not applicable.
format	Output format. One of "flextable" (default), "gt", or "tibble". Use format = "tibble" to preserve the original tibble or nested-list output.

Details

If the car package is installed, check_collinearity() uses car::vif(). Otherwise, it computes VIF/GVIF from the fitted model matrix so that diagnostics remain available without an additional dependency.

Value

For multivariable models, a tibble if a single fitted model is present, or a named list of tibbles if multiple fitted models are present. With format = "gt" or format = "flextable", leaf tibbles are converted to formatted tables while preserving any list nesting. The tibble contains:

Variable

Model term.

VIF

Variance inflation factor. For multi-degree-of-freedom terms, this is the adjusted GVIF: GVIF^(1 / (2 * Df)).

Interpretation

Simple interpretation based on common cut points: no collinearity, moderate, or high.

For univariate models, an error is raised indicating that VIF is not applicable.

---

Check Convergence for a Regression Model

Description

Assesses model convergence and provides diagnostics for each exposure (in univariate mode) or for the full model (in multivariable mode), depending on the regression approach used.

Usage

check_convergence(
  data,
  exposures,
  outcome,
  approach = "logit",
  multivariate = FALSE,
  format = c("flextable", "gt", "tibble")
)

Arguments

data	A data frame containing the dataset.
exposures	A character vector of predictor variable names. Quoted names are recommended in scripts, and bare names are also accepted. If multivariate = FALSE, each exposure is assessed separately. If multivariate = TRUE, exposures are included together.
outcome	A character string specifying the outcome variable. Quoted and bare names are accepted.
approach	A character string specifying the regression approach. One of: "logit", "logbinomial", "poisson", "robpoisson", or "negbin".
multivariate	Logical. If TRUE, checks convergence for a multivariable model; otherwise, performs checks for each univariate model.
format	Output format. One of "flextable" (default), "gt", or "tibble". Use format = "tibble" for the original data-frame style output.

Details

For robpoisson, predicted probabilities (fitted values) may exceed 1, which is acceptable when estimating risk ratios but should not be interpreted as actual probabilities.

This function is useful for identifying convergence issues, especially for "logbinomial" models, which often fail to converge.

Value

A data frame, gt_tbl, or flextable summarizing convergence diagnostics, including:

Exposure

Name of the exposure variable.

Model

The regression approach used.

Converged

TRUE if the model converged successfully; FALSE otherwise.

Max.prob.

Maximum predicted probability or fitted value in the dataset.

See Also

[identify_confounder()], [interaction_models()]

Examples

if (requireNamespace("gtregression", quietly = TRUE)) {
  data(data_PimaIndiansDiabetes, package = "gtregression")

  check_convergence(
    data = data_PimaIndiansDiabetes,
    exposures = c("age", "mass"),
    outcome = "diabetes",
    approach = "logit"
  )

  check_convergence(
    data = data_PimaIndiansDiabetes,
    exposures = c("age", "mass"),
    outcome = "diabetes",
    approach = "logit",
    multivariate = TRUE
  )
}

---

Birth Weight Data

Description

A dataset from the MASS package containing risk factors associated with low birth weight (LBW) in newborns. Originally collected at Baystate Medical Center, Springfield, Massachusetts, USA.

Usage

data_birthwt

Format

A data frame with 189 observations and 10 variables:

low

Indicator for birth weight < 2500g (binary): 0 = normal, 1 = low birth weight

age

Mother's age in years (numeric)

lwt

Mother's weight in pounds at last menstrual period (numeric)

race

Mother's race (factor): 1 = White, 2 = Black, 3 = Other

smoke

Smoking status during pregnancy (binary): 0 = No, 1 = Yes

ptl

Number of previous premature labors (integer)

ht

History of hypertension (binary): 0 = No, 1 = Yes

ui

Presence of uterine irritability (binary): 0 = No, 1 = Yes

ftv

no of physician visits during the 1st trimester (integer, 0–6)

bwt

Birth weight in grams (numeric)

Details

The outcome variable is binary ('low'): birth weight < 2500g (yes = 1) or not (no = 0).

Source

Hosmer, D.W., Lemeshow, S. (1989). *Applied Logistic Regression.* New York: Wiley. Also available in MASS and described in detail in its documentation.

---

Epilepsy Treatment and Seizure Counts

Description

RCT on the effect of a drug on the seizures in patients with epilepsy. Contains repeated measures data with treatment groups, baseline seizure counts, and follow-up counts.

Usage

data_epilepsy

Format

A data frame with 236 observations and 9 variables:

y

Number of seizures in a 2-week period (count)

trt

Treatment group (factor): placebo or progabide

base

Seizure count during baseline period (numeric)

age

Age of patient (numeric)

V4

Indicator for 4th visit (binary)

subject

Patient ID (factor)

period

Follow-up period number (integer)

lbase

Log of baseline seizures (numeric)

lage

Log of age (numeric)

Source

MASS package. Original data from Thall and Vail (1990)

---

Student Absenteeism in Rural Schools

Description

This dataset contains observations on the number of days absent from school for children in rural Australia, along with student characteristics. It's commonly used to demonstrate count models such as Poisson and Negative Binomial regression.

Usage

data_gt_quin

Format

A data frame with 146 observations and 5 variables:

Eth

Ethnicity ("A" = Aboriginal, "N" = Non-Aboriginal)

Sex

Sex ("F" or "M")

Age

Age group ("F0", "F1", "F2", "F3")

Lrn

Learner status ("AL" = average learner, "SL" = slow learner)

Days

Number of days absent from school (count outcome)

Source

MASS package. See also Venables and Ripley (2002), *Modern Applied Statistics with S*.

---

Infertility Matched Case-Control Study

Description

investigating the relationship between infertility and abortions.

Usage

data_infertility

Format

A data frame with 248 observations and 8 variables:

education

Education level (0 = 0–5 years, 1 = 6–11 years, 2 = 12+ years)

age

Age in years

parity

Number of prior pregnancies

induced

Number of induced abortions

case

Infertility case status (1 = case, 0 = control)

spontaneous

Number of spontaneous abortions

stratum

Matched set ID

pooled.stratum

Pooled stratum ID used for conditional regression

Source

https://stat.ethz.ch/R-manual/R-devel/library/datasets/html/infert.html

---

Lung Cancer Trial Data

Description

Survival data from a clinical trial of lung cancer patients conducted by the Veteran's Administration.

Usage

data_lungcancer

Format

A data frame with 137 observations and 8 variables:

trt

Treatment group (1 = standard, 2 = test)

celltype

Cell type (squamous, smallcell, adeno, large)

time

Survival time (in days)

status

Censoring status (1 = died, 0 = censored)

karno

Karnofsky performance score (higher = better)

diagtime

Months from diagnosis to randomization

age

Age in years

prior

Prior therapy (0 = no, 10 = yes)

Source

https://CRAN.R-project.org/package=survival

References

Kalbfleisch JD and Prentice RL (1980). The Statistical Analysis of Failure Time Data.

---

PimaIndians2 Diabetes Dataset

Description

A cleaned version of the original Pima Indians Diabetes dataset from the 'mlbench' package. Useful for demonstrating regression approaches for binary outcomes.

Usage

data_PimaIndiansDiabetes

Format

A data frame with 768 observations and 9 variables:

pregnant

Number of times pregnant

glucose

Plasma glucose concentration (glucose tolerance test)

pressure

Diastolic blood pressure (mm Hg)

triceps

Triceps skin fold thickness (mm)

insulin

2-Hour serum insulin (mu U/ml)

mass

Body mass index (BMI)

pedigree

Diabetes pedigree function

age

Age in years

diabetes

Factor indicating diabetes status (pos/neg)

Source

https://www.openml.org/d/37

---

Descriptive Summary Table (no gtsummary) using gt/flextable

Description

Publication-ready summary of categorical and continuous variables (optionally stratified). Mimics the OG gtsummary style: * column headers include N, e.g. "Overall, N=200" * categorical rows shown as n (%) * continuous rows default to Median (IQR) (footnote reflects summary)

Usage

descriptive_table(
  data,
  exposures,
  by = NULL,
  percent = c("column", "row"),
  digits = 1,
  show_missing = c("ifany", "no"),
  show_dichotomous = c("all_levels", "single_row"),
  show_overall = c("no", "first", "last"),
  statistic = NULL,
  value = NULL,
  format = c("flextable", "gt"),
  theme = c("minimal")
)

Arguments

data	data.frame
exposures	Character vector of variables to summarise. Quoted names are recommended in scripts, and bare names are also accepted.
by	Optional single grouping variable. Quoted and bare names are accepted.
percent	"column" (default) or "row"; aliases like "col"/"rows" accepted
digits	integer; decimals for % and continuous stats (default 1)
show_missing	"ifany" (default) or "no"
show_dichotomous	"all_levels" (default) or "single_row"
show_overall	"no" (default), "first", or "last"
statistic	optional named vector per continuous var: values in "mean","median","mode","count" (default is "median" = Median (IQR))
value	optional named list for single-row binaries (e.g., list(sex="Female")); formula entries like list(sex ~ "Female") are also accepted
format	"flextable" (default) or "gt"
theme	preset or primitives

Value

A list with class c("gtregression", "descriptive_table", ...) containing:

table

A gt_tbl or flextable.

table_display

Display-ready data.

table_body

Long audit data with variable, level, and type.

metadata

Additional metadata fields.

---

Dissect a dataset before regression

Description

Returns a tidy summary of each variable's structure, missingness, uniqueness, and suitability for use in regression models.

Usage

dissect(data, verbose = FALSE, format = c("flextable", "gt", "tibble"))

Arguments

data	A data frame.
verbose	Logical; if TRUE, print the summary and interpretation notes. The tibble is returned invisibly only when printed by the console.
format	Output format. One of "flextable" (default), "gt", or "tibble". Use format = "tibble" for pipeline-friendly raw output.

Value

A tibble, gt_tbl, or flextable, depending on format. The tibble has columns: Variable, Type, Missing ( Levels, Compatibility, and Hint.

Examples

dissect(data_birthwt)
dissect(data_birthwt, format = "gt")

# Print interpretation notes for beginners
dissect(data_birthwt, verbose = TRUE)

---

Build a compatible data frame for forest plots

Description

Creates the tabular input used by forest_reg() from uni_reg(), multi_reg(), and optionally descriptive_table() objects. This function is useful when users want to inspect, edit, or reuse the exact data that will be passed to the forest plot.

Usage

forest_df(uni, multi = NULL, desc = NULL, digits = 2)

Arguments

uni	A gtregression object from uni_reg(). If multi is supplied without uni, the multivariable object is plotted as a single effect column.
multi	Optional gtregression object from multi_reg().
desc	Optional descriptive table object from descriptive_table().
digits	Number of digits used when formatting confidence intervals.

Value

A data frame with display columns, formatted effect-size columns, standard-error columns, and plotting attributes used by forest_reg() to draw confidence intervals.

Examples

birthwt_data <- data_birthwt |>
  dplyr::mutate(
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW"))
  )

uni_or <- uni_reg(
  birthwt_data,
  outcome = "low",
  exposures = c("age", "lwt", "smoke", "ht"),
  approach = "logit"
)
multi_or <- multi_reg(
  birthwt_data,
  outcome = "low",
  exposures = c("smoke", "ht"),
  adjust_for = c("age", "lwt"),
  approach = "logit"
)

forest_data <- forest_df(uni_or, multi_or)
head(forest_data)

---

Draw a publication-ready forest plot

Description

Wrapper around forestploter::forest() that works directly with forest_df() output or with gtregression regression objects. It can show descriptive columns and one or two model effect columns in a table-style forest plot.

Usage

forest_reg(
  df = NULL,
  uni = NULL,
  multi = NULL,
  desc = NULL,
  theme = NULL,
  ci_col_width = 0.25,
  side = c("right", "left"),
  quiet = TRUE,
  effects = NULL,
  ticks_at = NULL,
  ticks_digits = NULL,
  ...
)

Arguments

df	Output of forest_df(). If NULL, it is built from uni, multi, and desc.
uni, multi, desc	Optional gtregression objects to pass through to forest_df().
theme	Optional forestploter::forest_theme(). If NULL, a sensible default is used. You may pass colors and styling either here or through ....
ci_col_width	Numeric or length-2 numeric. Relative width of the CI column(s). A vector like c(0.22, 0.26) lets you tune unadjusted and adjusted columns separately.
side	Character. For each effect, position of the plot relative to the effect-size text: "left" = plot first then text; "right" = text first then plot. The Characteristic column and descriptive columns remain on the left.
quiet	Logical. Suppress forestploter warnings. Default = 'TRUE'.
effects	Optional effect labels passed to forestploter::forest().
ticks_at	Optional numeric vector, or length-2 list for two effect columns, specifying x-axis tick positions. If NULL, forestploter::forest() chooses the default ticks.
ticks_digits	Optional number of digits for x-axis tick labels.
...	Passed to forestploter::forest(). Common options include title and footnote.

Value

A gtregression_forest object with elements:

plot

The forest plot object.

data

The plotting data sent to forestploter::forest().

input_data

The original forest_df() data, including standard-error helper columns.

meta

Model metadata, including reference line and x-axis transformation.

Examples

birthwt_data <- data_birthwt |>
  transform(
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1),
                 labels = c("Normal BW", "Low BW"))
  )

uni_or <- uni_reg(
  birthwt_data,
  outcome = "low",
  exposures = c("age", "lwt", "smoke", "ht"),
  approach = "logit"
)
multi_or <- multi_reg(
  birthwt_data,
  outcome = "low",
  exposures = c("smoke", "ht"),
  adjust_for = c("age", "lwt"),
  approach = "logit"
)

forest_reg(uni = uni_or, multi = multi_or)

---

Identify confounders and effect modifiers

Description

Assesses whether one or more candidate variables act as confounders or effect modifiers for one or more exposures.

Usage

identify_confounder(
  data,
  outcome,
  exposure,
  potential_confounder,
  approach = "logit",
  method = "change",
  threshold = 10,
  emm_threshold = 10,
  emm_test = c("interaction", "both", "estimate"),
  interaction_alpha = 0.05,
  format = c("flextable", "gt"),
  theme = c("minimal")
)

Arguments

data	A data frame.
outcome	Outcome variable name. Quoted and bare names are accepted.
exposure	Exposure variable name(s). Can be a character scalar or vector. Quoted names are recommended in scripts, and bare names are also accepted.
potential_confounder	Candidate confounder/effect-modifier variable name(s). Can be a character scalar or vector. Quoted names are recommended in scripts, and bare names are also accepted.
approach	Regression approach. One of "logit", "logbinomial", "poisson", "robpoisson", "linear", or "negbin".
method	Confounding assessment method. One of "change", "mh", or "both". "change" compares crude and adjusted model estimates. "mh" compares crude and Mantel-Haenszel pooled estimates and is available for binary outcome, binary exposure, and categorical strata. "both" uses either method.
threshold	Percent change threshold for confounding assessment.
emm_threshold	Threshold for relative spread in stratum-specific estimates when using estimate-based effect-modification screening.
emm_test	One of "interaction", "both", or "estimate".
interaction_alpha	Alpha threshold for interaction p-values.
format	Output table format. One of "flextable" (default) or "gt".
theme	Table theme preset or primitives.

Details

The function first assesses possible effect modification using stratum-specific estimates and/or an interaction test. If no important effect modification is detected, it then assesses confounding using the selected method.

This is a screening aid for viewing and organising results. Confounding and effect modification should be interpreted using subject-matter knowledge, study design, and causal diagrams such as DAGs. Automated change-in-estimate and interaction checks should not be used as the sole basis for model adjustment.

Use this function when you want to screen one or more candidate variables and organise crude, adjusted, Mantel-Haenszel, and effect-modification signals in one place. For a focused comparison of models with and without a planned exposure-by-modifier interaction term, use interaction_models().

Value

If a single exposure-candidate pair is supplied, returns a detailed list.

If multiple combinations are supplied, returns a list with:

summary

A tibble with one row per exposure-candidate combination.

details

A named list of detailed results for each combination.

See Also

interaction_models() for focused model comparison of a planned interaction term.

---

Compare Models With and Without an Interaction Term

Description

Fits two models, one with and one without an interaction term between an exposure and a potential effect modifier. The models are compared using a likelihood ratio test or Wald test to assess statistical evidence of interaction.

Usage

interaction_models(
  data,
  outcome,
  exposure,
  covariates = NULL,
  effect_modifier,
  approach = "logit",
  test = c("LRT", "Wald"),
  alpha = 0.05,
  verbose = FALSE,
  format = c("flextable", "gt", "tibble")
)

Arguments

data	A data frame containing all required variables.
outcome	Outcome variable name. Quoted and bare names are accepted.
exposure	Main exposure variable name. Quoted and bare names are accepted.
covariates	Optional character vector of additional covariates. Quoted names are recommended in scripts, and bare names are also accepted.
effect_modifier	Variable name for the potential effect modifier. Quoted and bare names are accepted.
approach	Regression approach. One of "logit", "logbinomial", "poisson", "robpoisson", "negbin", or "linear".
test	Statistical test for model comparison. One of "LRT" or "Wald".
alpha	Significance threshold used to classify the interaction result.
verbose	Logical; if TRUE, prints a short interpretation.
format	Output format for the viewing table. One of "flextable" (default), "gt", or "tibble". Use format = "tibble" to keep only the original list structure.

Details

Use this function when the interaction is planned or clinically/causally motivated and you want a focused model comparison. Mantel-Haenszel estimation is not used here because this function tests an explicit interaction term in a regression model. For broader screening of candidate confounders or effect modifiers, including Mantel-Haenszel-supported checks when appropriate, use identify_confounder().

Value

A list with model objects, formulas, p-value, decision, and a one-row summary tibble. When format is "gt" or "flextable", the list also includes table.

See Also

identify_confounder() for broader confounding and effect-modification screening.

---

Merge gtregression tables and preserve structure and notes

Description

Merge gtregression tables and preserve structure and notes

Usage

merge_tables(..., spanners = NULL, theme = "minimal")

Arguments

...	Two or more gtregression objects containing $table_display.
spanners	Character vector of spanner labels, one per table. If NULL, defaults to "Table 1", "Table 2", etc.
theme	Merge theme preset or vector of primitives.

Value

A merged table object of class c("gtregression", "merged_table", ...).

Examples

birthwt_data <- data_birthwt |>
  dplyr::mutate(
    race = factor(race, levels = c(1, 2, 3),
                  labels = c("White", "Black", "Other")),
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW"))
  )

uni_tbl <- uni_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("age", "lwt", "smoke", "ht"),
  approach = "logit"
)

multi_tbl <- multi_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("smoke", "ht"),
  adjust_for = c("age", "lwt"),
  approach = "logit"
)

merge_tables(
  uni_tbl,
  multi_tbl,
  spanners = c("Univariable", "Adjusted")
)

---

Modify Regression/Descriptive Tables (labels, headers, caption, notes)

Description

Works with objects created by this package (class "gtregression"): uni_reg(), multi_reg(), descriptive_table(), and merge_tables(). No gtsummary dependency or fallback.

Usage

modify_table(
  gt_table,
  variable_labels = NULL,
  level_labels = NULL,
  header_labels = NULL,
  caption = NULL,
  bold_labels = FALSE,
  bold_levels = FALSE,
  remove_N = FALSE,
  remove_N_obs = FALSE,
  remove_abbreviations = FALSE,
  caveat = NULL
)

Arguments

gt_table	Table object produced by this package (must contain $table_display).
variable_labels	Named character vector, for example c(old_var = "New label", ...).
level_labels	Named list for factor levels: list(var1 = c(old = "New", ...), var2 = c(...)).
header_labels	Named character vector to rename visible headers, e.g. c("OR (95% CI)" = "Crude OR", "p-value" = "P"). Common aliases such as estimate, p.value, and N are also accepted.
caption	Optional caption/title.
bold_labels	Logical; bold variable (header) rows in the body.
bold_levels	Logical; bold factor level rows in the body.
remove_N	Logical; if TRUE, drops the N column for univariate package tables.
remove_N_obs	Logical; if TRUE, suppresses multivariable complete-case footnote.
remove_abbreviations	Logical; if TRUE, removes the Abbreviations footnote line.
caveat	Optional extra footnote.

Value

The modified table object (same class as input).

Examples

birthwt_data <- data_birthwt |>
  dplyr::mutate(
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW"))
  )

tbl <- uni_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("age", "smoke", "ht"),
  approach = "logit"
)

modify_table(
  tbl,
  variable_labels = c(age = "Maternal age", smoke = "Smoking"),
  level_labels = list(smoke = c(Yes = "Smoker")),
  header_labels = c(estimate = "Crude OR", p.value = "P"),
  caption = "Univariable regression for low birth weight"
)$table

---

Multivariable regression

Description

Create a publication-ready multivariable regression table using either gt or flextable, without a gtsummary dependency.

Usage

multi_reg(
  data,
  outcome,
  exposures,
  adjust_for = NULL,
  interaction = NULL,
  approach = "logit",
  format = c("flextable", "gt"),
  theme = c("minimal")
)

Arguments

data	A data.frame containing the variables of interest.
outcome	Character scalar; name of the outcome variable. Quoted and bare names are accepted.
exposures	Character vector; exposure variable(s) to report. Quoted names are recommended in scripts, and bare names are also accepted. If adjust_for = NULL, all exposures are included in a single multivariable model. If adjust_for is supplied, one adjusted model is fitted per exposure and only exposure-specific adjusted estimate(s) are displayed.
adjust_for	Optional character vector of adjustment variables. Quoted and bare names are accepted. Must not overlap with exposures.
interaction	Optional character scalar specifying one interaction term using standard formula syntax, e.g. "bmi*sex". When used with adjust_for, only a single exposure should be supplied.
approach	Character scalar specifying the regression approach. One of "logit", "logbinomial", "poisson", "linear", "robpoisson", or "negbin".
format	Output table format; one of "flextable" (default) or "gt".
theme	Table styling preset (e.g. "minimal", "striped", "clinical", "shaded", "jama") or a character vector of primitives such as c("plain","zebra","lines","labels_bold","compact","header_shaded").

Details

In default mode (adjust_for = NULL), all exposures are included in a single multivariable model. In adjusted mode, one model is fitted per exposure, adjusting for the variables specified in adjust_for.

Interaction terms specified via interaction are included in the model using standard formula expansion (e.g. bmi*sex). Interaction effects are displayed as additional rows beneath the corresponding exposure.

Value

A list of class c("gtregression","multi_reg", ...) with elements:

table

A flextable (if format="flextable") or gt_tbl (if format="gt").

table_body

A data frame of adjusted estimates and confidence intervals for each exposure and level.

table_display

A data frame used for rendering the final table, including header and level rows.

models

A list of fitted model(s).

model_summaries

summary() output for the fitted model(s).

reg_check

Regression diagnostics for linear models; otherwise a message.

approach

The regression approach used.

format

The output format used.

source

Function identifier ("multi_reg").

adjusted_mode

Whether one adjusted model per exposure was fitted.

adjust_for

Adjustment variables supplied by the user, if any.

exposures

Exposure variables supplied by the user.

interaction

Interaction term supplied by the user, if any.

---

Visualize a regression model as a forest plot

Description

Creates a forest plot from a fitted gtregression object produced by functions such as uni_reg() or multi_reg().

Usage

plot_reg(
  tbl,
  title = NULL,
  caption = NULL,
  ref_line = NULL,
  order_y = NULL,
  log_x = FALSE,
  xlim = NULL,
  breaks = NULL,
  point_color = "#1F77B4",
  errorbar_color = "#4C4C4C",
  base_size = 14,
  show_ref = TRUE,
  sig_color = NULL,
  sig_errorbar_color = NULL,
  alpha = 0.05,
  show_adjustment_note = TRUE
)

Arguments

tbl	A fitted gtregression object.
title	Optional plot title.
caption	Optional plot caption. If NULL, an adjustment note is added automatically for adjusted multi_reg() objects when show_adjustment_note = TRUE.
ref_line	Optional numeric value for the reference line. Defaults to 0 for linear models and 1 otherwise.
order_y	Optional character vector specifying exposure order.
log_x	Logical; if TRUE, use a log-scaled x-axis for non-linear models.
xlim	Optional numeric vector of length 2 specifying x-axis limits.
breaks	Optional numeric vector of x-axis tick breaks.
point_color	Fill color for points.
errorbar_color	Color for error bars.
base_size	Base font size.
show_ref	Logical; if TRUE, reference rows are shown.
sig_color	Optional fill color for significant points.
sig_errorbar_color	Optional color for significant error bars.
alpha	Significance level for linear models when p.value is available.
show_adjustment_note	Logical; if TRUE, add a default caption describing adjust_for variables when available.

Value

A ggplot2 object.

---

Side-by-side forest plots: univariate vs multivariable

Description

Creates two aligned forest plots from gtregression objects returned by uni_reg() and multi_reg().

Usage

plot_reg_combine(
  tbl_uni,
  tbl_multi,
  title_uni = NULL,
  title_multi = NULL,
  caption = NULL,
  ref_line = NULL,
  order_y = NULL,
  log_x = FALSE,
  point_color = "#1F77B4",
  errorbar_color = "#4C4C4C",
  base_size = 14,
  show_ref = TRUE,
  sig_color = NULL,
  sig_errorbar_color = NULL,
  xlim_uni = NULL,
  breaks_uni = NULL,
  xlim_multi = NULL,
  breaks_multi = NULL,
  alpha = 0.05,
  show_adjustment_note = TRUE
)

Arguments

tbl_uni	A univariate gtregression object.
tbl_multi	A multivariable gtregression object.
title_uni, title_multi	Optional panel titles.
caption	Optional combined plot caption. If NULL, an adjustment note is added automatically from tbl_multi when show_adjustment_note = TRUE.
ref_line	Optional numeric reference line. If NULL, uses 0 for linear models and 1 otherwise.
order_y	Optional character vector to customize exposure ordering.
log_x	Logical; if TRUE, uses log x-axis for non-linear models.
point_color, errorbar_color	Base colors for non-significant rows.
base_size	Base font size for theme_minimal().
show_ref	Logical; if TRUE, include reference levels as (ref).
sig_color, sig_errorbar_color	Optional colors for significant rows. If NULL, base colors are reused.
xlim_uni, breaks_uni	Optional x-axis limits and breaks for the univariate panel.
xlim_multi, breaks_multi	Optional x-axis limits and breaks for the multivariable panel.
alpha	Significance level for linear models when p.value is available.
show_adjustment_note	Logical; if TRUE, add a default caption describing adjust_for variables from tbl_multi when available.

Value

A patchwork object with two ggplot2 panels.

---

Print gtregression objects (unified)

Description

Prints the rendered table for any object produced by this package (objects that include class "gtregression"), regardless of subtype (uni_reg, multi_reg, stratified_*, merged_table, descriptive_table, ...). If no rendered table is found, a compact structure of the object (or its display data) is shown.

Usage

## S3 method for class 'gtregression'
print(x, ...)

Arguments

x	An object with class "gtregression".
...	Ignored. Present for compatibility with the generic.

---

Save multiple tables and plots to a Word document

Description

Saves a collection of gtregression tables, merged tables, gt_tbl/flextable objects, and ggplot2 plots into a single Word document.

Usage

save_docx(
  tables = NULL,
  plots = NULL,
  filename = "report.docx",
  titles = NULL,
  plot_width = 6,
  plot_height = 5
)

Arguments

tables	A list of tables. Each element may be a gtregression object, merged_table object, gt_tbl, or flextable.
plots	A list of ggplot2 plot objects.
filename	File name for the output, with or without .docx. If no directory is supplied, the file is saved in tempdir().
titles	Optional character vector of titles for tables and plots in the order they are added.
plot_width	Width of inserted plots in inches.
plot_height	Height of inserted plots in inches.

Value

Saves the Word document to disk. Invisibly returns the normalized file path.

Examples

birthwt_data <- data_birthwt |>
  dplyr::mutate(
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW"))
  )

tbl <- uni_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("age", "smoke"),
  approach = "logit",
  format = "flextable"
)

save_docx(tables = tbl, filename = tempfile("report"))

---

Save a single plot

Description

Saves a ggplot2 plot to a file in PNG, PDF, or JPG format.

Usage

save_plot(
  plot,
  filename = "plot",
  format = c("png", "pdf", "jpg"),
  width = 8,
  height = 6,
  dpi = 300
)

Arguments

plot	A ggplot2 object.
filename	Name of the file to save, with or without extension. If no directory is supplied, the file is saved in tempdir().
format	Output format. One of "png", "pdf", or "jpg".
width	Width of the saved plot in inches.
height	Height of the saved plot in inches.
dpi	Resolution of the plot in dots per inch.

Value

Saves the file to disk. Invisibly returns the normalized file path.

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) +
  ggplot2::geom_point()

save_plot(p, filename = tempfile("plot"), format = "png")

---

Save a single regression or summary table

Description

Saves a gtregression table, merged table, gt_tbl, or flextable as a Word, PDF, or HTML file.

Usage

save_table(tbl, filename = "table", format = c("docx", "pdf", "html"))

Arguments

tbl	A gtregression object, merged_table object, gt_tbl, or flextable.
filename	File name for the output. Extension is optional. If no directory is supplied, the file is saved in tempdir().
format	Output format. One of "docx", "pdf", or "html".

Value

Saves the file to disk. Invisibly returns the normalized file path.

Examples

birthwt_data <- data_birthwt |>
  dplyr::mutate(
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW"))
  )

tbl <- uni_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("age", "smoke"),
  approach = "logit"
)

save_table(tbl, filename = tempfile("table"), format = "html")

---

Stepwise Model Selection with Evaluation Metrics

Description

Performs stepwise model selection using forward, backward, or both directions across different regression approaches. The function returns a summary table with evaluation metrics and the best model based on the lowest AIC.

Usage

select_models(
  data,
  outcome,
  exposures,
  approach = "logit",
  direction = "forward",
  format = c("flextable", "gt", "tibble")
)

Arguments

data	A data frame containing the outcome and predictor variables.
outcome	A single character string indicating the outcome variable. Quoted and bare names are accepted.
exposures	Character vector of predictor variables to consider. Quoted names are recommended in scripts, and bare names are also accepted.
approach	Regression method. One of: "logit", "logbinomial", "poisson", "robpoisson", "negbin", or "linear".
direction	Stepwise selection direction. One of: "forward" (default), "backward", or "both".
format	Output format for the viewing table. One of "flextable" (default), "gt", or "tibble". Use format = "tibble" to keep only the original list structure.

Value

A list with the following components:

• results_table: A tibble summarising each accepted step's model metrics (AIC, BIC, deviance, log-likelihood, and adjusted R-squared for linear models).

• best_model: The best-fitting model object based on lowest AIC.

• all_models: A named list of the accepted stepwise models.

• direction: Stepwise selection direction used.

• table: A formatted gt_tbl or flextable when format is "gt" or "flextable".

Examples

data <- data_birthwt
stepwise <- select_models(
  data = data,
  outcome = "bwt",
  exposures = c("age", "lwt", "smoke"),
  approach = "linear",
  direction = "forward"
)
stepwise$results_table
stepwise$best_model

---

Stratified multivariable regression

Description

Fits multivariable regression models within each stratum and returns a unified wide table with one "Characteristic" column and, under bold spanners for each stratum, two columns: "Adjusted <effect>" and "p-value".

Usage

stratified_multi_reg(
  data,
  outcome,
  exposures,
  stratifier,
  adjust_for = NULL,
  interaction = NULL,
  approach = "logit",
  format = c("flextable", "gt"),
  theme = c("minimal")
)

Arguments

data	A data frame containing the variables.
outcome	Character scalar; name of the outcome variable. Quoted and bare names are accepted.
exposures	Character vector of exposure variables to report. Quoted names are recommended in scripts, and bare names are also accepted.
stratifier	Character scalar; name of the stratifying variable. Quoted and bare names are accepted.
adjust_for	Optional character vector of adjustment variables. Quoted and bare names are accepted. This argument works the same way as in multi_reg().
interaction	Optional character scalar specifying one interaction term using standard formula syntax, e.g. "bmi*sex"
approach	One of "logit", "logbinomial", "poisson", "linear", "robpoisson", or "negbin"
format	One of "flextable" (default) or "gt".
theme	Preset name (e.g. "minimal", "striped", "clinical", "shaded", "jama") or primitives c("plain","zebra","lines","labels_bold","compact","header_shaded")

Details

If adjust_for = NULL, all exposures are included in one multivariable model within each stratum. If adjust_for is supplied, one adjusted model is fitted per exposure within each stratum.

Value

A list of class c("gtregression","stratified_multi_reg", ...) with:

table

A flextable (format = "flextable") or gt_tbl (format = "gt").

table_display

Wide data frame used to build the table.

per_stratum

Named list of per-stratum regression results.

models

Named list of fitted models by stratum.

model_summaries

Named list of model summaries by stratum.

reg_check

Named list of diagnostics by stratum.

by, levels, approach, format, source

Metadata fields.

Examples

birthwt_data <- data_birthwt |>
  transform(
    race = factor(race, levels = c(1, 2, 3),
                  labels = c("White", "Black", "Other")),
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    ui = factor(ui, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1),
                 labels = c("Normal BW", "Low BW"))
  )

stratified_multi <- stratified_multi_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("age", "lwt", "smoke", "ht"),
  stratifier = "race",
  approach = "logit"
)

stratified_adjusted <- stratified_multi_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("smoke", "ht", "ui"),
  stratifier = "race",
  adjust_for = c("age", "lwt"),
  approach = "logit"
)

---

Stratified univariable regression

Description

Fit univariable regression models within each level of a stratifier and combine the results into a publication-ready stratified table rendered with gt or flextable.

Usage

stratified_uni_reg(
  data,
  outcome,
  exposures,
  stratifier,
  approach = "logit",
  format = c("flextable", "gt"),
  theme = c("minimal")
)

Arguments

data	A data frame containing the variables.
outcome	Character scalar; name of the outcome variable. Quoted and bare names are accepted.
exposures	Character vector of exposure variables to model. Quoted names are recommended in scripts, and bare names are also accepted.
stratifier	Character scalar; name of the stratifying variable. Quoted and bare names are accepted.
approach	Modeling approach. One of "logit", "logbinomial", "poisson", "robpoisson", "linear", or "negbin".
format	Output table format; one of "flextable" (default) or "gt".
theme	Table styling preset or theme primitives.

Value

A list of class c("gtregression", "stratified_uni_reg", ...) with elements:

table

A rendered gt_tbl or flextable.

table_display

Display-ready wide stratified results.

per_stratum

List of complete uni_reg() results by stratum.

models

List of fitted model objects by stratum.

model_summaries

List of model summaries by stratum.

reg_check

Regression diagnostics by stratum.

by

The stratifier variable.

levels

Strata included in the analysis.

approach

The regression approach used.

format

The output format used.

source

Function identifier ("stratified_uni_reg").

Accessors

$table

Rendered stratified regression table.

$table_display

Wide display data used to build the table.

$per_stratum

Full uni_reg() result objects by stratum.

$models

List of fitted model objects for each stratum.

$model_summaries

List of model summaries.

$reg_check

Diagnostic check results (when applicable).

See Also

[multi_reg()], [plot_reg()], [identify_confounder()]

Examples

birthwt_data <- data_birthwt |>
  transform(
    race = factor(race, levels = c(1, 2, 3),
                  labels = c("White", "Black", "Other")),
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1),
                 labels = c("Normal BW", "Low BW"))
  )

stratified_uni <- stratified_uni_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("age", "lwt", "smoke"),
  stratifier = "race",
  approach = "logit"
)

stratified_uni$table

---

Univariate regression

Description

Create a publication-ready univariate regression table using either gt or flextable

Usage

uni_reg(
  data,
  outcome,
  exposures,
  approach = "logit",
  format = c("flextable", "gt"),
  theme = c("minimal")
)

Arguments

data	data.frame
outcome	Character scalar; outcome column name. Quoted and bare names are accepted.
exposures	Character vector; exposure column names. Quoted names are recommended in scripts, and bare names are also accepted.
approach	one of "logit", "logbinomial", "poisson", "linear"
format	One of "flextable" (default) or "gt".
theme	preset name (e.g. "minimal", "striped", "clinical", "shaded", "jama") or primitives c("plain","zebra","lines","labels_bold","compact","header_shaded")

Value

A list of class c("gtregression","uni_reg", ...) with elements:

table

A flextable (when format="flextable") or gt_tbl (when format="gt").

table_body

Data frame of numeric estimates and CIs.

table_display

Data frame for display (headers + levels).

models

List of fitted univariate models.

model_summaries

Per-model summary() results.

reg_check

Diagnostics for linear models; message otherwise.

approach, format, source

Metadata fields.

Examples

d <- mtcars
if (requireNamespace("gt", quietly = TRUE)) {
  uni_reg(d, "am", c("mpg","cyl"), approach = "logit", format = "gt")$table
}
if (requireNamespace("flextable", quietly = TRUE)) {
  uni_reg(d, "am", c("mpg","cyl"), approach = "logit", format = "flextable")$table
}

---