Metadata-Version: 2.4
Name: welfareweights
Version: 0.1.1
Summary: Open implementation of the GBD disability-weight estimation pipeline (Salomon et al. 2012/2015): probit on paired comparisons, interval regression on population-health-equivalence responses, logit-space rescaling.
License: Apache-2.0
Project-URL: Homepage, https://welfareweights.com
Project-URL: Documentation, https://welfareweights.github.io/engine/
Project-URL: Repository, https://github.com/welfareweights/engine
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-DATA
License-File: NOTICE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: pandas>=2.0
Requires-Dist: statsmodels>=0.14
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# WelfareWeights Engine

[![tests](https://github.com/welfareweights/engine/actions/workflows/ci.yml/badge.svg)](https://github.com/welfareweights/engine/actions/workflows/ci.yml) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21401783.svg)](https://doi.org/10.5281/zenodo.21401783) [![PyPI](https://img.shields.io/pypi/v/welfareweights)](https://pypi.org/project/welfareweights/)

Install: `pip install welfareweights` (Python 3.11+)

Open-source tooling to estimate disability weights from survey data. These are the valuations that turn health states into DALYs (disability-adjusted life years) for burden-of-disease work. Eventually we will extend that methodology to health and welfare states that are not yet well modeled.

This is the academic core of the [WelfareWeights](https://welfareweights.com) project. The companion survey platform (welfareweights.com) is managed separately; this repository is the freely reusable engine and its documentation.

## Use

```python
from welfareweights.inference import bootstrap_dws

res = bootstrap_dws(pc_df, phe_df, n_boot=200, rng=0)
print(res.weights)  # one row per health state: dw, lo, hi
```

`pc_df` holds paired-comparison responses (`respondent_id, state_1, state_2, y`) and `phe_df` holds population-health-equivalence responses (`respondent_id, state, n_cases, y`); the docstrings in [pipeline.py](src/welfareweights/pipeline.py) define the columns precisely. `welfareweights.estimate_dws` gives point estimates and diagnostics without the bootstrap, and `welfareweights.simulate` generates synthetic survey data from the assumed data-generating process if you have none yet — [examples/quickstart.py](examples/quickstart.py) shows the whole loop, truth to recovery, in about fifteen seconds.

## Why

DALYs compress an enormous range of human experience into a single number, and the disability weights underneath them are estimated from public surveys using a methodology that most researchers cannot easily reproduce or extend. The goal here is to democratize and open-source that methodology. I want transparent, reproducible, and open code, so weights can be replicated, scrutinized, and computed for new states. This will help people doing burden-of-disease accounting, policy analysis, and welfare measurement more broadly.

## Scope

1. **Replicate** the gold-standard approach (Salomon et al.) that derives disability weights from paired-comparison and valuation survey data.
2. **Open-source** it as a clean, well-documented library with user-friendly guides, so anyone can run survey data through it.
3. **Extend** it to estimate weights for states the current instruments miss.

## Understand and audit the method

[docs/METHODS.md](docs/METHODS.md) explains the whole estimator (what the survey questions ask, what each stage assumes, why the tricks work, what must be true for the weights to mean anything, and how to attack it), written for people who did econometrics years ago or who know math and code but never took it; [methods.pdf](https://welfareweights.github.io/engine/methods.pdf) is the same document typeset, with full citations and the validation evidence as an appendix (that link opens the PDF in your browser's own viewer, where the hyperlinks work; GitHub's embedded PDF pane does not support links, so use this one rather than browsing to [docs/methods.pdf](docs/methods.pdf)). [examples/quickstart.py](examples/quickstart.py) runs the full pipeline with uncertainty intervals on synthetic data with known true weights, in about fifteen seconds. A browsable index of all of this, with every link opening in a new tab, is at [welfareweights.github.io/engine](https://welfareweights.github.io/engine/).

## Validation

The original survey microdata is not public, so the estimator is validated the hard way instead: known-truth recovery from the assumed data-generating process, metamorphic invariance tests, loud-failure tests for every identification hazard we found in review, a link-robustness cross-check, held-out fit diagnostics, Monte Carlo coverage tests of the bootstrap intervals, a misspecification battery, and a full-scale run at the published GBD 2010 design size (220 states, 14,000 respondents: rank correlation 0.9997, mean error 0.005). The evidence, including the one documented blind spot, is collected in [docs/VALIDATION.md](docs/VALIDATION.md); the studies behind it are reproducible from [studies/](studies/) with recorded seeds.

## Status

Early and under active construction. The estimation pipeline is implemented and validated against synthetic data (see above) while we request the original survey data; the roadmap is in [ROADMAP.md](ROADMAP.md). Expect interfaces to change. Watch or star the repo to follow along.

## License

Two licenses, by artifact type:

- **Code**: [Apache License 2.0](LICENSE). Use it freely, including commercially; it carries an explicit patent grant.
- **Data, estimated weights, and documentation**: [Creative Commons Attribution 4.0](LICENSE-DATA) (CC-BY-4.0). Reuse freely with attribution.

Note that raw survey responses are governed by respondent consent and privacy rules, not by these licenses, and are not published here.

## Citation

If you use this work, please cite it via the "Cite this repository" button (see [CITATION.cff](CITATION.cff)). The concept DOI [10.5281/zenodo.21401783](https://doi.org/10.5281/zenodo.21401783) always resolves to the latest release.

