% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analysis-diffs.R
\name{get_diffs}
\alias{get_diffs}
\title{Treatment Effect Estimation for Survey Designs}
\usage{
get_diffs(
  design,
  x,
  treats,
  group = NULL,
  covariates = NULL,
  ref_level = NULL,
  pval_adj = NULL,
  show_means = TRUE,
  show_pct_change = FALSE,
  scale = c("ame", "link"),
  variance = "ci",
  conf_level = 0.95,
  min_cell_n = 30L,
  n_weighted = FALSE,
  decimals = NULL,
  na.rm = TRUE,
  label_values = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)
}
\arguments{
\item{design}{A survey design object: \code{survey_taylor},
\code{survey_replicate}, \code{survey_twophase}, or \code{survey_nonprob}.}

\item{x}{<\code{\link[tidyselect:language]{tidy-select}}> A single unquoted
numeric variable name for the dependent variable. Must resolve to
exactly one numeric column (continuous or 0/1 binary).}

\item{treats}{<\code{\link[tidyselect:language]{tidy-select}}> A single unquoted
variable name for the treatment/group variable. Must resolve to
exactly one column with at least 2 unique levels. Coerced to factor
if not already.}

\item{group}{<\code{\link[tidyselect:language]{tidy-select}}> Optional subgroup
variable(s) for interaction analysis. When provided, treatment effects
are reported separately within each subgroup. Combined with any
grouping set by \code{group_by()}. Default \code{NULL}.}

\item{covariates}{Character vector of additional model terms as strings.
Supports interactions (\code{"age * gender"}), polynomials
(\code{"poly(edu, 2)"}), and transformations (\code{"log(income)"}). When
provided, forces the marginaleffects estimation path. Default \code{NULL}.}

\item{ref_level}{Character(1). Reference level of \code{treats} for
comparisons. If \code{NULL} (default), the first factor level is used.
Must match an existing level.}

\item{pval_adj}{Character(1) or \code{NULL}. P-value adjustment method
passed to \code{\link[stats:p.adjust]{stats::p.adjust()}}. Options: \code{"holm"}, \code{"hochberg"},
\code{"hommel"}, \code{"bonferroni"}, \code{"BH"}, \code{"BY"}, \code{"fdr"}, \code{"none"}.
\code{NULL} = no adjustment. When \code{group} is active, adjustment is applied
independently within each group.}

\item{show_means}{Logical. If \code{TRUE} (default), includes a \code{mean}
column and a reference row with \code{estimate = 0}. Subject to link-scale
suppression (see Details).}

\item{show_pct_change}{Logical. If \code{TRUE}, includes a \code{pct_change}
column: \code{estimate / reference_mean}. Subject to link-scale
suppression (see Details). Default \code{FALSE}.}

\item{scale}{Character(1). \code{"ame"} (default): average marginal effects
on the response scale. \code{"link"}: coefficients on the link scale.
For Gaussian/identity models, both are identical. Case-sensitive.}

\item{variance}{\code{NULL} or a character vector of one or more of \code{"se"},
\code{"ci"}. Controls which uncertainty columns appear. Default \code{"ci"}.}

\item{conf_level}{Numeric(1) in (0, 1). Confidence level. Default
\code{0.95}.}

\item{min_cell_n}{Integer(1). Minimum unweighted cell size before
\code{surveycore_warning_small_cell} fires. Default \code{30L}.}

\item{n_weighted}{Logical. If \code{TRUE}, includes an \code{n_weighted} column
with sum of weights per treatment level. Default \code{FALSE}.}

\item{decimals}{Integer(1) or \code{NULL}. If non-NULL, rounds numeric
output columns. \code{pct_change} is rounded to \code{decimals + 2}. Default
\code{NULL}.}

\item{na.rm}{Logical. If \code{TRUE} (default), rows with \code{NA} in \code{x},
\code{treats}, or \code{group} are dropped before fitting. If \code{FALSE}, \code{NA}
values cause an error.}

\item{label_values}{Logical. If \code{TRUE} (default), the \code{treats} and
\code{group} columns display value labels from metadata instead of raw
codes. Output type is \code{factor} when labels are applied.}

\item{name_style}{\code{"surveycore"} (default) or \code{"broom"}. When
\code{"broom"}, renames \code{se} to \code{std.error}, \code{ci_low} to \code{conf.low},
etc. The \code{mean} column is excluded from renaming.}

\item{...}{Passed to \code{\link[=survey_glm]{survey_glm()}}. Common uses:
\code{family = quasibinomial()}.}

\item{.id}{Character(1) or \code{NULL}. Column name used to identify each
survey when \code{design} is a \code{\link{survey_collection}}. For collection inputs,
\code{NULL} (the default) resolves to the collection's stored \verb{@id} property.
Pass a non-\code{NULL} value to override. Ignored when \code{design} is a single
survey.}

\item{.if_missing_var}{\code{"error"}, \code{"skip"}, or \code{NULL}. How to handle
surveys in a collection that lack one of the requested NSE variables.
For collection inputs, \code{NULL} (the default) resolves to the collection's
stored \verb{@if_missing_var} property. Pass a non-\code{NULL} value to override.
Ignored when \code{design} is a single survey.}
}
\value{
A \code{survey_diffs} tibble (also inheriting \code{survey_result}).
Columns (in order): group columns (when active), treatment variable,
\code{estimate}, \code{pct_change} (optional), \code{mean} (optional), \code{n},
\code{n_weighted} (optional), \code{se} (optional), \code{ci_low} (optional),
\code{ci_high} (optional), \code{p_value}, \code{stars}. Use \code{\link[=meta]{meta()}} to access
design type, family, reference level, and other metadata.
}
\description{
Estimates treatment effects (differences from a reference group) via
survey-weighted regression. Supports bivariate and multivariate models,
Gaussian and non-Gaussian families, and optional subgroup analysis.
}
\details{
\subsection{Estimation Paths}{

\code{get_diffs()} uses two estimation paths:
\itemize{
\item \strong{Clean path} (bivariate Gaussian, no group): extracts coefficients
directly from \code{clean()}. The intercept is the reference group mean;
treatment coefficients are differences from reference.
\item \strong{Marginaleffects path} (covariates, non-Gaussian with
\code{scale = "ame"}, or group): uses \code{avg_slopes()} for estimates and
\code{avg_predictions()} for means.
}
}

\subsection{Link-Scale Suppression}{

When \code{scale = "link"} and the family is non-Gaussian, the \code{mean} and
\code{pct_change} columns are suppressed (omitted entirely). Link-scale
means are not substantively meaningful.
}

\subsection{P-Value Adjustment}{

When \code{group} is active, p-value adjustment is applied independently
within each group. For global adjustment across all comparisons,
apply \code{\link[stats:p.adjust]{stats::p.adjust()}} to the result manually. Confidence intervals
reflect the specified \code{conf_level} and are not affected by p-value
adjustment.
}

\subsection{Degrees of Freedom}{

All p-values and confidence intervals use the t-distribution with
design-based residual degrees of freedom, regardless of estimation
path.
}

\subsection{Non-Gaussian Models}{

By default, non-Gaussian models report average marginal effects on
the response scale. Set \code{scale = "link"} for coefficients on the link
scale (e.g., log-odds for logistic regression).
}
}
\examples{
library(marginaleffects)

# Create survey design with treatment groups
set.seed(42)
df <- data.frame(
  id = 1:200, wt = runif(200, 0.5, 2),
  dv = rnorm(200, 50, 10),
  arm = factor(sample(c("Control", "A", "B"), 200, TRUE))
)
d <- as_survey(df, weights = wt)

# Basic treatment effect
get_diffs(d, dv, arm)

# With percentage change and p-value adjustment
get_diffs(d, dv, arm, show_pct_change = TRUE, pval_adj = "BH")

}
\seealso{
Other analysis: 
\code{\link{clean}()},
\code{\link{get_anova}()},
\code{\link{get_corr}()},
\code{\link{get_covariance}()},
\code{\link{get_freqs}()},
\code{\link{get_means}()},
\code{\link{get_pairwise}()},
\code{\link{get_quantiles}()},
\code{\link{get_ratios}()},
\code{\link{get_t_test}()},
\code{\link{get_totals}()},
\code{\link{get_variance}()},
\code{\link{meta}()}
}
\concept{analysis}
