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.
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:
# One row per area: the prediction, its MSE, CV, and 95% intervalfit.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
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
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.