py-simba-pop

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 (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

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:

pip install -e ".[notebooks]"

Quick start

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:

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).

See 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 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 writes two synthetic farms in those formats, and 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 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 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

@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.