svy: Python Package for Complex Survey Design and Analysis

Design-based inference for stratified, cluster, and multi-stage surveys

Documentation
Survey Analysis
Python
Statistics
Professional Python toolkit for designing complex surveys, calculating sample sizes, weighting survey data, and performing statistical analysis with stratified, cluster, and multi-stage sampling designs.
Author

Mamadou S. Diallo, Ph.D.

Published

January 18, 2026

Modified

April 12, 2026

Keywords

complex survey analysis Python, survey design Python package, stratified sampling Python, cluster sampling analysis, PPS sampling Python, survey weighting calibration, variance estimation surveys, design-based inference, Taylor linearization Python, survey bootstrap replication, multi-stage sampling design, probability sampling Python, survey statistics Python, NHANES BRFSS DHS analysis, official statistics Python, R survey package Python alternative, svydesign Python, svymean Python equivalent, survey sampling Python, weighted survey estimation Python

What is svy?

svy is a Python package for design-based analysis of complex survey data. When surveys use stratification, clustering, or unequal probability selection, standard software produces incorrect standard errors. svy accounts for the actual sampling design in all calculations — means, totals, proportions, regression models, and more.

Get Started → Browse Tutorials → Source Code ↗

pip install svy

Quick Start

import svy

# Load survey data
smp_data = svy.io.read_csv("survey_data.csv")

# Define the survey design
smp_design = svy.Design(
    stratum=("region_id", "urban_rural"),  # Stratification variables
    psu="psu_id",                          # Primary sampling units
    wgt="weight",                          # Survey weights
)

# Create the sample object
sample = svy.Sample(data=smp_data, design=smp_design)

# Estimate population mean with design-based standard error
mean_income = sample.estimation.mean("income")
print(mean_income)
# Output: estimate, SE, 95% CI, design effect (DEFF)

# Regression accounting for complex design
model = sample.glm.fit(
    y="income",
    x=["age", svy.Cat("education")],
    family="gaussian"
)
print(model)
# Output: coefficients, design-based SEs, t-tests
Tip📌 Validated against R

svy produces numerically identical results to R’s survey package across Taylor linearization, BRR, bootstrap, and jackknife methods. Read the validation study →

Coming from R?

If you use R’s survey package, svy maps directly to the same concepts:

R (survey package) svy (Python)
svydesign() svy.Design() + svy.Sample()
svymean() sample.estimation.mean()
svytotal() sample.estimation.total()
svyglm() sample.glm.fit()
as.svrepdesign() svy.Design(rep_weights=...)

Results are validated to be numerically equivalent. See the full validation study and the getting started guide for a side-by-side comparison.

Core Capabilities

Data Wrangling

Rename, categorization, recoding, top- and bottom- coding, labelling. → Wrangling tutorial

Survey Design & Planning

Calculate required sample sizes, perform power analysis, and allocate samples optimally across strata. → Planning tutorial

Sample Selection

Draw probability samples using SRS, systematic, PPS, stratified, and multi-stage designs. → Selection tutorial

Survey Weighting

Compute design weights, adjust for nonresponse, and calibrate using poststratification, raking, and GREG. → Weighting tutorial

Replicate weights (Bootstrap, BRR, and Jackknife). → Replicate weights

Statistical Estimation

Estimate means, totals, proportions, ratios, and medians with Taylor linearization or replicate weight variance. → Estimation tutorial

Categorical Data Analysis

Tabulation, Crosstabulation, T-test. → Categorical Data Analysis tutorial

Regression Modeling

Fit linear, logistic, and Poisson GLMs with design-adjusted standard errors. → GLM tutorial

Who Uses svy?

svy is built for the communities that work with complex survey data:

  • 📊 Survey methodologists — national statistics offices, sampling design work
  • 📈 Biostatisticians — NHANES, BRFSS, DHS, and other public health surveys
  • 🎓 Social scientists — household surveys, labor force studies, demographic research
  • 🏛️ Government statisticians — official statistics production
  • 🔬 Epidemiologists — prevalence estimation, risk factor analysis
  • 👨‍🏫 Educators — teaching survey sampling and design-based inference

Documentation

Installation pip, uv, virtual environments
Getting Started First analysis in 10 minutes
Quick Tour The Sample object explained
Tutorials Full workflow, step by step
svy-sae Small area estimation
svy-io Read SPSS, Stata, SAS files

Frequently Asked Questions

Is svy a Python alternative to R’s survey package?

Yes. svy is designed to provide equivalent design-based inference to R’s survey package with a Pythonic API. Results have been validated to be numerically identical. See the validation study.

Can I use svy with NHANES, DHS, or BRFSS data?

Yes — svy is built for exactly these surveys. It supports the complex stratified cluster designs used by NHANES, DHS, BRFSS, and similar large-scale public health and demographic surveys.

Does svy support replicate weights?

Yes. svy supports Bootstrap, Balanced Repeated Replication (BRR), and Jackknife replicate weight methods for variance estimation. See the replicate weights tutorial.

What is design-based inference and why does it matter?

Design-based inference accounts for how the sample was drawn — stratification, clustering, unequal probabilities — when calculating standard errors. Ignoring the design typically underestimates standard errors, producing falsely narrow confidence intervals and incorrect hypothesis tests.

Is svy production-ready?

Core functionality for survey design, weighting, and variance estimation is stable and production-ready. The API continues to mature. See the development status note below.

How does svy differ from samplics?

svy supersedes samplics, an earlier library by the same author. svy provides a unified Sample object, expanded methodology (GLMs, SAE, data I/O), and active long-term support. samplics is archived.

Development Status

svy is under active development. Core survey design, weighting, and variance estimation are stable and production-ready. APIs and documentation continue to mature.

📧 Feedback: info@svylab.com  ·  🐛 Issues: GitHub Issues

Community & Support

TipHelp make svy the standard for survey analysis in Python

Starring the repository helps signal demand and prioritize validation and stability work. → Star svy on GitHub

Academic Citation

@software{svy2025,
  title   = {svy: Python Package for Complex Survey Analysis},
  author  = {Diallo, Mamadou S.},
  year    = {2025},
  url     = {https://github.com/samplics-org/svy},
  doi     = {10.5281/zenodo.XXXXXXX},
  version = {0.15.0}
}

License

svy is open source software released under the MIT License. See LICENSE for full terms.