% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compare_models.R
\name{compare_models}
\alias{compare_models}
\title{Compare Prespecified Regression Models}
\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{
\item{...}{Two or more gtregression model objects, or one list containing
them. Inputs should be outputs from \code{multi_reg()}, \code{cox_reg()},
or \code{surv_reg()}.}

\item{model_names}{Optional character vector of names to display. If omitted,
names supplied in \code{...} are used; otherwise models are labelled
\code{Model 1}, \code{Model 2}, etc.}

\item{nested}{Logical. If \code{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.}

\item{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.}

\item{exponentiate}{Logical. If \code{NULL}, Cox, logistic, Poisson,
negative-binomial, and parametric survival models are exponentiated by
default, while linear models are not.}

\item{digits}{Number of digits for model statistics and estimates.}

\item{p_digits}{Number of digits for p-values.}

\item{format}{Output format. Defaults to \code{"flextable"}.}

\item{theme}{Table theme preset.}
}
\value{
A \code{gtregression} object with:
\itemize{
  \item \code{table}: publication-ready table
  \item \code{table_body}: raw comparison statistics
  \item \code{table_display}: formatted display data
  \item \code{models}: fitted models compared
  \item \code{comparison_status}: whether models appear to use the same
    analysis sample
  \item \code{comparison_warnings}: caution messages that are highlighted
    in rendered tables when interpretation needs extra care
}
}
\description{
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 \code{multi_reg()},
\code{cox_reg()}, or \code{surv_reg()}.
}
\details{
\code{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 \code{models}
element. The reported N, event counts, and fit statistics therefore come from
the model already fitted by \code{multi_reg()}, \code{cox_reg()}, or
\code{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.
The guided builder in \code{gtregression_app()} can create the fitted
gtregression objects before calling this function; the generated app code
exposes every model formula and comparison call.

Likelihood-ratio p-values are meaningful only for nested models fitted to
the same analysis sample. \code{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
\code{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
)

}
\seealso{
\code{gtregression_app()}, \code{multi_reg()}, \code{cox_reg()},
  \code{surv_reg()}, \code{select_models()}
}
