Metadata-Version: 2.4
Name: py-simba-pop
Version: 0.4.0
Summary: A transparent, reproducible Python implementation of the SIMBA-POP banana cohort model.
Author-email: Collins Patrick Ohagwu <cpohagwu@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/cpohagwu/py-simba-pop
Project-URL: Documentation, https://github.com/cpohagwu/py-simba-pop/blob/main/docs/index.md
Project-URL: Repository, https://github.com/cpohagwu/py-simba-pop
Project-URL: Issues, https://github.com/cpohagwu/py-simba-pop/issues
Keywords: agriculture,crop-model,banana,cohort-model,population-dynamics,simba-pop
Classifier: Development Status :: 3 - 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: pandas<3,>=2.2.2; python_version < "3.13"
Requires-Dist: pandas<3,>=2.2.3; python_version >= "3.13"
Requires-Dist: pyyaml>=6.0.1; python_version < "3.13"
Requires-Dist: pyyaml>=6.0.2; python_version >= "3.13"
Provides-Extra: viz
Requires-Dist: matplotlib==3.9.2; extra == "viz"
Provides-Extra: notebooks
Requires-Dist: plotly<7,>=5.24.1; extra == "notebooks"
Requires-Dist: openpyxl>=3.1.5; extra == "notebooks"
Requires-Dist: scipy>=1.13.1; python_version < "3.13" and extra == "notebooks"
Requires-Dist: scipy>=1.14.1; python_version >= "3.13" and extra == "notebooks"
Requires-Dist: nbconvert>=7; extra == "notebooks"
Requires-Dist: ipykernel>=6; extra == "notebooks"
Provides-Extra: test
Requires-Dist: pytest==8.3.5; extra == "test"
Requires-Dist: openpyxl==3.1.5; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest==8.3.5; extra == "dev"
Requires-Dist: ruff==0.16.1; extra == "dev"
Requires-Dist: openpyxl==3.1.5; extra == "dev"
Dynamic: license-file

# py-simba-pop

[![PyPI](https://img.shields.io/pypi/v/py-simba-pop.svg)](https://pypi.org/project/py-simba-pop/)
[![Python](https://img.shields.io/pypi/pyversions/py-simba-pop.svg)](https://pypi.org/project/py-simba-pop/)
[![Tests](https://github.com/cpohagwu/py-simba-pop/actions/workflows/tests.yml/badge.svg)](https://github.com/cpohagwu/py-simba-pop/actions/workflows/tests.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**py-simba-pop** is a transparent, reproducible Python implementation of
**SIMBA-POP**, the banana cohort model published by Tixier, Malézieux & Dorel
(2004), *Ecological Modelling* 180:407–417. It follows the design spirit of
[PCSE](https://github.com/ajwdewit/pcse) (Python Crop Simulation
Environment): one `SimbaPopEngine` drives everything, every input file is
read by a dedicated, standardized reader class (`py_simba_pop.readers`) with
exactly one canonical schema regardless of which farm the data came from,
and there is no cold-start/warm-start split -- a bare seed population and a
full field inventory are the same `initial_population` argument.

SIMBA-POP tracks a perennial banana field as two interlinked chains of
weekly cohorts -- pre-flowering (vegetative) and post-flowering
(reproductive) -- driven by thermal-time (degree-day) accumulation, with
log-normal dispersion curves controlling how a cohort spreads across
flowering, sucker-selection, and harvest transitions instead of switching
all at once. Continuous multi-generational simulation falls out naturally:
each week's suckers reseed the vegetative chain and each week's flowering
reseeds the reproductive chain. Real ribbon-tag bagging and farm-wide
sucker-selection records can drive the model directly -- and whenever a
variable isn't available, the engine falls back to the paper's own
mechanistic prediction, always with an explicit `Notice`, never silently.

## Install

```bash
pip install -e ".[dev]"
```

To run the example notebooks and scripts (Plotly for graphs, openpyxl for
the farm `.xlsx` exports, SciPy for the initial-population reconstruction and
peak matching), install the `notebooks` extra instead:

```bash
pip install -e ".[notebooks]"
```

## Quick start

```python
from py_simba_pop import ParameterSet, WeatherProvider, SimbaPopEngine

params = ParameterSet.from_tixier_defaults()
weather = WeatherProvider.from_file_and_params("weather.csv", params)  # date, tmean columns

engine = SimbaPopEngine.from_seed_population(params, weather, seed_population=1000.0)
output = engine.run(n_weeks=200)  # a pandas DataFrame: week_index, Nt, Nt_pre, Nt_post, Ht, FLt, St, ...
```

Every parameter has a hardcoded Tixier et al. (2004) default -- the call
above is the entire configuration required. If you have your own
already-calibrated values, load them from a plain YAML file in the same
schema instead:

```python
params = ParameterSet.from_yaml("my_farm_params.yaml")
```

Under the default `rate_basis: cohort` every plant flowers once, is
harvested once and keeps exactly one follower, so a farm's number of
production units stays constant (see
[docs/model_overview.md](docs/model_overview.md#rate-basis-per-cohort-distributions-default-vs-the-current-pool)).

See
[examples/01_running_farm_simulation.ipynb](examples/01_running_farm_simulation.ipynb)
for the full workflow -- weather, an existing field's cohort inventory, and
real ribbon-tag bagging / farm-wide sucker-selection records all driving
the same engine, with graceful, explicitly-logged fallback for whatever's
missing. [examples/build_farm_inputs.py](examples/build_farm_inputs.py)
builds every input file for a farm from its legacy weekly Excel exports
(and reconstructs the initial population from production records when no
census exists), [examples/generate_synthetic_farm.py](examples/generate_synthetic_farm.py)
writes two synthetic farms in those formats, and
[examples/build_custom_parameters.py](examples/build_custom_parameters.py)
is a standalone recipe for deriving your own harvest parameters from field
data.

## Model overview

See [docs/model_overview.md](docs/model_overview.md) for the cohort-chain
concept, the exact weekly algorithm, the standardized file readers, and a
table mapping each parameter name back to its symbol in the source paper.
See [docs/usage.md](docs/usage.md) for the full API and output-handling
details.

## How to cite

If you use py-simba-pop in your research, please cite it as:

> Ohagwu, C. P. (2026). *py-simba-pop: A transparent, reproducible Python
> implementation of the SIMBA-POP banana cohort model* (Version 0.4.0)
> [Computer software]. https://github.com/cpohagwu/py-simba-pop

```bibtex
@software{ohagwu_py_simba_pop,
  author  = {Ohagwu, Collins Patrick},
  title   = {{py-simba-pop}: A transparent, reproducible {Python} implementation of the {SIMBA-POP} banana cohort model},
  year    = {2026},
  url     = {https://github.com/cpohagwu/py-simba-pop},
  version = {0.4.0}
}
```

## License

Apache License 2.0. See [LICENSE](LICENSE).
