Quick Tour of svy-sae: Small Area Estimation in Python
Fay–Herriot, BHF, and EBP models on three classic datasets
Tutorials
Overview
Python
A five-minute tour of svy-sae for small area estimation in Python: a Fay-Herriot model of milk expenditure, a BHF model of county crop areas, and EBP poverty indicators, with the results API.
Author
Mamadou S. Diallo, Ph.D.
Modified
November 8, 2026
Keywords
small area estimation Python, svy-sae quick tour, Fay-Herriot Python, EBLUP Python, EBP poverty indicators
WarningAbout these examples
This tutorial illustrates the svy-sae API; it is not a rigorous small area analysis. The models are kept simple so each step stays readable, and in many places, from the choice of covariates to the variance model, better choices could be made to improve them.
A five-minute, hands-on tour of svy-sae: an area-level model, a unit-level model, and poverty indicators, each on a classic small area dataset that loads with svy.datasets. Each section links to a deeper tutorial, where every step runs on one realistic survey.
Which model?
The model follows from the data you have:
Table 1: Choosing a model
You have
Fit
Tutorial
One row per area: a direct estimate, its sampling variance, and covariates
The summary closes with the findings: checks svy-sae runs on every fit, here non-normal area effects and two influential areas. The predictions come with their MSE, coefficient of variation, and 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 MSE is analytical (Prasad–Rao) by default. A parametric bootstrap takes one argument:
The corn and soybean data are those of the original BHF paper: hectares of corn in 37 sampled segments of 12 counties, with the number of satellite pixels classified as corn and as soybeans. A second table holds each county’s mean pixel counts over all its segments:
The predictions are the county means of corn hectares per segment. See BHF (EBLUP) for the model and Checking unit-level models for its diagnostics.
Poverty indicators: income in Spain
A poverty rate is not linear in income, so the BHF model cannot predict it from covariate means. The EBP simulates the income of every population unit instead. The synthetic Spanish data hold the income of 17,199 sampled people in 52 provinces, and the covariates of 713,301 people in five of them:
income = svy.datasets.load("spain_synth_income").datapopulation = svy.datasets.load("spain_synth_covariates_oos").datapoverty_line =0.6* income["income"].median()print(f"Poverty line: {poverty_line:,.0f}")
Poverty line: 6,477
The poverty line is 60% of the median income, a common relative line. ebp() takes the population records, the indicators, and the poverty line. Some incomes are negative, down to about −1,600, so transform_shift moves them above zero before the Box–Cox transformation:
The model is fitted on all 52 provinces; the predictions cover the five in the population file. n_reps=0 skips the bootstrap MSE, whose replicates are drawn from the population file and so would refit the model on five provinces only. See Molina–Rao (EBP) for the indicators, transformations, custom indicators, and computing time, and Weighted EBP for survey weights.
The results object
Every fit returns an SAEResults. Printing it gives the summary; to_polars() gives each part as a table:
Table 2: Tables of SAEResults
to_polars(...)
Content
"predictions"
One row per area (and indicator): pred, mse, cv, lci, uci, in_sample
"fixed"
Regression coefficients with standard errors and intervals
"components"
Variance components
"diagnostics"
One row per area: residuals, area effects, Cook’s distance
"units"
Unit-level fits: one row per sampled unit
"tests"
Normality, R², variance inflation, and other model-level tests
"findings"
The checks that failed, with a code, a detail, and a hint
fit.findings() applies the same rules at other thresholds, and fit.refit() reruns the fit with some arguments changed, such as fit.refit(mse="bootstrap").
Diagnostic plots hang off .plots:
fit.plots.model_vs_direct();
Direct estimates against Fay–Herriot predictions for the milk data
Key takeaways
✅ Three entry points: AreaLevel.fh() for area tables, UnitLevel.eblup() for means from unit records, UnitLevel.ebp() for poverty and other nonlinear indicators.
✅ Uncertainty with the estimates: MSE, CV, and intervals, analytical or bootstrap.
✅ Checks built in: every fit runs its diagnostics and reports what failed as findings.
✅ Tables out: to_polars() returns every part of a fit as a polars DataFrame.
Next steps
The tutorials take each model step by step on one synthetic household survey, from the direct estimates to diagnostics, transformations, and benchmarking, and check every estimate against the census.