Metadata-Version: 2.4
Name: pyfies
Version: 0.1.1
Summary: Python implementation of FAO's Food Insecurity Experience Scale (FIES) — weighted Rasch model, equating to the global standard, and prevalence estimation for SDG indicator 2.1.2.
Project-URL: Homepage, https://github.com/nejohnson2/pyFIES
Project-URL: Issues, https://github.com/nejohnson2/pyFIES/issues
Project-URL: Documentation, https://nejohnson2.github.io/pyFIES/
Author-email: "Nicholas E. Johnson" <nicholas.e.johnson@stonybrook.edu>
License: Apache-2.0
License-File: LICENSE
Keywords: FAO,FIES,Rasch model,SDG 2.1.2,food insecurity,item response theory,psychometrics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == 'plot'
Description-Content-Type: text/markdown

# pyFIES

Python implementation of FAO's **Food Insecurity Experience Scale (FIES)** — the
methodology behind UN SDG indicator **2.1.2** (prevalence of moderate-or-severe
and severe food insecurity in the population).

`pyfies` is a from-scratch port of the R package
[`RM.weights`](https://cran.r-project.org/package=RM.weights) (Cafiero, Viviani, Nord),
implementing the weighted Conditional Maximum Likelihood (CML) Rasch estimator,
equating to FAO's 2014–2016 global standard, and probabilistic prevalence
assignment along the latent food-insecurity trait.

> **Status:** alpha. v0.1 covers the dichotomous Rasch model, equating, and
> prevalence estimation. The polytomous (partial credit) extension and full
> diagnostics suite are planned for v0.2.

## Installation

```bash
pip install pyfies          # from PyPI (once published)
pip install -e ".[dev]"     # editable install with dev tooling
```

Requires Python 3.11+.

## Quickstart

```python
import pandas as pd
from pyfies import RaschModel, FAO_2014_2016, DEFAULT_FIES_ITEMS

# df has 8 columns named WORRIED, HEALTHY, FEWFOOD, SKIPPED,
# ATELESS, RUNOUT, HUNGRY, WHLDAY (1=affirmative, 0=negative, NA=missing)
X = df[DEFAULT_FIES_ITEMS].to_numpy()
w = df["sampling_weight"].to_numpy()

model = RaschModel().fit(X, sample_weight=w)
model.equate(reference=FAO_2014_2016)
result = model.prevalence()

print(f"Moderate or severe food insecurity: {result.moderate_or_severe:.1%}")
print(f"Severe food insecurity:             {result.severe:.1%}")
```

## What it computes

1. **Item severity parameters** for each FIES question via weighted CML.
2. **Person parameters** per raw score (post-hoc MLE conditional on item parameters).
3. **Equating** to the FAO 2014–2016 global metric so prevalence rates are
   comparable across countries and survey rounds.
4. **Prevalence rates** at any latent-trait threshold via Gaussian-mixture
   probabilistic assignment.

## Methodology references

- FAO. *The Food Insecurity Experience Scale — Development of a Global Standard
  for Monitoring Hunger Worldwide.* Technical Paper v1.1, 2016.
  [link](https://www.fao.org/fileadmin/templates/ess/voh/FIES_Technical_Paper_v1.1.pdf)
- Cafiero, C., Viviani, S., Nord, M. (2018). *Food security measurement in a
  global context: The Food Insecurity Experience Scale.* Measurement, 116, 146–152.
  [doi:10.1016/j.measurement.2017.10.065](https://doi.org/10.1016/j.measurement.2017.10.065)
- FAO. [Voices of the Hungry / FIES landing page](https://www.fao.org/measuring-hunger/access-to-food/about-the-food-insecurity-experience-scale-(fies)/en).

## Numerical parity with `RM.weights`

pyFIES is validated against the reference R package on the `data.FAO_country1..4`
sample datasets shipped with `RM.weights`. To regenerate parity fixtures (R
required, one-time):

```bash
Rscript scripts/generate_r_fixtures.R
```

Default tolerance: `atol=1e-6` on item severities and prevalence rates.

## Citing

If you use pyFIES in published research, please cite both this package and the
underlying FAO methodology (Cafiero et al., 2018). A `CITATION.cff` file will be
added at first stable release.

## License

[Apache 2.0](LICENSE).
