Metadata-Version: 2.4
Name: py-simba-pop-tools
Version: 0.1.0
Summary: Calibration, validation and backtesting tools for the py-simba-pop banana cohort model.
Author-email: Collins Patrick Ohagwu <cpohagwu@gmail.com>
License: Apache-2.0
Project-URL: Documentation, https://github.com/cpohagwu/simba-ecosystem-docs
Project-URL: Core, https://pypi.org/project/py-simba-pop/
Project-URL: Issues, https://github.com/cpohagwu/simba-ecosystem-docs/issues
Keywords: agriculture,crop-model,banana,calibration,simba-pop
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: py-simba-pop<0.5,>=0.4.1
Requires-Dist: numpy>=1.26.4; python_version < "3.13"
Requires-Dist: numpy>=2.1.0; python_version >= "3.13"
Requires-Dist: pandas<3,>=2.2.2; python_version < "3.13"
Requires-Dist: pandas<3,>=2.2.3; python_version >= "3.13"
Requires-Dist: scipy>=1.13.1; python_version < "3.13"
Requires-Dist: scipy>=1.14.1; python_version >= "3.13"
Provides-Extra: test
Requires-Dist: pytest==8.3.5; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest==8.3.5; extra == "dev"
Requires-Dist: ruff==0.16.1; extra == "dev"
Dynamic: license-file

# py-simba-pop-tools

Calibration, validation and backtesting tools for
[py-simba-pop](https://pypi.org/project/py-simba-pop/), the SIMBA-POP banana
cohort model.

```
pip install py-simba-pop-tools
```

Releases are compiled wheels for CPython 3.11-3.13 on Windows, macOS and
Linux, with type stubs (`py.typed`) for editors and type checkers. There is no
source distribution. Documentation:
[simba-ecosystem-docs](https://github.com/cpohagwu/simba-ecosystem-docs).

## Contents

| Module | What it does |
|---|---|
| `py_simba_pop_tools.calibration.harvest` | Harvest timing from ribbon-tagged production records: a nonparametric life table, and a maximum-likelihood fit in the engine's own weekly model with field losses as a competing risk, with a cohort-block bootstrap; the field-loss (reproductive death) rate as an exposure hazard, by period, with a drift test |
| `py_simba_pop_tools.calibration.vegetative` | Flowering and follower-selection timing (threshold, peak, spread) fitted to recorded bagging and parous/nulliparous selections, with the engine driven by the recorded selections; and flowering from bagging alone, through a temporal split with follower selection fixed, with a block bootstrap. Keeps the deviance profile over the threshold |
| `py_simba_pop_tools.calibration.bootstrap` | Moving-block bootstrap weights for records ordered in time |
| `py_simba_pop_tools.calibration.literature` | Parameter values reproduced from published calibrations, each with its source table |
| `py_simba_pop_tools.evaluation.backtest` | Rolling-origin backtests with as-of data (each table filtered by its contract's lag; forecasters start from the last ledger week known, so a longer lag is forecast through): persistence, seasonal naive and Mode B baselines, and a calibrated Mode B that refits the field-loss rate and harvest timing at every origin; MAE, RMSE and bias by horizon and subgroup; Diebold-Mariano (Harvey-Leybourne-Newbold) with Holm across horizons |
| `py_simba_pop_tools.evaluation.curves` | Lag-scanned agreement between a simulated and an observed weekly series (validation only, not a fit) |
| `py_simba_pop_tools.data.contracts` | The canonical tables calibration and evaluation read: ribbon ledger, daily weather, plant monitoring |
| `py_simba_pop_tools.data.snapshots` | Immutable, hashed as-of snapshots of those tables, for backtests that use only data known at each origin |
| `py_simba_pop_tools.data.reconstruction` | An initial population reconstructed from production records, or spun up from a number of mats |
| `py_simba_pop_tools.synthetic` | Records made by py-simba-pop's own model, with switches that break the calibration's assumptions (bagging lag, harvest shift, incomplete or noisy desuckering records, recording error) -- tests and robustness studies only |

The package reads canonical tables only. Converting a farm's own exports into
them is the job of a separate, farm-specific adapter.

## Building from source (development)

A release build compiles every module (Cython, `setup.py`) and needs a C
compiler. Without one, a development install uses the plain sources:

```
PY_SIMBA_POP_TOOLS_PURE=1 pip install -e "packages/py-simba-pop-tools[test]"   # PowerShell: $env:PY_SIMBA_POP_TOOLS_PURE = "1"
pytest packages/py-simba-pop-tools
```

`release/check_wheel.py` audits a built wheel: compiled modules, `__init__`
files, type stubs and `py.typed` only.

## Licence and attribution

Apache-2.0 (see `LICENSE`).

Calibration, validation and backtesting tools for py-simba-pop. Values in `calibration.literature` are reproduced from the publications cited there (currently Guarín & Ochoa 2012, Table 2). Not affiliated with or endorsed by CIRAD or the original authors.
