Metadata-Version: 2.4
Name: svy
Version: 0.12.0
Summary: End-to-end surveys: design, sample, analyze, report.
Author: Mamadou S Diallo
Author-email: Samplics LLC <msdiallo@samplics.org>
Keywords: sampling,sample,weighting,estimation,survey
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: numpy>=2.3
Requires-Dist: msgspec>=0.19.0
Requires-Dist: polars[pyarrow]>=1.33.1
Requires-Dist: svy-rs>=0.0.3
Requires-Dist: scipy>=1.16.0
Requires-Dist: svy-io>=0.0.10a
Provides-Extra: report
Requires-Dist: rich>=14.1; extra == "report"
Requires-Dist: great-tables>=0.18; extra == "report"
Provides-Extra: sae
Requires-Dist: svy-sae>=0.1.0; extra == "sae"
Provides-Extra: all
Requires-Dist: rich>=14.1; extra == "all"
Requires-Dist: great-tables>=0.18; extra == "all"
Requires-Dist: svy-sae>=0.1.0; extra == "all"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# svy

Modern Python tools for **complex survey analysis**, built for real-world statistical workflows.

**svy** is a rigorously design-based yet production-oriented library for survey design, weighting, and estimation — without sacrificing transparency or scalability.

🌐 Website: [svylab.com](https://svylab.com)
📘 Documentation: [svylab.com/docs/svy](https://svylab.com/docs/svy/)
📦 Source: [github.com/samplics-org/svy](https://github.com/samplics-org/svy)

---

## What is svy?

svy is designed for people who **actually work with complex survey data**, including national statistical offices, public health and development programs, survey methodologists, and data scientists working with complex samples.

> **Correct inference first — without hiding assumptions or sacrificing usability.**

### Validation

svy has been validated against R's `survey` package, producing numerically identical results across Taylor linearization, replication methods, and complex survey designs. See the [full comparison](https://svylab.com/learn/notes/posts/svy-vs-r-comparison/).

---

## Installation

```bash
pip install svy
```

---

## Quick Start

```python
import svy

# Load example data
hld_data = svy.load_dataset(name="hld_sample_wb_2023")

# Define the survey design
hld_design = svy.Design(stratum=("geo1", "urbrur"), psu="ea", wgt="hhweight")

# Create a sample object
hld_sample = svy.Sample(data=hld_data, design=hld_design)

# Estimate the mean of total expenditure
tot_exp_mean = hld_sample.estimation.mean(y="tot_exp")

print(tot_exp_mean)
```

---

## Capabilities

- **Complex survey design** — strata, clusters, weights
- **Design-based estimation** with valid standard errors
- **Replication methods** — BRR, bootstrap, jackknife, SDR
- **Categorical data analysis** — tabulation, crosstabulation, t-test, Rao-Scott test
- **Generalized linear models** — logistic, Poisson, Gamma with survey weights
- **Explicit, inspectable, reproducible outputs**
- **Built on Polars, NumPy, SciPy, and Rust**

---

## Related Packages

| Package                                     | Purpose                         | Install               |
| ------------------------------------------- | ------------------------------- | --------------------- |
| **svy**                                     | Core survey design & estimation | `pip install svy`     |
| [svy-sae](https://svylab.com/docs/svy-sae/) | Small Area Estimation           | `pip install svy-sae` |
| [svy-io](https://svylab.com/docs/svy-io/)   | SPSS / Stata / SAS I/O          | `pip install svy-io`  |

---

## Documentation

Full documentation, tutorials, and methodological notes:
👉 [svylab.com/docs/svy](https://svylab.com/docs/svy/)

---

## Feedback

- Issues: [github.com/samplics-org/svy/issues](https://github.com/samplics-org/svy/issues)
- Discussions: [github.com/samplics-org/svy/discussions](https://github.com/samplics-org/svy/discussions)

---

## License

MIT License — Copyright © 2026 Samplics LLC
