% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mediation_analysis.R
\name{mediation_analysis}
\alias{mediation_analysis}
\title{Causal mediation analysis}
\usage{
mediation_analysis(
  data,
  exposure,
  mediator,
  outcome,
  covariates = NULL,
  mediator_approach = "linear",
  outcome_approach = "linear",
  exposure_value = NULL,
  reference_value = NULL,
  sims = 1000,
  conf_level = 0.95,
  seed = NULL,
  format = c("flextable", "gt"),
  theme = c("minimal")
)
}
\arguments{
\item{data}{A data frame.}

\item{exposure}{Exposure/treatment variable. Quoted and bare names are
accepted.}

\item{mediator}{Mediator variable. Quoted and bare names are accepted.}

\item{outcome}{Outcome variable. Quoted and bare names are accepted.}

\item{covariates}{Optional character vector of covariate names. Quoted names
are recommended in scripts, and bare names are also accepted.}

\item{mediator_approach}{Mediator model. Currently \code{"linear"}.}

\item{outcome_approach}{Outcome model. One of \code{"linear"} or
\code{"logit"}. Logistic mediation effects are reported on the predicted
probability-difference scale.}

\item{exposure_value}{Exposure value used as the treatment level. If
\code{NULL}, the second factor level, value 1 for 0/1 variables, or the
75th percentile for continuous exposures is used.}

\item{reference_value}{Exposure value used as the reference level. If
\code{NULL}, the first factor level, value 0 for 0/1 variables, or the
25th percentile for continuous exposures is used.}

\item{sims}{Number of non-parametric bootstrap replicates used for confidence
intervals.}

\item{conf_level}{Confidence level for intervals.}

\item{seed}{Optional random seed for reproducible bootstrap intervals.}

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

\item{theme}{Table theme.}
}
\value{
A list of class \code{c("gtregression", "mediation_analysis", ...)}
with elements:
\describe{
  \item{table}{A formatted \code{flextable} or \code{gt_tbl}.}
  \item{table_body}{Data frame of mediation effect estimates.}
  \item{table_display}{Formatted data frame used to build the table.}
  \item{models}{Fitted mediator and outcome models.}
  \item{boot}{Bootstrap replicate estimates.}
  \item{values}{Reference and exposure values used.}
  \item{variable_labels}{Named character vector of display labels.}
  \item{call}{Matched function call.}
}
}
\description{
Estimate direct, indirect, total, and proportion mediated effects from
regression models.
}
\details{
This function is for planned mediation questions, not automatic causal
discovery. Causal interpretation requires the usual mediation assumptions,
including no unmeasured exposure-outcome, exposure-mediator, or
mediator-outcome confounding, correct temporal order, and suitable model
specification. Use a directed acyclic graph (DAG) and subject-matter
knowledge before interpreting the estimates causally.

For \code{outcome_approach = "linear"}, effects are mean differences. For
\code{outcome_approach = "logit"}, effects are predicted probability
differences, not odds ratios.
}
\examples{
med <- mediation_analysis(
  data = data_diabetes_mediation,
  exposure = obesity,
  mediator = glucose,
  outcome = diabetes,
  covariates = c(age, blood_pressure, pregnancies, diabetes_pedigree),
  outcome_approach = logit,
  sims = 50,
  seed = 123
)

med$table
med$table_body

# HTML-first output
mediation_analysis(
  data = data_diabetes_mediation,
  exposure = obesity,
  mediator = glucose,
  outcome = diabetes,
  covariates = c(age, blood_pressure, pregnancies, diabetes_pedigree),
  outcome_approach = logit,
  format = gt,
  sims = 50,
  seed = 123
)$table

}
