Installation Guide

Install svy-sae for Small Area Estimation in Python with pip or uv, set up a project for the tutorials, and pre-compile the model kernels.

Keywords

install svy-sae, pip install small area estimation, uv Python project setup

Default setup

To use svy-sae, you first need to install it. You can install svy-sae from PyPI using pip:

pip install svy-sae

The svy-sae package depends on svy for survey design specification and direct estimation. This dependency is installed automatically.

We recommend using a virtual environment to install svy-sae. You can create one with:

python -m venv venv

You may replace venv with any name you prefer, such as .venv or svy_sae_env. Activate the virtual environment with:

source venv/bin/activate

---

Recommended setup for the tutorials

For the tutorials, we will use the uv package manager to create and configure a new Python project. If you prefer a different Python package manager (e.g., venv, pipx, poetry, or pipenv), feel free to use that instead.

Step 1: Install uv

You may skip this step if you already have uv installed.

pip install uv

For best results, install uv globally so it is available across projects. Refer to the official documentation for platform-specific instructions.

---

Step 2: Create a project folder

Navigate to the directory where you would like to create your project and run:

uv init svy_sae_tutorial
cd svy_sae_tutorial

This generates the following structure:

svy_sae_tutorial/
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

• .python-version → Python version for the virtual environment
• pyproject.toml → project configuration and dependencies
• main.py → placeholder script
• README.md → project overview

---

Step 3: Add svy-sae as a dependency

Use uv add to add svy-sae to your project:

uv add svy-sae

This adds svy-sae under [project] dependencies in your pyproject.toml and installs it:

[project]
name = "svy_sae_tutorial"
dependencies = ["svy-sae"]

If you want to pin a specific version:

uv add "svy-sae==0.4.0"

You may also add additional packages as needed, for example:

uv add polars
uv add ruff --dev

To remove a package:

uv remove polars

To upgrade a dependency:

uv lock --upgrade-package svy-sae

---

Optional: pre-compile the kernels

Model kernels compile on first use and are cached to disk, so only the very first fit of a given data shape on a machine pays compilation — a few extra seconds. To pay that cost up front instead (before a workshop, a demo, or a production window), warm the cache once after installing:

import svy_sae

svy_sae.warmup()

Passing your own dataset warms the exact shapes your later fits will use — see the warmup documentation for details.

---

Next steps

Next, take a quick tour of the svy-sae workflow and package structure:

Quick Tour