% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analysis-covariance.R
\name{get_covariance}
\alias{get_covariance}
\title{Design-Based Population Covariance for a Survey Design}
\usage{
get_covariance(
  design,
  x,
  group = NULL,
  redundant = FALSE,
  diagonal = FALSE,
  variance = "ci",
  conf_level = 0.95,
  n_weighted = FALSE,
  decimals = NULL,
  min_cell_n = 30L,
  na.rm = TRUE,
  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}}> Two or more unquoted
variable names. Must resolve to at least two columns. Non-numeric
columns are dropped with a warning; if fewer than 2 numeric variables
remain, an error is raised.}

\item{group}{<\code{\link[tidyselect:language]{tidy-select}}> Optional grouping
variable(s). Combined with any grouping set by \code{group_by()}. Default
\code{NULL}. Covariances are estimated separately within each group using
that group's own weighted means for centring.}

\item{redundant}{Logical. If \code{FALSE} (default), each unordered pair
appears once in supply order (lower-triangle). If \code{TRUE}, both
\verb{(A, B)} and \verb{(B, A)} are emitted.}

\item{diagonal}{Logical. If \code{FALSE} (default), self-pairs \verb{(x, x)} are
excluded. If \code{TRUE}, one self-pair per variable is emitted with
\verb{covariance = \eqn{\widehat{\mathrm{Var}}(x)}{Var_hat(x)}} (the
design-based variance -- \strong{not} \code{1}).}

\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"}. Default \code{"ci"}.}

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

\item{n_weighted}{Logical. If \code{TRUE}, append an \code{n_weighted} column
with the pair's pairwise-complete sum of weights. Default \code{FALSE}.}

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

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

\item{na.rm}{Logical. If \code{TRUE} (default), pairwise-complete deletion
per pair, and rows with \code{NA} in any group variable are excluded from
the output. If \code{FALSE}, NAs propagate to produce \code{NaN} estimates;
NA group values are retained as their own group row.}

\item{label_values}{Logical. If \code{TRUE} (default) and the grouping
variable has value labels, the group column is converted to a
labelled factor.}

\item{label_vars}{Logical. If \code{TRUE} (default) and variable labels are
set in metadata, \code{var1} and \code{var2} show labels instead of raw names.}

\item{name_style}{\code{"surveycore"} (default) or \code{"broom"}. Under
\code{"broom"}, renames \code{covariance} -> \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_covariance} tibble (also inheriting \code{survey_result}).
Columns, in order:
\itemize{
\item \verb{[group_cols...]} — group variable columns (when active), first.
\item \code{var1}, \code{var2} — factor columns identifying the pair (levels in
\code{x}-supply order).
\item \code{covariance} — design-based Pearson covariance estimate
(Kish-corrected). \code{NaN} for degenerate cells; \code{0} for pairs where
at least one variable is constant on the active domain.
\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} — pairwise unweighted count.
\item \code{n_weighted} — pair's sum of weights (only when requested).
}
}
\description{
Compute the design-based estimate of the finite-population Pearson
covariance for every (unordered, by default) pair of numeric variables
selected from \code{x}, with optional grouping, uncertainty quantification,
and metadata-driven labelling. Matches the off-diagonal entries of
\code{survey::svyvar()} (Kish \code{n/(n-1)} correction) on Taylor, replicate,
twophase, and nonprob designs at numerical parity.
}
\details{
Confidence intervals use the normal-Wald approximation on the SE of the
covariance estimate: \code{ci_low = covariance - z * se},
\code{ci_high = covariance + z * se}, where \code{z = qnorm((1 + conf_level) / 2)}.
The bounds are \strong{not clamped}. Covariance is unbounded — \code{ci_low} and
\code{ci_high} may have opposite signs and may cross zero. Users who want
clamped intervals can post-process. This behaviour matches
\code{survey::svyvar()}.

NA handling is \strong{pairwise-complete per pair}: each ordered pair drops
rows where either variable is \code{NA}. There is no \code{na_handling} argument;
pairwise is the only policy. This matches \code{survey::svyvar()} off-diagonal
pair-at-a-time semantics, \strong{not} \code{svyvar()}'s default listwise deletion
across a multi-variable formula. Numerical parity therefore only holds
when oracle calls are made pair-at-a-time
(\code{survey::svyvar(~x + y, design)} per pair).

Under \code{diagonal = TRUE}, the self-pair \verb{(x, x)} returns the design-based
Kish-corrected \strong{variance} of \code{x} on the active domain — not \code{1} as in
\code{get_corr()}. The covariance matrix diagonal is the variance vector, not
the identity. The diagonal-parity gate guarantees that
\code{get_covariance(d, c(x, x), diagonal = TRUE)$covariance} and \verb{$se} equal
\code{get_variance(d, x)$variance} and \verb{$se} numerically (point at \code{1e-10},
SE at \code{1e-8}) when the active domains match.

Design effect (\code{deff}) uses the Goodnight / Mood-Graybill SRS reference
\code{SE_SRS(cov) = sqrt((Var(x) * Var(y) + cov^2) / (n - 1))}. When both
the design SE and SRS SE are zero (constant-variable pairs), \code{deff} is
set to exactly \code{0} (0 / 0 guard).
}
\examples{
d <- as_survey(
  nhanes_2017,
  ids = sdmvpsu,
  weights = wtint2yr,
  strata = sdmvstra,
  nest = TRUE
)
get_covariance(d, x = c(ridageyr, bpxsy1))

# Include the diagonal (self-pairs return Var(x), not 1)
get_covariance(d, x = c(ridageyr, bpxsy1), diagonal = TRUE)

# With grouping
get_covariance(d, x = c(ridageyr, bpxsy1), group = riagendr)

}
\references{
Mood, A. M., Graybill, F. A., & Boes, D. C. (1974).
\emph{Introduction to the Theory of Statistics} (3rd ed.). McGraw-Hill.

Lumley, T. (2010). \emph{Complex Surveys: A Guide to Analysis Using R}.
Wiley.

Cochran, W. G. (1977). \emph{Sampling Techniques} (3rd ed.). Wiley.

Demnati, A., & Rao, J. N. K. (2004). Linearization variance
estimators for survey data. \emph{Survey Methodology}, 30, 17--26.
}
\seealso{
Other analysis: 
\code{\link{clean}()},
\code{\link{get_anova}()},
\code{\link{get_corr}()},
\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{get_variance}()},
\code{\link{meta}()}
}
\concept{analysis}
