% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analysis-variance.R
\name{get_variance}
\alias{get_variance}
\title{Design-Based Population Variance for a Survey Design}
\usage{
get_variance(
  design,
  x,
  group = NULL,
  variance = "ci",
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  na_handling = c("pairwise", "listwise"),
  label_values = TRUE,
  label_vars = 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}. Also accepts a
\code{\link{survey_collection}}.}

\item{x}{<\code{\link[tidyselect:language]{tidy-select}}> One or more unquoted
numeric variable names. Must resolve to at least one numeric column;
non-numeric columns are rejected (no silent drop).}

\item{group}{<\code{\link[tidyselect:language]{tidy-select}}> Optional grouping
variable(s). Combined with any grouping set by \code{group_by()}. Default
\code{NULL}.}

\item{variance}{\code{NULL} or a character vector of one or more of \code{"se"},
\code{"ci"}, \code{"var"}, \code{"cv"}, \code{"moe"}, \code{"deff"}. Controls which uncertainty
columns appear in the output. Default \code{"ci"}.}

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

\item{n_weighted}{Logical. If \code{TRUE}, add an \code{n_weighted} column with the
sum of weights for non-NA, positive-weight observations in each row's
estimate. Default \code{FALSE}.}

\item{decimals}{Integer or \code{NULL}. If an integer, rounds all numeric output
columns to this many decimal places. Default \code{NULL} (no rounding).}

\item{min_cell_n}{Integer. Minimum unweighted cell count before
\code{surveycore_warning_small_cell} fires. Default \code{30L} (AAPOR guidance).}

\item{na.rm}{Logical. If \code{TRUE} (default), \code{NA} values in the focal
variable are excluded from the estimate and rows with \code{NA} in any
grouping variable are excluded from the output. If \code{FALSE}, \code{NA}
propagates to produce \code{NaN} estimates.}

\item{na_handling}{\code{"pairwise"} (default) or \code{"listwise"}. In
multi-variable mode controls whether each focal variable uses its own
complete-case set (\code{"pairwise"}) or the intersection across all focal
variables (\code{"listwise"}). Ignored when \code{na.rm = FALSE}.}

\item{label_values}{Logical. Accepted for API uniformity; used to
convert grouping-variable codes to value labels. Default \code{TRUE}.}

\item{label_vars}{Logical. If \code{TRUE} (default), the \code{name} column
shows variable labels when available (falling back to raw names).}

\item{name_style}{\code{"surveycore"} (default) or \code{"broom"}. Under \code{"broom"},
renames \code{variance} → \code{estimate}, \code{se} → \code{std.error}, \code{ci_low} →
\code{conf.low}, \code{ci_high} → \code{conf.high}.}

\item{...}{Unused. Reserved so that \code{.id} and \code{.if_missing_var} remain
named-only when a \code{survey_collection} is passed as \code{design}.}

\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_variance} tibble (also inheriting \code{survey_result}).
Columns, in order:
\itemize{
\item \verb{[group_cols...]} — group variable columns (when active), first.
\item \code{name} — focal variable name (or its label when \code{label_vars = TRUE}).
\item \code{variance} — design-based point estimate of the finite-population
variance. \code{NaN} for degenerate cells; exact \code{0} for constant-in-domain
variables.
\item Uncertainty columns (\code{se}, \code{var}, \code{cv}, \code{ci_low}, \code{ci_high},
\code{moe}, \code{deff}) — only those requested via \code{variance}.
\item \code{n} — unweighted count of non-NA observations used.
\item \code{n_weighted} — sum of weights (only when \code{n_weighted = TRUE}).
}
}
\description{
Compute the design-based estimate of the finite-population variance for one
or more numeric variables in a survey design, with optional grouping,
uncertainty quantification, and metadata-driven labelling. Matches
\code{survey::svyvar()} numerically (Kish \code{n/(n-1)} correction) on Taylor,
replicate, twophase, and nonprob designs.
}
\details{
Confidence intervals use the normal-Wald approximation on the SE of the
variance estimate: \code{ci_low = variance - z * se},
\code{ci_high = variance + z * se}, where \code{z = qnorm((1 + conf_level) / 2)}.
The bounds are \strong{not clamped}. When the true variance is near zero with
wide SE, \code{ci_low} may be negative. Users who want non-negative lower
bounds can clamp at \code{0} post-hoc. This behaviour matches
\code{survey::svyvar()}.

Under \code{na_handling = "pairwise"} (the default), each focal variable
contributes its own per-variable complete-case count to \code{n}. Under
\code{na_handling = "listwise"}, every output row shares the intersection
complete-case count — rows with \code{NA} in any selected variable are
excluded from every variable's calculation.
}
\examples{
d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
get_variance(d, ridageyr)

# Multiple variables
get_variance(d, c(ridageyr, bpxsy1))

# With grouping
get_variance(d, ridageyr, group = riagendr)

}
\seealso{
Other analysis: 
\code{\link{clean}()},
\code{\link{get_anova}()},
\code{\link{get_corr}()},
\code{\link{get_covariance}()},
\code{\link{get_diffs}()},
\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{meta}()}
}
\concept{analysis}
