% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/interaction_models.R
\name{interaction_models}
\alias{interaction_models}
\title{Compare Models With and Without an Interaction Term}
\usage{
interaction_models(
  data,
  outcome = NULL,
  exposure,
  covariates = NULL,
  effect_modifier,
  approach = "logit",
  time = NULL,
  event = NULL,
  distribution = "weibull",
  test = c("LRT", "Wald"),
  alpha = 0.05,
  verbose = FALSE,
  format = c("flextable", "gt", "tibble")
)
}
\arguments{
\item{data}{A data frame containing all required variables.}

\item{outcome}{Outcome variable name. Quoted and bare names are accepted.
Required for ordinary regression approaches. Leave unset for Cox and
parametric survival approaches and supply \code{time} and \code{event}
instead.}

\item{exposure}{Main exposure variable name. Quoted and bare names are
accepted.}

\item{covariates}{Optional character vector of adjustment covariates. They
are included in both the model without and the model with the interaction
term. Quoted names are recommended in scripts, and bare names are also
accepted.}

\item{effect_modifier}{Variable name for the potential effect modifier.
Quoted and bare names are accepted.}

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

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

\item{event}{Event indicator variable name for survival approaches.}

\item{distribution}{Parametric survival distribution for
\code{approach = "survreg"}. One of \code{"weibull"},
\code{"exponential"}, \code{"lognormal"}, or \code{"loglogistic"}.}

\item{test}{Statistical test for model comparison. One of \code{"LRT"} or
\code{"Wald"}.}

\item{alpha}{Significance threshold used to classify the interaction result.}

\item{verbose}{Logical; if \code{TRUE}, prints a short interpretation.}

\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 model objects, formulas, p-value, decision, and a
  one-row summary tibble. When \code{format} is \code{"gt"} or
  \code{"flextable"}, the list also includes \code{table}.
}
\description{
Fits two models, one with and one without an interaction term between an
exposure and a potential effect modifier. The models are compared using a
likelihood ratio test or Wald test to assess statistical evidence of
interaction.
}
\details{
Use this function when the interaction is planned or clinically/causally
motivated and you want a focused model comparison. Mantel-Haenszel estimation
is not used here because this function tests an explicit interaction term in
a regression model. For broader screening of candidate confounders or effect
modifiers, including Mantel-Haenszel-supported checks when appropriate, use
\code{\link{identify_confounder}()}.

With \code{covariates = c(age, sex)}, the two fitted models are
\code{outcome ~ exposure + effect_modifier + age + sex} and
\code{outcome ~ exposure + effect_modifier + age + sex +
exposure:effect_modifier}. Both models use the same complete-case analysis
data, so covariate adjustment is applied consistently to the interaction
comparison.
}
\examples{
birthwt_data <- data_birthwt |>
  dplyr::mutate(
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW")),
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    race = factor(race, levels = c(1, 2, 3),
                  labels = c("White", "Black", "Other"))
  )

interaction_models(
  data = birthwt_data,
  outcome = low,
  exposure = smoke,
  effect_modifier = race,
  covariates = c(age, lwt),
  approach = logit
)

lung_data <- data_lungcancer |>
  dplyr::mutate(
    trt = factor(trt, levels = c(1, 2),
                 labels = c("Standard treatment", "Test treatment")),
    prior = factor(prior, levels = c(0, 10), labels = c("No", "Yes"))
  )

interaction_models(
  data = lung_data,
  time = time,
  event = status,
  exposure = trt,
  effect_modifier = prior,
  covariates = c(age, karno),
  approach = cox
)

}
\seealso{
\code{\link{identify_confounder}()} for broader confounding and
  effect-modification screening.
}
