/svy

name: svy
description: >-
  Complex survey analysis: strata/PSU/weights, variance estimation (Taylor, BRR, jackknife, bootstrap), survey GLM, domain analysis, calibration. Polars-native. Use for NHANES, CPS, ACS PUMS, BRFSS, DHS. Non-survey regression: statsmodels/pyfixest.
metadata:
  audience: research-coders
  domain: python-library
  library-version: "0.13.0"
  skill-last-updated: "2026-03-28"

svy Skill

svy: design-based analysis of complex survey data in Python. Covers survey design specification (strata, PSU, weights, FPC), variance estimation (Taylor linearization, BRR, jackknife, bootstrap), descriptive estimation (means, totals, proportions, ratios, medians), survey-weighted GLM regression (gaussian, binomial, Poisson), domain/subpopulation analysis, calibration, and survey data I/O (SAS, SPSS, Stata). Uses Polars DataFrames natively. Use when analyzing data from complex sample surveys (NHANES, CPS, ACS PUMS, MEPS, ECLS-K, BRFSS, DHS). For non-survey regression, use statsmodels; for fixed effects, use pyfixest; for panel/IV models, use linearmodels.

Comprehensive skill for complex survey data analysis with svy. Use decision trees below to find the right guidance, then load detailed references.

What is svy?

svy is the Python package for **design-based analysis of complex survey data**:

• **Survey-aware estimation**: Means, totals, proportions, ratios, medians with proper design-based standard errors
• **GLM regression**: Survey-weighted linear, logistic, and Poisson regression with design-adjusted inference
• **Flexible variance estimation**: Taylor linearization (default), bootstrap, BRR (including Fay's modification), and jackknife (JK1, JKn) replicate methods
• **Domain estimation**: Correct subpopulation analysis without pre-filtering (preserves design structure)
• **Native Polars**: Built on Polars DataFrames, not pandas
• **Survey data I/O**: Read SAS (.sas7bdat), SPSS (.sav), Stata (.dta), and CSV with metadata
• **Calibration**: Post-stratification, raking, and GREG calibration for weight adjustment
• **Validated**: Results numerically equivalent to R's survey package across all methods

Version Notes

This skill targets **svy 0.13.0** (released 2026-03-25). svy supersedes **samplics** (archived 2026-03-10), an earlier library by the same author (Mamadou S. Diallo, Ph.D.). Key differences from samplics:

• Unified `Sample` object replaces separate `TaylorEstimator` / `ReplicateEstimator` classes
• Polars-native (samplics used numpy arrays)
• Expanded GLM support and data I/O module (`svy.io`)
• The API is substantially different from samplics — do not assume samplics patterns carry over

How to Use This Skill

Reference File Structure

| File | Purpose | When to Read | |------|---------|--------------| | `estimation.md` | Means, totals, proportions, ratios, medians, domain estimation, cross-tabs, hypothesis tests | Descriptive survey statistics | | `regression.md` | Survey-weighted OLS, logistic, Poisson regression; extracting results; diagnostics | Survey regression models | | `design-weights.md` | Design specification, replicate weights, weight manipulation, variance setup, survey data I/O, federal survey patterns | Setting up the survey design object |

Reading Order

1. **New to svy?** Start with `design-weights.md` then `estimation.md` 2. **Need survey-weighted regression?** Read `design-weights.md` then `regression.md` 3. **Have replicate weights already?** Read `design-weights.md` (replicate design section) then `estimation.md` or `regression.md` 4. **Setting up a federal survey (NHANES, CPS, etc.)?** Read `design-weights.md` (federal survey patterns table) 5. **Coming from samplics?** Read `design-weights.md` for the new API; the `Sample` object replaces `TaylorEstimator`/`ReplicateEstimator`

Related Skills

| Skill | Relationship | |-------|-------------| | `data-scientist` | Provides methodology guidance (especially `survey-analysis.md`); svy provides implementation. Load data-scientist for "when and why" to use survey methods | | `statsmodels` | Complement for non-survey regression (OLS, GLM, time series, diagnostics). **WLS in statsmodels is NOT survey-weighted regression** — it does not account for stratification or clustering | | `pyfixest` | Complement for fixed effects models and DiD. pyfixest does not handle complex survey designs; use svy for survey-weighted estimation, pyfixest for FE/DiD | | `linearmodels` | Complement for panel models (RE, FD, Fama-MacBeth) and IV/GMM. Does not handle survey designs | | `polars` | svy uses Polars DataFrames natively. Load polars skill for data preparation before passing to svy |

Quick Decision Trees

"I need to analyze survey data"

What task?
├─ Descriptive statistics (mean, total, proportion)
│   └─ ./references/estimation.md
├─ Regression model
│   ├─ Linear (continuous outcome) → ./references/regression.md
│   ├─ Logistic (binary outcome) → ./references/regression.md
│   └─ Poisson (count outcome) → ./references/regression.md
├─ Set up the survey design object
│   └─ ./references/design-weights.md
├─ Read survey data from SAS/SPSS/Stata
│   └─ ./references/design-weights.md
├─ Subpopulation / domain analysis
│   └─ ./references/estimation.md
└─ Cross-tabulation
    └─ ./references/estimation.md

"I need survey-weighted regression"

What model?
├─ Linear regression (continuous Y)
│   └─ family="gaussian" → ./references/regression.md
├─ Logistic regression (binary Y)
│   └─ family="binomial" → ./references/regression.md
├─ Poisson regression (count Y)
│   └─ family="poisson" → ./references/regression.md
├─ Ordinal logistic / Cox survival / IV
│   └─ Not in svy — use rpy2 + R survey package (see rpy2 bridge below)
└─ Fixed effects + survey weights
    └─ Not directly supported — see Boundaries below

"I need to set up variance estimation"

What do you have?
├─ Design variables (strata, PSU, weights)
│   └─ Taylor linearization → ./references/desig