auxvecLASSO (version 0.2.0)

print.assess_aux_vector: Print Summary of Auxiliary Vector Assessment

Description

S3 print method for objects of class assess_aux_vector. Displays a formatted, colorized summary of weight variation metrics, register diagnostics (overall and by domain), and survey diagnostics (overall and by domain).

Usage

# S3 method for assess_aux_vector
print(x, ...)

Value

Invisibly returns the input object x.

Arguments

x

An object of class assess_aux_vector containing diagnostic results. Expected to have components:

weight_variation

Named numeric vector or list of weight variation metrics.

register_diagnostics

List with total and by_domain components. Each inner data frame typically includes columns variable, mean, se, rse, bias, mse, and (when population means are available) p_bias.

survey_diagnostics

List with total and by_domain components. Each inner data frame typically includes columns variable, mean, se, rse; bias, mse, and p_bias are NA unless population means were provided.

...

Additional arguments (currently ignored).

Details

In addition to means and standard errors, the printer shows the relative standard error (RSE = SE / |mean|) and—when population means are supplied to estimate_mean_stats()—two-sided p-values for the bias testing \(H_0:\ \text{mean} = \text{population mean}\).

Requires the crayon package for colored output.

The print method outputs sections with colored headers for easier readability:

• Weight Variation Metrics

• Register Diagnostics summarized for all units and by domain

• Survey Diagnostics summarized for all units and by domain

For each variable shown, the following metrics are printed when present:

• Mean — survey-weighted mean.

• SE — design-based standard error from survey.

• RSE — relative standard error, \(\mathrm{SE}/|\mathrm{Mean}|\).

• Bias — difference between estimate and population mean (if supplied).

• MSE — \(\mathrm{Bias}^2 + \mathrm{SE}^2\) (if population means supplied).

• p(Bias) — two-sided p-value testing \(H_0:\ \mathrm{Bias}=0\), computed as \(2\Phi(-|z|)\) with \(z=\mathrm{Bias}/\mathrm{SE}\) (shown when population means are available).

Edge cases: if mean == 0 the RSE is reported as NA; if SE == 0, p(Bias) is 1 when |Bias| is numerically zero and 0 otherwise. Objects created with earlier versions that lack rse or p_bias columns are handled gracefully (those fields are simply not printed).

If the crayon package is not installed, the function will stop with an error.

Examples

## ============================================================
## Example 1: Print with register + survey diagnostics
##            (includes population means -> prints p(Bias))
## ============================================================
if (requireNamespace("survey", quietly = TRUE) &&
  requireNamespace("crayon", quietly = TRUE)) {
  set.seed(7)
  options(survey.lonely.psu = "adjust")

  ## --- Simulate a small survey
  n <- 180
  sex <- factor(sample(c("F", "M"), n, replace = TRUE), levels = c("F", "M"))
  region <- factor(sample(c("N", "S"), n, replace = TRUE), levels = c("N", "S"))
  age <- round(rnorm(n, mean = 42, sd = 12))
  reg_income <- 52000 + 1500 * (region == "S") + rnorm(n, sd = 3500) # register var
  y1 <- 10 + 1.8 * (sex == "M") + rnorm(n, sd = 2) # survey vars
  y2 <- 95 + 4.5 * (region == "S") + rnorm(n, sd = 3.5)
  w <- runif(n, 0.7, 2.1) * 40
  df <- data.frame(sex, region, age, reg_income, y1, y2, w)
  des <- survey::svydesign(ids = ~1, weights = ~w, data = df)

  ## --- Optional calibration inputs (simple main effects)
  ## Model matrix columns: (Intercept), sexM, regionS, age
  Npop <- 4000
  calibration_formula <- ~ sex + region + age
  calibration_pop_totals <- c(
    "(Intercept)" = Npop,
    "sexM"        = round(0.48 * Npop),
    "regionS"     = round(0.52 * Npop),
    "age"         = 41 * Npop
  )

  ## --- Population means for the register var: total + by domain
  register_vars <- "reg_income"
  register_pop_means <- list(
    total = c(reg_income = 52500),
    by_domain = list(
      region = c(N = 51500, S = 53500)
    )
  )

  ## --- Build assessment object
  aux1 <- assess_aux_vector(
    design                 = des,
    df                     = df,
    calibration_formula    = calibration_formula,
    calibration_pop_totals = calibration_pop_totals,
    register_vars          = register_vars,
    register_pop_means     = register_pop_means,
    survey_vars            = c("y1", "y2"),
    domain_vars            = "region",
    diagnostics            = c("weight_variation", "register_diagnostics", "survey_diagnostics"),
    already_calibrated     = FALSE,
    verbose                = FALSE
  )

  ## Colorized, formatted summary:
  print(aux1)
}

## ============================================================
## Example 2: Print with survey diagnostics only (by domain)
##            (no population means -> p(Bias) omitted)
## ============================================================
if (requireNamespace("survey", quietly = TRUE) &&
  requireNamespace("crayon", quietly = TRUE)) {
  set.seed(11)
  options(survey.lonely.psu = "adjust")

  n <- 120
  region <- factor(sample(c("N", "S"), n, replace = TRUE), levels = c("N", "S"))
  sex <- factor(sample(c("F", "M"), n, replace = TRUE), levels = c("F", "M"))
  yA <- 50 + 2.5 * (region == "S") + rnorm(n, sd = 2)
  yB <- 30 + 1.5 * (sex == "M") + rnorm(n, sd = 1.5)
  w <- runif(n, 0.8, 1.9) * 35
  toy <- data.frame(region, sex, yA, yB, w)

  des2 <- survey::svydesign(ids = ~1, weights = ~w, data = toy)

  aux2 <- assess_aux_vector(
    design                 = des2,
    df                     = toy,
    calibration_formula    = NULL, # skip calibration
    calibration_pop_totals = NULL,
    register_vars          = NULL, # no register diagnostics
    survey_vars            = c("yA", "yB"),
    domain_vars            = "region",
    diagnostics            = c("weight_variation", "survey_diagnostics"),
    already_calibrated     = TRUE,
    verbose                = FALSE
  )

  print(aux2)
}