% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analysis-ratios.R
\name{get_ratios}
\alias{get_ratios}
\title{Survey-Weighted Ratio Estimation}
\usage{
get_ratios(
  design,
  numerator,
  denominator,
  group = NULL,
  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}.}

\item{numerator}{<\code{\link[tidyselect:language]{tidy-select}}> A single unquoted
numeric variable name for the numerator. Must resolve to exactly one
numeric column.}

\item{denominator}{<\code{\link[tidyselect:language]{tidy-select}}> A single unquoted
numeric variable name for the denominator. Must resolve to exactly one
numeric column. All in-domain values must not sum to zero.}

\item{group}{<\code{\link[tidyselect:language]{tidy-select}}> Optional grouping
variable(s). Combined with any grouping set by \code{group_by()}. Rows where
the grouping variable is \code{NA} are excluded from all groups and do not
appear in the output. This matches \code{dplyr::group_by()} semantics.
Default \code{NULL}.}

\item{variance}{\code{NULL} or a character vector from \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
confidence intervals. Default \code{0.95}.}

\item{n_weighted}{Logical. If \code{TRUE}, add an \code{n_weighted} column with the
sum of weights for rows where both numerator and denominator are non-NA
in each group. Default \code{FALSE}.}

\item{decimals}{Integer or \code{NULL}. If an integer, rounds all numeric output
columns (e.g., \code{ratio}, \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 analysis variable is \code{NA} are dropped
from calculations, and observations where any group variable is \code{NA} are
excluded from the output. If \code{FALSE}, \code{NA} observations in the analysis
variable are included in calculations, 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. Accepted for API uniformity; has no visible
effect on \code{get_ratios()} output. Default \code{TRUE}.}

\item{label_vars}{Logical. Accepted for API uniformity; has no visible
effect on \code{get_ratios()} output. Default \code{TRUE}.}

\item{name_style}{\code{"surveycore"} (default) or \code{"broom"}. When \code{"broom"},
renames \code{ratio} → \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_ratios} tibble (also inheriting \code{survey_result}).
\itemize{
\item \verb{[group_cols...]} — group variable columns (when active), first.
\item \code{ratio} — estimated ratio (weighted total of numerator / weighted
total of denominator).
\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 count of rows where both numerator and denominator
are non-NA.
\item \code{n_weighted} — sum of weights (only when requested).
}
Numerator and denominator variable names are stored in \code{meta(result)}, not
as output columns. Use \code{meta(result)$numerator} and
\code{meta(result)$denominator} to access them.
}
\description{
Estimate the ratio of two survey-weighted totals (numerator / denominator)
for a survey design object. Uses the delta method (linearization) for
variance estimation for Taylor, SRS, calibrated, and two-phase designs, and
direct per-replicate computation for replicate-weight designs. Both
approaches are equivalent to \code{survey::svyratio()} for their respective
design types.
Supports optional grouping, domain estimation, and all five survey design
classes.
}
\examples{
d <- as_survey(pew_npors_2025, weights = weight, strata = stratum)

# Ratio of prayer frequency to in-person attendance frequency
get_ratios(d, numerator = pray, denominator = attendper)

# With grouped estimates
get_ratios(d, pray, attendper, group = gender)

# AAPOR-compliant output
get_ratios(d, pray, attendper, variance = c("ci", "moe"), n_weighted = TRUE)

}
\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_t_test}()},
\code{\link{get_totals}()},
\code{\link{get_variance}()},
\code{\link{meta}()}
}
\concept{analysis}
