% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analysis-corr.R
\name{get_corr}
\alias{get_corr}
\title{Survey-Weighted Correlation (Pearson, Polychoric, Polyserial)}
\usage{
get_corr(
  design,
  x,
  group = NULL,
  format = c("long", "wide"),
  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",
  method = "pearson",
  ...,
  .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}. \code{method} values \code{"polychoric"}
and \code{"polyserial"} are supported on \code{survey_taylor} and
\code{survey_replicate} only; other design classes raise
\code{surveycore_error_polychoric_design_unsupported}.}

\item{x}{<\code{\link[tidyselect:language]{tidy-select}}> Two or more unquoted
variable names. For \code{method = "pearson"}, non-numeric columns are dropped
with a warning. For \code{method = "polychoric"}, every selected column must
classify as ordinal (ordered factor, unordered factor, or integer with
\verb{<= 10} distinct values) — non-ordinal columns raise
\code{surveycore_error_polychoric_requires_ordinal}. For
\code{method = "polyserial"}, each pair is canonicalized by type (one ordinal
\itemize{
\item one continuous); logical / character / high-cardinality integer
columns raise \code{surveycore_error_polyserial_canonicalization_ambiguous}.
}}

\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{format}{\code{"long"} (default) or \code{"wide"}. Long format returns one row
per variable pair with inference statistics. Wide format returns the
correlation matrix (\code{r} values only — no variance or inference columns).
When \code{group} is active, group columns are prepended in both formats.
Case-sensitive.}

\item{redundant}{Logical. If \code{FALSE} (default), each pair appears once
(lower triangle: pairs where var1 precedes var2 in input order). If
\code{TRUE}, both \verb{(A, B)} and \verb{(B, A)} are included (full directed pairs).
Only affects long format; wide format always shows the full symmetric
matrix.}

\item{diagonal}{Logical. If \code{FALSE} (default), self-correlations are
excluded (diagonal is \code{NA} in wide format). If \code{TRUE}, self-correlations
(r equals 1) are included.}

\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"}. CI bounds
use the Fisher Z transform (guaranteeing bounds in (-1, 1)). Only
applies to long format.}

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

\item{n_weighted}{Logical. If \code{TRUE}, add an \code{n_weighted} column with the
pairwise sum of weights (both variables non-NA). Default \code{FALSE}.}

\item{decimals}{Integer or \code{NULL}. If an integer, rounds all numeric output
columns (e.g., \code{r}, \code{se}, \code{ci_low}, \code{ci_high}) to this many decimal
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 guidance).}

\item{na.rm}{Logical. If \code{TRUE} (default), pairs use complete cases for
each variable pair separately (pairwise deletion), and observations where
any group variable is \code{NA} are excluded from the output. If \code{FALSE},
pairwise complete cases are still used for each variable pair, and
observations where a group variable is \code{NA} are collected into their own
group row in the output (appearing after all non-\code{NA} group rows).}

\item{label_values}{Logical. If \code{TRUE} (default) and the grouping variable
has value labels, the group column is converted to a labelled factor.
Has no visible effect when no groups are active.}

\item{label_vars}{Logical. If \code{TRUE} (default) and variable labels are
set in metadata, \code{var1}/\code{var2} columns (long) and \code{variable} column
(wide) show labels instead of raw names. Falls back to raw names if
labels are unset.}

\item{name_style}{\code{"surveycore"} (default) or \code{"broom"}. When \code{"broom"},
renames \code{r} → \code{estimate}, \code{se} → \code{std.error}, etc. Only affects long
format.}

\item{method}{Character(1). Estimator applied to every pair. One of
\code{"pearson"} (default, sample-based product-moment correlation),
\code{"polychoric"} (MLE under a bivariate-normal latent model for two
ordinal variables), or \code{"polyserial"} (MLE for one ordinal + one
continuous variable). The same \code{method} applies to every pair; it
cannot be vectorised. Non-matching values raise the standard
\code{\link[base:match.arg]{base::match.arg()}} signal.}

\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_corr} tibble (also inheriting \code{survey_result}).

When \code{group} is active, group variable columns are prepended before all
other columns in both long and wide formats.

\strong{Long format} columns:
\itemize{
\item \verb{[group_cols...]} — group variable columns (when active), first.
\item \code{var1}, \code{var2} — variable names (or labels when
\code{label_vars = TRUE}).
\item \code{r} — Pearson correlation coefficient.
\item Variance 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{p_value} — two-tailed p-value.
\item \code{statistic} — t-statistic.
\item \code{df} — degrees of freedom for the t-test (n minus 2).
\item \code{n} — pairwise unweighted count.
\item \code{n_weighted} — pairwise sum of weights (only when requested).
}

\strong{Wide format} columns:
\itemize{
\item \verb{[group_cols...]} — group variable columns (when active), first.
\item \code{variable} — row variable names (or labels).
\item One column per focal variable, containing \code{r} values.
}

Use \code{meta(result)} to access design type, variable labels, and
\code{method} (\code{"pearson"}, \code{"polychoric"}, or \code{"polyserial"}). For
\code{method != "pearson"}, \code{meta(result)$bivariate_normal_cdf} is
\code{"pbivnorm"} (the bivariate-normal CDF used internally). When the
replicate variance path observed one or more non-converged replicates,
\code{meta(result)$n_failed_replicates_total} carries the scalar total.
}
\description{
Compute pairwise correlations between two or more variables in a survey
design, with design-based standard errors and confidence intervals. Returns
results in long or wide format. The estimator is selected by \code{method}:
\code{"pearson"} (default) for two numeric variables, \code{"polychoric"} for two
ordinal variables under a bivariate-normal latent model (Olsson 1979),
or \code{"polyserial"} for one ordinal + one continuous variable (Cox 1974).
The survey-weighted polychoric and polyserial estimators (point estimates
and design-based variance) are implemented from scratch following
Mannan (2025); they are not derived from the \code{survey} package, which does
not provide these estimators.
}
\details{
\strong{Polychoric / polyserial semantics.} For \code{method != "pearson"}, each pair
is fit by a two-step MLE: weighted marginal thresholds (and, for
polyserial, a weighted standardization of the continuous side) are
estimated first, then \code{rho} is maximised over the weighted
log-likelihood via \code{\link[stats:optimize]{stats::optimize()}} on \verb{(-1 + 1e-6, 1 - 1e-6)}.
Confidence intervals are constructed on the Fisher-z scale
(\code{atanh(rho)}) and back-transformed via \code{tanh} with truncation to
\verb{[-1, 1]}. The Wald statistic \code{zeta.hat / SE(zeta.hat)} is referred to
a standard normal distribution, so \code{df = NA_integer_} — distinct from
the Pearson case where \code{df = n - 2} and the t-distribution is used.
Column label attributes are method-neutral (e.g. \code{"statistic"}, not
\code{"t-statistic"} / \code{"z-statistic"}); check \code{meta(result)$method} to
interpret the values.

\strong{Bivariate-normal assumption.} The polychoric / polyserial MLEs
assume the underlying latent variables are jointly bivariate-normal.
This is an unverified assumption; no runtime diagnostic is performed.

\strong{Taylor-path cost.} On a \code{survey_taylor} design, the variance path
for \code{method != "pearson"} is \code{O(n)} re-optimisations per variable pair
(a perturbation-based influence function). For large \code{n} and many
pairs, passing a \code{survey_replicate} design (one re-fit per replicate,
not per respondent) is substantially faster.

\strong{Replicate-type caveat.} Mannan (2025) verifies the replicate-weight
variance formula for jackknife and bootstrap replicates. BRR and Fay
replicates are admitted mechanically via the design's stored \code{scale}
/ \code{rscales} coefficients, but the paper does not validate their
behaviour for this non-linear pseudo-likelihood estimator.
}
\examples{
d <- as_survey(nhanes_2017, ids = sdmvpsu, weights = wtint2yr,
               strata = sdmvstra, nest = TRUE)
get_corr(d, x = c(ridageyr, bpxsy1))

# Wide correlation matrix
get_corr(d, x = c(ridageyr, bpxsy1), format = "wide")

# AAPOR-compliant
get_corr(d, x = c(ridageyr, bpxsy1),
         variance = c("ci", "moe"), n_weighted = TRUE)

# Polychoric correlation between two ordinal variables
df <- data.frame(
  id = 1:200,
  wt = runif(200, 0.5, 2),
  o1 = factor(sample(1:4, 200, replace = TRUE), ordered = TRUE),
  o2 = factor(sample(1:4, 200, replace = TRUE), ordered = TRUE)
)
d_ord <- as_survey(df, weights = wt)
get_corr(d_ord, x = c(o1, o2), method = "polychoric")

}
\references{
Cox, N. R. (1974). Estimation of the correlation between a continuous
and a discrete variable. \emph{Biometrics}, 30(1), 171-178.

Mannan, H. (2025). SAS programs for estimation of weighted polychoric
and weighted polyserial correlations in a complex survey. SSRN.
\doi{10.2139/ssrn.6580480}

Olsson, U. (1979). Maximum likelihood estimation of the polychoric
correlation coefficient. \emph{Psychometrika}, 44(4), 443-460.
}
\seealso{
Other analysis: 
\code{\link{clean}()},
\code{\link{get_anova}()},
\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{get_variance}()},
\code{\link{meta}()}
}
\concept{analysis}
