% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multi_reg.R
\name{multi_reg}
\alias{multi_reg}
\title{Multivariable regression}
\usage{
multi_reg(
  data,
  outcome,
  exposures,
  adjust_for = NULL,
  interaction = NULL,
  approach = "logit",
  format = c("flextable", "gt"),
  theme = c("minimal"),
  model_stats = FALSE,
  show_ref = TRUE
)
}
\arguments{
\item{data}{A \code{data.frame} containing the variables of interest.}

\item{outcome}{Character scalar; name of the outcome variable. Quoted and
bare names are accepted.}

\item{exposures}{Character vector; exposure variable(s) to report.
Quoted names are recommended in scripts, and bare names are also accepted.
If \code{adjust_for = NULL}, all exposures are included in a single
multivariable model. If \code{adjust_for} is supplied, one adjusted
model is fitted per exposure and only exposure-specific adjusted
estimate(s) are displayed.}

\item{adjust_for}{Optional character vector of adjustment variables. Quoted
and bare names are accepted. Must not overlap with \code{exposures}.}

\item{interaction}{Optional character scalar specifying one interaction term
using standard formula syntax, e.g. \code{"bmi*sex"}.
When used with \code{adjust_for}, only a single exposure should be supplied.}

\item{approach}{Character scalar specifying the regression approach.
One of \code{"logit"}, \code{"firth"}, \code{"logbinomial"}, \code{"poisson"},
\code{"linear"}, \code{"robpoisson"}, or \code{"negbin"}.
Use \code{"firth"} for Firth penalized logistic regression, especially
with sparse cells or separation.}

\item{format}{Output table format; one of \code{"flextable"} (default) or
\code{"gt"}.}

\item{theme}{Table styling preset (e.g. \code{"minimal"}, \code{"striped"},
\code{"clinical"}, \code{"shaded"}, \code{"jama"}) or a character vector of
primitives such as \code{c("plain","zebra","lines","labels_bold","compact","header_shaded")}.}

\item{model_stats}{Logical; if \code{TRUE}, extract model-fit statistics
such as AIC, BIC, log-likelihood, deviance, pseudo R-squared for
non-linear models, and R-squared for linear models. Statistics are stored
in the returned object's \code{model_stats} element and are not added to
the publication table.}

\item{show_ref}{Logical; if \code{TRUE} (default), display reference-category
rows as \code{"Ref."}. If \code{FALSE}, hide reference rows; a message
reminds users to use \code{show_ref = TRUE} when reference rows are needed.}
}
\value{
A list of class \code{c("gtregression","multi_reg", ...)} with elements:
\describe{
  \item{table}{A \code{flextable} (if \code{format="flextable"}) or
  \code{gt_tbl} (if \code{format="gt"}).}
  \item{table_body}{A data frame of adjusted estimates and confidence intervals
  for each exposure and level.}
  \item{table_display}{A data frame used for rendering the final table,
  including header and level rows.}
  \item{models}{A list of fitted model(s).}
  \item{model_summaries}{\code{summary()} output for the fitted model(s).}
  \item{model_stats}{Model-fit statistics when \code{model_stats = TRUE};
  otherwise \code{NULL}.}
  \item{variable_labels}{Named character vector of display labels used for
  exposure variables.}
  \item{reg_check}{Regression diagnostics for linear models. Printing this
  element renders a publication-ready table; individual diagnostic rows remain
  available for programmatic use. Other approaches return a message.}
  \item{approach}{The regression approach used.}
  \item{format}{The output format used.}
  \item{source}{Function identifier (\code{"multi_reg"}).}
  \item{adjusted_mode}{Whether one adjusted model per exposure was fitted.}
  \item{adjust_for}{Adjustment variables supplied by the user, if any.}
  \item{exposures}{Exposure variables supplied by the user.}
  \item{interaction}{Interaction term supplied by the user, if any.}
}
}
\description{
Fit adjusted or multivariable regression models and return a manuscript-style
table in \pkg{flextable} or \pkg{gt} format.
}
\details{
Use the default mode when you want all exposures in one model. Use
\code{adjust_for} when you want one adjusted estimate per reported exposure,
with the same adjustment set used repeatedly.

If exposure variables have a \code{"label"} attribute, for example from
\code{labelled::var_label()}, those labels are used automatically in the
displayed table and plots. Internal matching still uses the original column
names.

In default mode (\code{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 \code{adjust_for}.

Interaction terms specified via \code{interaction} are included in the model
using standard formula expansion (e.g. \code{bmi*sex}). Interaction effects are
displayed as additional rows beneath the corresponding exposure.
}
\examples{
endometrial_data <- data_endometrial
endometrial_data$HG <- factor(endometrial_data$HG, levels = c(0, 1))
endometrial_data$NV <- factor(endometrial_data$NV, levels = c(0, 1))
multi_reg(endometrial_data, HG, c(NV, PI, EH), approach = firth, format = gt)$table

}
