% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analysis-freqs.R
\name{get_freqs}
\alias{get_freqs}
\title{Weighted Frequency Tables for Categorical Survey Variables}
\usage{
get_freqs(
  design,
  x,
  ...,
  group = NULL,
  names_to = "name",
  values_to = "value",
  variance = NULL,
  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}.}

\item{x}{<\code{\link[tidyselect:language]{tidy-select}}> One or more categorical
variables. Bare names or tidy-select helpers (e.g., \code{c(q1, q2, q3)}).
When two or more variables are selected, multi-variable stacking mode
is activated (see Details).}

\item{...}{Additional arguments passed to tidy-select (future-proof;
currently unused).}

\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{names_to}{Character(1). Column name for the variable identifier in
multi-variable mode. Default \code{"name"}.}

\item{values_to}{Character(1). Column name for the response value in
multi-variable mode. Default \code{"value"}.}

\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{NULL} (no uncertainty columns).}

\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 (estimated population count) per cell. Default \code{FALSE}.}

\item{decimals}{Integer or \code{NULL}. If an integer, rounds all numeric output
columns (e.g., \code{pct}, \code{se}, \code{ci_low}, \code{ci_high}) 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 are excluded from
analysis: observations where the focal variable is \code{NA} are dropped from
frequency counts, and observations where any group variable is \code{NA} are
excluded from the output. If \code{FALSE}, \code{NA} values in the focal variable
appear as a dedicated frequency row in the output (not merely counted),
and observations where a group variable is \code{NA} are collected into their
own group row (appearing after all non-\code{NA} group rows).}

\item{label_values}{Logical. If \code{TRUE} (default), convert raw variable
values to labels using metadata or \code{haven} attributes. Falls back to
raw values when no labels exist.}

\item{label_vars}{Logical. If \code{TRUE} (default), use variable labels from
metadata in the \code{names_to} column (multi-variable mode only). Falls back
to the raw variable name when no label is set.}

\item{name_style}{\code{"surveycore"} (default) or \code{"broom"}. When \code{"broom"},
renames \code{pct} → \code{estimate}, \code{se} → \code{std.error}, etc.}

\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_freqs} tibble (also inheriting \code{survey_result}). Columns:
\itemize{
\item \verb{[group_cols...]} — group variable columns (when active), first.
\item \verb{[variable_name]} (single) or \verb{[names_to]} + \verb{[values_to]} (multi).
\item \code{pct} — weighted proportion (0–1).
\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{n} — unweighted cell count (sample basis of each estimate).
\item \code{n_weighted} — estimated population count (only when requested).
}
Use \code{meta(result)} to access design type, variable labels, value labels,
and other metadata.
}
\description{
Compute weighted proportions (percentages) for one or more categorical
variables in a survey design, with optional grouping, uncertainty
quantification, and metadata-driven labelling.
}
\details{
\strong{Single-variable mode} (when \code{x} resolves to exactly one variable):
The focal variable name becomes the first column. Rows follow the factor
level order (if the variable is a factor) or ascending sort order otherwise.

\strong{Multi-variable mode} (when \code{x} resolves to two or more variables):
Results are stacked in long format. The \code{names_to} column contains the
variable label (when \code{label_vars = TRUE}) or the raw variable name as
fallback. The \code{values_to} column contains the response values.

\strong{Domain estimation:} Proportions use the ratio linearization approach,
equivalent to \code{survey::svymean()} on a binary indicator within the active
domain. The full design structure is used for variance estimation — rows are
not physically removed for domain/group subsets.

\strong{\code{na.rm = FALSE}:} \code{NA} is appended as the last level. All proportions
(including non-\code{NA} levels) have their denominator inflated to include
\code{NA} rows, so the \code{pct} column sums to 1.
}
\examples{
# NHANES exam weights are 0 for non-examined participants; filter first
nhanes_sub <- nhanes_2017[nhanes_2017$wtmec2yr > 0, ]
d <- as_survey(nhanes_sub, ids = sdmvpsu, weights = wtmec2yr,
               strata = sdmvstra, nest = TRUE)

# Single variable
get_freqs(d, riagendr)

# With confidence intervals
get_freqs(d, riagendr, variance = "ci")

# Grouped
get_freqs(d, riagendr, group = sdmvstra)

# Multi-variable (stacked)
get_freqs(d, c(riagendr, ridreth3), names_to = "item", values_to = "value")

}
\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_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}
