% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/check_convergence.R
\name{check_convergence}
\alias{check_convergence}
\title{Check regression model convergence}
\usage{
check_convergence(
  data,
  exposures,
  outcome,
  approach = "logit",
  multivariate = FALSE,
  format = c("flextable", "gt", "tibble")
)
}
\arguments{
\item{data}{A data frame containing the dataset.}

\item{exposures}{A character vector of predictor variable names. Quoted names
are recommended in scripts, and bare names are also accepted.
If \code{multivariate = FALSE}, each exposure is assessed separately.
If \code{multivariate = TRUE}, exposures are included together.}

\item{outcome}{A character string specifying the outcome variable. Quoted and
bare names are accepted.}

\item{approach}{A character string specifying the regression approach.
One of:
  \code{"logit"}, \code{"logbinomial"}, \code{"poisson"},
  \code{"robpoisson"}, or \code{"negbin"}.}

\item{multivariate}{Logical. If \code{TRUE},
checks convergence for a multivariable model;
  otherwise, performs checks for each univariate model.}

\item{format}{Output format. One of \code{"flextable"} (default),
\code{"gt"}, or \code{"tibble"}. Use \code{format = "tibble"} for the
original data-frame style output.}
}
\value{
A data frame, \code{gt_tbl}, or \code{flextable} summarizing
convergence diagnostics, including:
\describe{
  \item{\code{Exposure}}{Name of the exposure variable.}
  \item{\code{Model}}{The regression approach used.}
  \item{\code{Converged}}{\code{TRUE} if the model converged successfully;
   \code{FALSE} otherwise.}
  \item{\code{Max.prob.}}{Maximum predicted probability or
  fitted value in the dataset.}
}
}
\description{
Check whether requested models converge, either one exposure at a time or as
a single multivariable model.
}
\details{
For \code{robpoisson}, predicted probabilities (fitted values) may exceed 1,
which is acceptable when estimating risk ratios but should not be interpreted
as actual probabilities.

This is especially useful for \code{"logbinomial"} models, where convergence
problems are common and robust Poisson may be a practical alternative.
}
\examples{
if (requireNamespace("gtregression", quietly = TRUE)) {
  data(data_SynthDiabetes, package = "gtregression")

  check_convergence(
    data = data_SynthDiabetes,
    exposures = c("age", "mass"),
    outcome = "diabetes",
    approach = "logit",
    format = "tibble"
  )

  check_convergence(
    data = data_SynthDiabetes,
    exposures = c("age", "mass"),
    outcome = "diabetes",
    approach = "logit",
    multivariate = TRUE,
    format = "gt"
  )
}
}
\seealso{
[identify_confounder()],  [interaction_models()]
}
