Skip to contents

Compare Prespecified Regression Models

Source: R/compare_models.R
compare_models.Rd

Compare gtregression candidate models side by side using model-fit statistics. This is intended for transparent model comparison after you have already fitted the candidate models with functions such as multi_reg(), cox_reg(), or surv_reg().

Usage

compare_models(
  ...,
  model_names = NULL,
  nested = TRUE,
  primary_exposure = NULL,
  exponentiate = NULL,
  digits = 2,
  p_digits = 3,
  format = c("flextable", "gt", "tibble"),
  theme = c("minimal")
)

Arguments

...

Two or more gtregression model objects, or one list containing them. Inputs should be outputs from multi_reg(), cox_reg(), or surv_reg().

model_names

Optional character vector of names to display. If omitted, names supplied in ... are used; otherwise models are labelled Model 1, Model 2, etc.

nested

Logical. If TRUE, likelihood-ratio statistics are calculated sequentially by comparing each model with the previous model. Use this only when models are nested and supplied in the intended order.

primary_exposure

Optional exposure or exact coefficient name to track across models. For Cox models this can be used to show the hazard ratio and percentage change in the log-effect estimate across candidate models.

exponentiate

Logical. If NULL, Cox, logistic, Poisson, negative-binomial, and parametric survival models are exponentiated by default, while linear models are not.

digits

Number of digits for model statistics and estimates.

p_digits

Number of digits for p-values.

format

Output format. Defaults to "flextable".

theme

Table theme preset.

Value

A gtregression object with:

  • table: publication-ready table

  • table_body: raw comparison statistics

  • table_display: formatted display data

  • models: fitted models compared

  • comparison_status: whether models appear to use the same analysis sample

  • comparison_warnings: caution messages that are highlighted in rendered tables when interpretation needs extra care

Details

compare_models() does not refit models and does not perform hidden complete-case filtering. It compares models already fitted by gtregression and extracts the single fitted model stored in each object's models element. The reported N, event counts, and fit statistics therefore come from the model already fitted by multi_reg(), cox_reg(), or surv_reg(). This keeps model comparison separate from model selection: compare candidate models first, then choose the final model using clinical, epidemiological, and statistical judgement.

Likelihood-ratio p-values are meaningful only for nested models fitted to the same analysis sample. compare_models() checks whether the fitted models appear to use the same analysis sample using retained model row identifiers when available; otherwise it compares N and event counts. It also checks whether sequential model pairs appear to be nested when nested = TRUE. Rendered warnings are context-aware: no warning about different analysis samples is shown when the compared models use the same observations, and no nested-model warning is shown when sequential models appear nested. AIC, BIC, log-likelihood, and likelihood-ratio statistics remain visible when warnings are needed, but should then be interpreted with the displayed caution.

Examples

data("data_lungcancer", package = "gtregression")

lung_data <- data_lungcancer

cox_1 <- cox_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = trt
)

cox_2 <- cox_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = trt,
  adjust_for = c(age, karno)
)

compare_models(
  cox_1,
  cox_2,
  primary_exposure = trt
)

compare_models(
  cox_1,
  cox_2,
  model_names = c("Treatment only", "Treatment + age + performance"),
  primary_exposure = trt
)