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

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

\item{exposures}{Character vector of exposure variables to report. Quoted
names are recommended in scripts, and bare names are also accepted.}

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

\item{adjust_for}{Optional character vector of adjustment variables.
Quoted and bare names are accepted. This argument works the same way as in
\code{multi_reg()}.}

\item{interaction}{Optional character scalar specifying one interaction term
using standard formula syntax, e.g. \code{"bmi*sex"}}

\item{approach}{One of \code{"logit"}, \code{"firth"}, \code{"logbinomial"}, \code{"poisson"},
\code{"linear"}, \code{"robpoisson"}, or \code{"negbin"}}

\item{format}{One of \code{"flextable"} (default) or \code{"gt"}.}

\item{theme}{Preset name (e.g. \code{"minimal"}, \code{"striped"}, \code{"clinical"},
\code{"shaded"}, \code{"jama"}) or primitives
\code{c("plain","zebra","lines","labels_bold","compact","header_shaded")}}

\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","stratified_multi_reg", ...)} with:
\describe{
  \item{\code{table}}{A \code{flextable} (format = \code{"flextable"}) or
  \code{gt_tbl} (format = \code{"gt"}).}
  \item{\code{table_display}}{Wide data frame used to build the table.}
  \item{\code{per_stratum}}{Named list of per-stratum regression results.}
  \item{\code{models}}{Named list of fitted models by stratum.}
  \item{\code{model_summaries}}{Named list of model summaries by stratum.}
  \item{\code{variable_labels}}{Named character vector of display labels used
  for exposure variables.}
  \item{\code{reg_check}}{Named list of diagnostics by stratum.}
  \item{\code{by}, \code{levels}, \code{approach}, \code{format}, \code{source}}{Metadata fields.}
}
}
\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, model N, "Adjusted <effect>", and "p-value".
}
\details{
If \code{adjust_for = NULL}, all \code{exposures} are included in one
multivariable model within each stratum. If \code{adjust_for} is supplied,
one adjusted model is fitted per exposure within each stratum.


If exposure variables have a \code{"label"} attribute, for example from
\code{labelled::var_label()}, those labels are used automatically in the
displayed table. Internal matching still uses the original column names.
}
\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",
  format = "gt"
)

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