surveycore (version 0.8.3)

get_t_test: Design-Based Two-Sample T-Test for Survey Designs

Description

Compares the weighted means of two groups using a design-based t-test. Follows the mathematical model of survey::svyttest() but uses surveycore's own variance machinery (survey_glm()). Supports all four survey design classes and optional subgroup analysis via group.

Usage

get_t_test(
  design,
  x,
  by,
  group = NULL,
  conf_level = 0.95,
  variance = "ci",
  na.rm = TRUE,
  min_cell_n = 30L,
  decimals = NULL,
  label_values = TRUE,
  label_vars = TRUE,
  name_style = "surveycore",
  ...,
  .id = NULL,
  .if_missing_var = NULL
)

Value

A survey_t_test tibble (also inheriting survey_result). Columns: group columns (when active), level_a, level_b, estimate, mean_a, mean_b, n_a, n_b, se (optional), ci_low (optional), ci_high (optional), t_stat, df, p_value, stars. Use meta() to access design type, conf_level, and variable metadata.

Arguments

design

A survey design object: survey_taylor, survey_replicate, survey_twophase, or survey_nonprob.

x

<tidy-select> A single unquoted numeric variable name for the outcome variable. Must resolve to exactly one numeric column.

by

<tidy-select> A single unquoted variable name for the grouping variable. Must produce a model matrix with exactly 2 columns after fitting (intercept + one binary indicator). Character, integer, and logical columns are coerced to factor with a warning. Ordered factors are accepted as-is.

group

<tidy-select> Optional subgroup variable(s). When supplied, the t-test is run separately within each unique combination of group values. Combined with any grouping set by group_by(). Default NULL.

conf_level

Numeric(1). Confidence level strictly in (0, 1). Default 0.95.

variance

Character. Which uncertainty columns to include. Valid values: "se", "ci". Default "ci". Both may be requested: c("se", "ci").

na.rm

Logical(1). Accepted for API uniformity with other get_*() functions. NA rows in x or by are always excluded (the GLM requires complete cases). Default TRUE.

min_cell_n

Integer(1). Warn when either group has fewer than this many unweighted observations. Default 30L. Use 0L to suppress.

decimals

Integer(1) or NULL. Round all double output columns to this many decimal places. NULL = no rounding. Default NULL.

label_values

Logical(1). When TRUE (default), convert by and group factor codes to their value labels in the output.

label_vars

Logical(1). Accepted for API uniformity; has no visible effect because column names are fixed. Default TRUE.

name_style

Character(1). Output column naming style. "surveycore" (default) or "broom" (renames se to std.error, ci_low to conf.low, ci_high to conf.high, p_value to p.value, df to parameter). t_stat is not renamed.

...

Unused. Reserved so that .id and .if_missing_var remain named-only when a survey_collection is passed as design.

.id

Character(1) or NULL. Column name used to identify each survey when design is a survey_collection. For collection inputs, NULL (the default) resolves to the collection's stored @id property. Pass a non-NULL value to override. Ignored when design is a single survey.

.if_missing_var

"error", "skip", or NULL. How to handle surveys in a collection that lack one of the requested NSE variables. For collection inputs, NULL (the default) resolves to the collection's stored @if_missing_var property. Pass a non-NULL value to override. Ignored when design is a single survey.

See Also

Other analysis: clean(), get_anova(), get_corr(), get_covariance(), get_diffs(), get_freqs(), get_means(), get_pairwise(), get_quantiles(), get_ratios(), get_totals(), get_variance(), meta()

Examples

gss_sub <- gss_2024[gss_2024$sex %in% c(1L, 2L) & !is.na(gss_2024$age), ]
gss_sub$sex <- factor(gss_sub$sex, levels = c(1, 2), labels = c("Male", "Female"))
gss_design <- as_survey(gss_sub,
  ids = vpsu, weights = wtssps, strata = vstrat, nest = TRUE)
get_t_test(gss_design, age, by = sex)