svy-sae: Small Area Estimation in Python

Reliable estimates for districts, municipalities, and other domains too small for direct survey estimation

Documentation
Small Area Estimation
Python
Statistics
Official documentation for svy-sae, a Python package for small area estimation: Fay-Herriot, BHF, and EBP models with MSE, diagnostics, transformations, and benchmarking, validated against R’s sae package.
Author

Mamadou S. Diallo, Ph.D.

Modified

November 8, 2026

Keywords

small area estimation, SAE Python, Fay-Herriot Python, EBLUP Python, EBP poverty mapping, R sae package Python alternative, emdi Python

What is svy-sae?

svy-sae is a Python package for small area estimation (SAE). A survey designed for national or regional estimates samples too few households in each district to estimate the district directly. svy-sae combines the survey with census or administrative data through a model, and produces district estimates with their mean squared error (MSE).

svy-sae implements the standard area-level and unit-level estimators, checks its fits with built-in diagnostics, and runs on compiled JAX kernels that scale to a census of millions of households. It builds on svy, which supplies the direct estimates and the survey design.

Get Started → Browse Tutorials → Source Code ↗

pip install svy-sae "svy[remote]"
# or, with uv:
uv add svy-sae "svy[remote]"

svy[remote] loads the example datasets used in these docs, which need a network connection.

Quick Start

The milk data hold direct estimates of average household expenditure on milk for 43 small areas, with their sampling variances. A Fay–Herriot model combines each area’s direct estimate with a regression on its major area, giving the regression more weight where the direct estimate is imprecise:

import svy
import svy_sae as sae

milk = svy.datasets.load("milk").data

fit = sae.AreaLevel(milk).fh(
    y="yi",
    x=svy.Cat("MajorArea", ref=1),
    variance="variance",
    area="SmallArea",
)

print(fit)
╭──────────── SAE: Fay-Herriot (MSE: Prasad-Rao) - Area Level ─────────────╮
│ Method     REML  Log Likelihood   12.6775                                │
│ No. Areas    43  AIC             -15.3549                                │
│ No. Obs      43  BIC              -6.5489                                │
│                  KIC             -10.3549                                │
│                                                                          │
│                                                                          │
│  Term          Estimate   Std.Err       z   p-value    [0.025    0.975]  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│  Intercept       0.9682    0.0694   13.96    0.0000    0.8322    1.1041  │
│  MajorArea_2     0.1328    0.1030    1.29    0.1974   -0.0691    0.3347  │
│  MajorArea_3     0.2269    0.0923    2.46    0.0140    0.0460    0.4079  │
│  MajorArea_4    -0.2413    0.0816   -2.96    0.0031   -0.4013   -0.0813  │
│                                                                          │
│                                                                          │
│ Variance components: area variance: 0.0185503 (se 0.007618)              │
│                                                                          │
│ Findings:                                                                │
│ - Area effects not normal                                                │
│ - 2 influential areas                                                    │
╰──────────────────────────────────────────────────────────────────────────╯
# One row per area: the prediction, its MSE, CV, and 95% interval
fit.to_polars("predictions").head()
shape: (5, 8)
area pred mse cv lci uci indicator in_sample
str f64 f64 f64 f64 f64 str bool
"1" 1.021971 0.01346 0.113524 0.794575 1.249367 "mean" true
"2" 1.047602 0.005373 0.069969 0.903934 1.19127 "mean" true
"3" 1.067951 0.005702 0.070707 0.919949 1.215954 "mean" true
"4" 0.760817 0.008542 0.121477 0.57967 0.941963 "mean" true
"5" 0.846157 0.00958 0.115671 0.654321 1.037993 "mean" true

The quick tour explains this output and adds a unit-level model and poverty indicators.

Tip📌 Validated against R

Estimates are checked against R’s sae package on its own benchmark datasets, which load with svy.datasets:

svy-sae R sae
cornsoybean σ²ₑ 297.7133 297.7128
cornsoybean σ²ᵤ 63.3145 63.3149
milk σ²ᵤ 0.018550 0.018550

The bootstrap MSE agrees with sae::pbmseBHF within 0.4% on average across the twelve counties at 4,000 replicates, which is Monte Carlo error.

Coming from R?

If you use R’s sae or emdi packages, svy-sae maps to the same models:

R svy-sae (Python)
sae::eblupFH(), sae::mseFH(), emdi::fh() AreaLevel.fh()
sae::eblupSFH() AreaLevel.fh(random=sae.SAR(...))
emdi::step() AreaLevel.stepwise()
emdi::benchmark() AreaLevel.fh(benchmark=sae.Benchmark(...))
sae2::eblupRY() AreaLevel.fh(time=..., random=sae.AR1())
sae::eblupBHF(), sae::pbmseBHF() UnitLevel.eblup()
sae::ebBHF(), sae::pbmseebBHF(), emdi::ebp() UnitLevel.ebp()

Core Capabilities

Area-level models

The Fay–Herriot model by REML or ML, with analytical (Prasad–Rao) or parametric bootstrap MSE, and predictions for areas outside the sample. → Fay–Herriot tutorial

Generalized variance functions to smooth the sampling variances. → Smoothing variances

Stepwise covariate selection by AIC, BIC, or KIC. → Choosing covariates

Log, arcsine, and logit scales, with back-transformed estimates and their MSE. → Transformations

Ratio and raking benchmarks to regional or national totals. → Benchmarking

Spatial (SAR) and temporal (Rao–Yu, with time=) area effects through random=, for now without diagnostics or areas outside the sample.

Unit-level models

The Battese–Harter–Fuller model for area means, by REML or ML, with analytical or bootstrap MSE. → BHF tutorial

Poverty and nonlinear indicators

The Molina–Rao EBP with Box–Cox, log, or no transformation: poverty headcount, gap, and severity, the mean, median, Gini, quintile share ratio, and custom indicator functions. → EBP tutorial

Survey weights for informative sampling. → Weighted EBP

Diagnostics

Fay–Herriot fits with independent area effects and unit-level fits compute their residuals, influence, and tests, and reports what failed as findings, with diagnostic plots. → Checking area-level models, Checking unit-level models

Performance at scale

Compiled JAX kernels make census-scale work practical: on the 2.5-million-household census of the tutorials, the point estimates of an EBP of poverty rates take seconds on a laptop, and each bootstrap replicate a few seconds at the default 200 simulations.

Who Uses svy-sae?

  • 🏛️ National statistics offices: district and municipal estimates for official statistics
  • 🌍 Poverty analysts: poverty maps from household surveys and censuses
  • 📊 Survey methodologists: model-based estimates for domains the design did not plan for
  • 🔬 Epidemiologists: prevalence for local health areas
  • 🎓 Researchers and educators: teaching and comparing small area methods

Documentation

Installation pip, uv, virtual environments
Getting Started Installation, requirements, and first steps
Quick Tour Three models on three classic datasets
Tutorials Area-level and unit-level models, step by step on one survey

The svy Ecosystem

svy-sae is a companion to svy, the core library for complex survey design and analysis. svy prepares the inputs: it weights the survey, computes design-based direct estimates and their variances, and loads the example datasets used throughout these docs.

Frequently Asked Questions

Is svy-sae a Python alternative to R’s sae and emdi packages?

Yes. svy-sae fits the Fay–Herriot, Battese–Harter–Fuller, and Molina–Rao EBP models of R’s sae and emdi packages with a Pythonic API, and its estimates are checked against R’s sae on that package’s benchmark datasets. See Coming from R? above.

Does svy-sae use the survey design?

The direct estimates and their design-based variances for area-level models come from svy, which carries the survey design: see Preparing inputs. Unit-level EBP models can take the survey weights to guard against informative sampling: see Weighted EBP.

Can svy-sae estimate areas with no sample?

Yes. Area-level and unit-level models predict areas that appear in the population data but not in the sample, from the regression alone, with their MSE.

Is svy-sae production-ready?

The core models are validated and their interfaces are stabilizing. svy-sae is pre-1.0, so the API may change between minor versions; each release documents what moved in its changelog.

Development Status

svy-sae is under active development. The area-level and unit-level models are validated, and their interfaces are stabilizing. Diagnostics, documentation, and further models continue to grow.

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