% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/select_models.R
\name{select_models}
\alias{select_models}
\title{Stepwise model selection with fit metrics}
\usage{
select_models(
  data,
  outcome,
  exposures,
  approach = "logit",
  time = NULL,
  event = NULL,
  distribution = "weibull",
  direction = "forward",
  format = c("flextable", "gt", "tibble")
)
}
\arguments{
\item{data}{A data frame containing the outcome and predictor variables.}

\item{outcome}{A single character string indicating the outcome variable.
Quoted and bare names are accepted. Not used for survival approaches when
\code{time} and \code{event} are supplied.}

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

\item{approach}{Regression method. One of:
\code{"logit"}, \code{"logbinomial"}, \code{"poisson"},
\code{"robpoisson"}, \code{"negbin"}, \code{"linear"}, \code{"cox"}, or
\code{"survreg"}.}

\item{time, event}{Survival time and event indicator for \code{approach = "cox"}
or \code{approach = "survreg"}. Quoted and bare names are accepted.}

\item{distribution}{Parametric survival distribution for
\code{approach = "survreg"}. One of \code{"weibull"},
\code{"exponential"}, \code{"lognormal"}, or \code{"loglogistic"}.
Common spellings such as \code{"log-normal"} and \code{"log-logistic"} are
also accepted.}

\item{direction}{Stepwise selection direction. One of:
\code{"forward"} (default), \code{"backward"}, or \code{"both"}.}

\item{format}{Output format for the viewing table. One of
\code{"flextable"} (default), \code{"gt"}, or \code{"tibble"}. Use
\code{format = "tibble"} to keep only the original list structure.}
}
\value{
A list with the following components:
\itemize{
  \item \code{results_table}: A tibble summarising each accepted step's
  model metrics (AIC, BIC, deviance, log-likelihood, and adjusted R-squared
  for linear models).
  \item \code{best_model}: The best-fitting model object based on lowest AIC.
  \item \code{all_models}: A named list of the accepted stepwise models.
  \item \code{direction}: Stepwise selection direction used.
  \item \code{table}: A formatted \code{gt_tbl} or \code{flextable} when
  \code{format} is \code{"gt"} or \code{"flextable"}.
}
}
\description{
Compare candidate models added or removed stepwise, then return the accepted
steps, model-fit metrics, and the lowest-AIC model.
}
\details{
Treat stepwise selection as a screening tool. It is best used alongside the
study question, clinical judgement, and model diagnostics rather than as an
automatic final-model rule.
}
\examples{
data <- data_birthwt
stepwise <- select_models(
  data = data,
  outcome = "bwt",
  exposures = c("age", "lwt", "smoke"),
  approach = "linear",
  direction = "forward"
)
stepwise$results_table
stepwise$best_model

}
