svySE

Sampling Error Estimation for Complex Surveys

Version Status

The CRAN release is recommended for regular use. The GitHub development version may include new features and improvements that are still under active testing.

svySE is an R package for estimating sampling errors, producing descriptive indicator tables, and exporting structured results from complex survey data.

The package provides two complementary workflows:

• svySE_calc() calculates weighted estimates and sampling errors using the survey design.
• svySE_simple() calculates unweighted frequencies and percentages, expanded frequencies, or both, without sampling errors.

Results can be exported individually or consolidated across multiple datasets, survey weights, indicators, or analysis runs using svySE_xlsx().

svySE is built on top of the survey package and provides a higher-level workflow for the routine production of survey indicators while preserving the principles of design-based estimation.

Why svySE?

Survey indicator production often involves repeating the same technical steps:

1. preparing indicator variables;
2. identifying grouping and domain variables;
3. defining the survey design;
4. calculating weighted estimates;
5. estimating standard errors and confidence intervals;
6. calculating CV and DEFF;
7. preparing descriptive tables;
8. exporting results to structured workbooks.

svySE organizes these tasks into a reproducible and configurable workflow.

The package is designed to be:

• reproducible;
• flexible;
• easy to configure;
• suitable for repeated indicator production;
• compatible with complex survey designs;
• useful for official statistics;
• useful for academic and applied research;
• suitable for analyses involving multiple datasets or expansion factors.

Although the package was developed from practical experience in survey sampling and official statistics, it can be used by any researcher, analyst, public institution, national statistical office, or survey practitioner working with indicator-based survey data.

Main Features

• Weighted totals
• Weighted proportions
• Standard errors
• Confidence intervals
• Coefficients of variation
• Design effects
• Unweighted sample sizes
• Grouped estimates
• Domain estimates
• Optional strata variables
• Optional cluster variables
• Unstratified designs
• Unclustered designs
• Unweighted simple indicator tables
• Weighted expanded-frequency tables without sampling errors
• Combined expanded and unexpanded counts
• Configurable missing-value handling in simple indicator tables
• Flexible column selection
• Consolidated export of multiple analyses
• Selective export of chosen results
• Customizable .xlsx outputs

Package Workflow

The two calculation functions have separate responsibilities:

Simple indicator tables also provide explicit control over missing indicator values through the na_rm argument. Missing values can be excluded from the calculation or treated as a validation condition that stops the analysis.

This separation avoids redundant calculations and allows users to run only the workflow required for each analysis.

Installation

Stable version from CRAN

install.packages("svySE")

Development version from GitHub

install.packages("remotes")

remotes::install_github("lburgoss/svySE")

The CRAN version is recommended for regular use. The GitHub version may contain features under development before they are submitted to CRAN.

Load the package with:

library(svySE)

Example Data

The following simulated dataset contains:

• a geographic grouping variable;
• a stratification variable;
• a cluster variable;
• a sampling weight;
• a division variable;
• two binary indicators.

library(svySE)

set.seed(123)

df <- data.frame(
  dept = rep(c("A", "B", "C"), each = 50),
  strata = rep(c("S1", "S2", "S3"), each = 50),
  cluster = rep(1:30, each = 5),
  service = rep(c("S1", "S2"), length.out = 150),
  weight = runif(150, 10, 50),
  ind_1 = sample(c(0, 1), 150, replace = TRUE),
  ind_2 = sample(c(0, 1), 150, replace = TRUE)
)

head(df)

Configure the Analysis

svySE_cfg() defines the common settings used during sampling error estimation.

cfg <- svySE_cfg(
  estimator = "prop",
  variance = "taylor",
  lonely_psu = "adjust",
  conf_level = 0.95,
  target = 1,
  valid_values = c(0, 1),
  truncate_lower_ci = TRUE,
  pct_mult = 100,
  deff = TRUE,
  cv = TRUE,
  na_rm = TRUE
)

cfg

The most relevant options are:

Calculate Sampling Errors

svySE_calc() estimates weighted indicators and sampling errors using the survey design.

res_error <- svySE_calc(
  data = df,
  indicators = c("ind_1", "ind_2"),
  group_vars = "dept",
  group_labels = "Department",
  strata = "strata",
  cluster = "cluster",
  weight = "weight",
  division = NULL,
  div_weight = NULL,
  cfg = cfg,
  verbose = FALSE
)

res_error

The result is an object of class:

class(res_error)

A specific sampling error table can be inspected with:

res_error$results$ind_1$error$TOTAL

The output may contain:

Supported Survey Designs

svySE_calc() supports several survey design structures.

Weight only

res_weight <- svySE_calc(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  strata = NULL,
  cluster = NULL,
  weight = "weight",
  cfg = cfg,
  verbose = FALSE
)

Stratified design

res_strata <- svySE_calc(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  strata = "strata",
  cluster = NULL,
  weight = "weight",
  cfg = cfg,
  verbose = FALSE
)

Clustered design

res_cluster <- svySE_calc(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  strata = NULL,
  cluster = "cluster",
  weight = "weight",
  cfg = cfg,
  verbose = FALSE
)

Stratified clustered design

res_complex <- svySE_calc(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  strata = "strata",
  cluster = "cluster",
  weight = "weight",
  cfg = cfg,
  verbose = FALSE
)

Domain Estimation

A division variable can be used to calculate separate results for its categories while retaining the design-based estimation workflow.

res_domain <- svySE_calc(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  strata = "strata",
  cluster = "cluster",
  weight = "weight",
  division = "service",
  div_weight = NULL,
  cfg = cfg,
  verbose = FALSE
)

Available divisions can be inspected with:

names(res_domain$results$ind_1$error)

When div_weight is supplied, that weight is used for the corresponding division estimates.

Simple Indicator Tables

svySE_simple() creates descriptive indicator tables without calculating standard errors, confidence intervals, CV, or DEFF.

It supports three output modes:

Unweighted frequencies and percentages

This is the default and preserves the original behavior:

res_simple <- svySE_simple(
  data = df,
  indicators = c("ind_1", "ind_2"),
  group_vars = "dept",
  group_labels = "Department",
  output = "unweighted",
  target = 1,
  valid_values = c(0, 1),
  pct_mult = 100,
  na_rm = TRUE,
  verbose = FALSE
)

res_simple$results$ind_1$simple$TOTAL

Expanded frequencies

Expanded frequencies are obtained by summing the specified weight within categories 0, 1, and the valid total:

res_expanded <- svySE_simple(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  weight = "weight",
  output = "weighted",
  verbose = FALSE
)

res_expanded$results$ind_1$simple$TOTAL

The result contains:

Expanded and unexpanded counts together

res_both <- svySE_simple(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  weight = "weight",
  output = "both",
  verbose = FALSE
)

res_both$results$ind_1$simple$TOTAL

By default, na_rm = TRUE. Missing indicator values are excluded from the calculation, and groups without valid observations for a specific indicator are omitted from that indicator table.

Use na_rm = FALSE to stop the calculation when missing indicator values are present:

svySE_simple(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  na_rm = FALSE
)

Records with missing weights do not contribute to expanded frequencies. When output = "both", valid indicator records still contribute to the unweighted columns.

Unweighted frequencies describe the observed sample. Expanded frequencies are weighted totals. Neither mode in svySE_simple() calculates sampling errors.

Simple Tables by Division

res_simple_domain <- svySE_simple(
  data = df,
  indicators = "ind_1",
  group_vars = "dept",
  group_labels = "Department",
  division = "service",
  weight = "weight",
  output = "both",
  verbose = FALSE
)

names(res_simple_domain$results$ind_1$simple)

Export Results to XLSX

svySE_xlsx() exports sampling error results, simple indicator tables, or both.

Export one sampling error result

file_err <- tempfile(fileext = ".xlsx")

svySE_xlsx(
  x = res_error,
  file_err = file_err,
  file_tab = NULL,
  cols_err = svySE_cols_err("full"),
  overwrite = TRUE
)

file.exists(file_err)

Export one simple result

file_tab <- tempfile(fileext = ".xlsx")

svySE_xlsx(
  x = res_simple,
  file_err = NULL,
  file_tab = file_tab,
  cols_tab = svySE_cols_tab("full"),
  overwrite = TRUE
)

file.exists(file_tab)

Export Multiple Analyses

Multiple results generated from different datasets, indicators, survey weights, or function calls can be exported together.

results <- list(
  Main_errors = res_error,
  Domain_errors = res_domain,
  Main_simple = res_simple,
  Domain_simple = res_simple_domain
)

Export all available results:

file_err <- tempfile(fileext = ".xlsx")
file_tab <- tempfile(fileext = ".xlsx")

svySE_xlsx(
  x = results,
  file_err = file_err,
  file_tab = file_tab,
  cols_err = svySE_cols_err("full"),
  cols_tab = svySE_cols_tab("full"),
  overwrite = TRUE
)

svySE_xlsx() automatically identifies:

• objects generated by svySE_calc();
• objects generated by svySE_simple().

Sampling error tables are written to file_err, while simple indicator tables are written to file_tab.

Export Selected Results

The select argument can be used to export only chosen elements from a named list.

svySE_xlsx(
  x = results,
  select = c("Main_errors", "Domain_errors"),
  file_err = tempfile(fileext = ".xlsx"),
  file_tab = NULL,
  overwrite = TRUE
)

Export only simple tables:

svySE_xlsx(
  x = results,
  select = c("Main_simple", "Domain_simple"),
  file_err = NULL,
  file_tab = tempfile(fileext = ".xlsx"),
  overwrite = TRUE
)

Customize Exported Columns

Sampling error columns

svySE_cols_err("full")

A custom selection can be defined with:

error_columns <- svySE_cols_err(
  type = "custom",
  cols = c(
    "est_pct",
    "se_pct",
    "ci_l_pct",
    "ci_u_pct",
    "cv",
    "deff",
    "n_unw"
  )
)

Use the selected columns during export:

svySE_xlsx(
  x = res_error,
  file_err = tempfile(fileext = ".xlsx"),
  file_tab = NULL,
  cols_err = error_columns
)

Simple table columns

Available profiles include:

svySE_cols_tab("full")
svySE_cols_tab("unweighted")
svySE_cols_tab("target")
svySE_cols_tab("freq")
svySE_cols_tab("pct")
svySE_cols_tab("expanded")
svySE_cols_tab("expanded_freq")
svySE_cols_tab("expanded_pct")
svySE_cols_tab("counts")
svySE_cols_tab("percentages")

Export only sample and expanded counts:

svySE_xlsx(
  x = res_both,
  file_err = NULL,
  file_tab = tempfile(fileext = ".xlsx"),
  cols_tab = svySE_cols_tab("counts")
)

A custom selection can be defined with:

simple_columns <- svySE_cols_tab(
  type = "custom",
  cols = c(
    "freq_1",
    "pct_1",
    "exp_1",
    "exp_pct_1",
    "freq_total",
    "exp_total",
    "exp_pct_total"
  )
)

svySE_xlsx(
  x = res_both,
  file_err = NULL,
  file_tab = tempfile(fileext = ".xlsx"),
  cols_tab = simple_columns
)

When cols_tab = NULL, all columns available in each simple result are exported automatically.

Main Functions

Output Types

Technical Ecosystem

svySE integrates functionality from established R packages.

svySE does not replace survey. It provides a structured interface for repeated indicator production and export workflows built on top of its design-based estimation capabilities.

Documentation

The package includes:

• a reference manual;
• function documentation;
• package vignettes;
• reproducible examples;
• unit tests.

Open the package help:

help(package = "svySE")

Browse available vignettes:

browseVignettes("svySE")

Open documentation for the principal functions:

?svySE_cfg
?svySE_calc
?svySE_simple
?svySE_xlsx

Development Status

The current development version introduces:

• optional cluster variables;
• support for unstratified and unclustered designs;
• the new svySE_simple() workflow;
• separation between weighted estimation and descriptive simple tables;
• consolidated export of multiple analyses;
• selective export through the select argument;
• customizable .xlsx workbooks.
• weighted expanded frequencies in svySE_simple();
• combined expanded and unexpanded simple tables;
• additional simple-table column profiles and custom export;
• faster unclustered survey designs by avoiding unnecessary PSU nesting;

Future releases will focus on additional estimators, expanded quality indicators, more export options, and broader support for complex survey workflows.

Author

Luis Burgos

Statistician • RENACYT Researcher (Peru)

Sampling Specialist

National Institute of Statistics and Informatics (INEI)

ENCAL — Public Expenditure Quality Monitoring Survey

The package was developed independently based on professional experience in complex survey sampling, official statistics, and statistical programming.

Email: lburgoss1996@gmail.com

Suggestions, bug reports, and feature requests are welcome through the GitHub issue tracker.

License

MIT License