pysephone 0.1.0__tar.gz

pysephone-0.1.0/DATA_SOURCES.md

@@ -0,0 +1,57 @@
+# Data sources, attribution & licenses
+
+The **pysephone source code is licensed under the MIT License** (see `LICENSE`).
+
+This package also **bundles a number of third-party reference datasets** under
+`src/pysephone/data/`. Those datasets are **not** covered by the MIT license —
+each retains the terms of its original source, as documented below. If you use,
+redistribute, or build upon pysephone, you are responsible for honoring the terms
+of any bundled dataset you rely on, including any attribution and use
+restrictions noted here.
+
+> ⚠️ **Note on commercial use.** Most bundled datasets permit reuse with
+> attribution, but **`liestal.csv` is licensed for non-commercial use only**, and
+> **`kyoto.csv`** is an academic dataset provided for research use with required
+> citations and **no explicit redistribution grant**. These two files are
+> redistributed here on those terms; commercial users in particular must review
+> them before relying on these files.
+
+---
+
+## GMU cherry blossom data — `src/pysephone/data/gmu_cherry/data/`
+
+Cleaned peak-bloom / first-flowering records (schema:
+`location, lat, long, alt, year, bloom_date, bloom_doy`). Per-file provenance:
+
+| File | Source | License / terms | Attribution / citation |
+|---|---|---|---|
+| `washingtondc.csv` | US EPA, Climate Change Indicators — Cherry Blossoms | US federal source (public domain); see source for details | "Source: U.S. EPA, Climate Change Indicators in the United States — https://www.epa.gov/climate-indicators/cherry-blossoms" |
+| `meteoswiss.csv` | MeteoSwiss / opendata.swiss (phenological observations) | **Open use, incl. commercial**; must provide source | "Source: MeteoSwiss" |
+| `japan.csv` | Japan Meteorological Agency | Cite source | "Source: Japan Meteorological Agency — https://www.data.jma.go.jp/sakura/data/pdf/005.pdf" |
+| `south_korea.csv` | Korea Meteorological Administration | Cite source | "Source: Korean Meteorological Administration" |
+| `liestal.csv` | Landwirtschaftliches Zentrum Ebenrain, Sissach & MeteoSwiss | **Non-commercial use only**; must provide source | "Source: Landwirtschaftliches Zentrum Ebenrain, Sissach and MeteoSwiss" |
+| `kyoto.csv` | Yasuyuki Aono, Osaka Prefecture University | Academic / research use; **no explicit redistribution grant**; cite the papers below | Aono & Saito (2010), *Int. J. Biometeorology* 54:211–219; Aono & Kazui (2008), *Int. J. Climatology* 28:905–914. Source: http://atmenv.envi.osakafu-u.ac.jp/aono/kyophenotemp4/ |
+
+See `src/pysephone/data/gmu_cherry/data/README.md` for the full per-source notes.
+This collection originates from George Mason University's public
+`peak-bloom-prediction` competition repository.
+
+---
+
+## PEP725 metadata — `src/pysephone/data/pep725/metadata/`
+
+Only **lookup/metadata tables** (PEP725 species codes, country codes, and the
+catalog of entries to download) are bundled here. The actual PEP725 phenology
+**observations are not redistributed** — they are downloaded at runtime using
+your own PEP725 account credentials (see `src/pysephone/data/pep725/README.md`).
+PEP725 data is subject to the PEP725 data policy (https://www.pep725.eu/).
+
+---
+
+## World administrative boundaries — `src/pysephone/data/resources/`
+
+`world-administrative-boundaries.geojson` — obtained from OpenDataSoft
+(https://public.opendatasoft.com/explore/dataset/world-administrative-boundaries/),
+derived from Natural Earth (public domain) and related sources. Used only for
+optional map backgrounds in visualizations. Please review OpenDataSoft's terms
+for the dataset before redistribution.

pysephone-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TODO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pysephone-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: pysephone
+Version: 0.1.0
+Summary: A Python library for using machine learning to predict the timing of phenological events in plants
+Author-email: Ron van Bree <ronvbree@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 TODO
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/ronvree/pysephone
+Project-URL: Repository, https://github.com/ronvree/pysephone
+Keywords: phenology,machine-learning,bloom,agriculture,remote-sensing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: DATA_SOURCES.md
+Requires-Dist: pandas
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: matplotlib
+Requires-Dist: tqdm
+Requires-Dist: requests
+Requires-Dist: requests-cache
+Requires-Dist: retry-requests
+Requires-Dist: unidecode
+Requires-Dist: nlopt
+Requires-Dist: tables
+Requires-Dist: h5py
+Requires-Dist: platformdirs
+Provides-Extra: deep
+Requires-Dist: torch>=2.0; extra == "deep"
+Provides-Extra: boost
+Requires-Dist: xgboost>=1.7; extra == "boost"
+Provides-Extra: agera5
+Requires-Dist: cdsapi; extra == "agera5"
+Requires-Dist: xarray; extra == "agera5"
+Requires-Dist: netCDF4; extra == "agera5"
+Provides-Extra: openmeteo
+Requires-Dist: openmeteo-requests; extra == "openmeteo"
+Provides-Extra: geo
+Requires-Dist: geopandas; extra == "geo"
+Requires-Dist: shapely; extra == "geo"
+Requires-Dist: rasterio; extra == "geo"
+Provides-Extra: earthengine
+Requires-Dist: earthengine-api; extra == "earthengine"
+Provides-Extra: stats
+Requires-Dist: scikit-posthocs; extra == "stats"
+Requires-Dist: autorank; extra == "stats"
+Provides-Extra: all
+Requires-Dist: pysephone[agera5,boost,deep,earthengine,geo,openmeteo,stats]; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+
+# pysephone
+
+![python](https://img.shields.io/badge/python-3.14%2B-blue)
+[![license](https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray)](LICENSE)
+
+</div>
+<br>
+
+## Description
+
+**pysephone** is a Python package for developing and benchmarking crop phenology models — models that predict the timing of key developmental events in plants, such as flowering, leaf-out, or harvest maturity. Accurate phenology predictions are essential for agricultural planning, yield forecasting, and understanding how ecosystems respond to climate variability and long-term change. As growing seasons shift under climate change, the ability to reliably model phenological timing across species and regions becomes increasingly important for both science and policy.
+
+pysephone provides a standardised pipeline that connects observational phenology databases with meteorological drivers, and a suite of models ranging from classical process-based approaches to deep learning, all sharing a common interface.
+
+The package is designed to make it straightforward to:
+- load and preprocess phenological observation data from multiple sources,
+- pair observations with season-windowed meteorological time series (ERA5 reanalysis supported out of the box; other drivers can be integrated),
+- define phenology datasets for standardised intercomparison of models,
+- fit and evaluate a variety of models, and
+- systematically compare model behaviour across species, regions, and climate conditions.
+
+<br>
+
+## Installation
+
+```bash
+git clone https://github.com/ronvree/pysephone.git
+cd pysephone
+pip install -e .
+```
+
+Requires Python ≥ 3.14.
+
+The base install is intentionally lightweight (process-based + scikit-learn models, datasets, evaluation). Heavier and source-specific dependencies are opt-in via extras:
+
+| Extra | Adds | Needed for |
+|---|---|---|
+| `deep` | PyTorch | LSTM / GRU / CNN / Transformer / hybrid / Beta-GDD / BSpline-GDD models |
+| `boost` | XGBoost | `XGBoostModel` |
+| `agera5` | cdsapi, xarray, netCDF4 | Downloading AgERA5 from Copernicus CDS |
+| `openmeteo` | openmeteo-requests | Downloading Open-Meteo ERA5 |
+| `geo` | geopandas, shapely, rasterio | Map visualizations, WorldClim rasters |
+| `earthengine` | earthengine-api | Fetching AlphaEarth embeddings |
+| `stats` | scikit-posthocs, autorank | Friedman/Nemenyi comparison + critical-difference plots |
+| `all` | everything above | Convenience meta-extra (every model + data source) |
+
+Install one or more with e.g. `pip install "pysephone[deep]"` or `pip install "pysephone[deep,agera5]"`. Accessing a model whose extra isn't installed raises a clear error telling you which extra to add.
+
+Reproducing **BloomBench** specifically needs `pip install "pysephone[deep,boost,agera5,stats]"` — its models are CNN/LSTM/Transformer (`deep`), XGBoost (`boost`), RandomForest/Mean/Linear (base); climate features come from AgERA5 (`agera5`); and the `compare` step's Nemenyi/critical-difference plots need `stats`. It does **not** use AlphaEarth/Earth Engine or Open-Meteo.
+
+<br>
+
+## Data Sources
+
+| Source | Description |
+|---|---|
+| **PEP725** | Pan-European Phenology Database — multi-species observations across Europe |
+| **GMU Cherry Blossom** | Cherry blossom bloom dates from Japan, Switzerland, and South Korea |
+| **USA-NPN** | USA National Phenology Network — deciduous fruit-tree observations |
+| **AgERA5** | Daily agrometeorological indicators from Copernicus CDS (downscaled temperature/radiation, Penman–Monteith inputs, etc.) |
+| **Open-Meteo ERA5** | ERA5 reanalysis via the Open-Meteo archive |
+
+Meteorological data is cached locally in HDF5 for fast repeated access. Additional providers can be integrated by implementing the `FeatureProvider` interface.
+
+Some reference datasets (e.g. the cherry-blossom bloom records) are bundled with the package. These third-party datasets retain their original licenses and attribution requirements — see [DATA_SOURCES.md](DATA_SOURCES.md). Note that `liestal.csv` is non-commercial-use only and `kyoto.csv` is provided for academic use with required citations.
+
+<br>
+
+## Authentication & configuration
+
+Some data sources reach external APIs that require **your own** account/project — pysephone ships no credentials and no default project. Set these up once before running the download steps:
+
+**Copernicus CDS (AgERA5).** Authentication uses the [`cdsapi`](https://cds.climate.copernicus.eu/how-to-api) convention — pysephone handles no keys itself. Provide your credentials via either:
+- a `~/.cdsapirc` file, or
+- the `CDSAPI_URL` and `CDSAPI_KEY` environment variables.
+
+**Google Earth Engine (AlphaEarth embeddings).** Requires a Google Cloud project with the Earth Engine API enabled:
+1. Authenticate once: `python -c "import ee; ee.Authenticate()"`.
+2. Tell pysephone which project to use, in priority order:
+   - pass `ee_project="your-gcp-project"` to `fetch_alphaearth_embeddings_batched(...)`, or
+   - set the `PYSEPHONE_EE_PROJECT` environment variable (Earth Engine's native `EARTHENGINE_PROJECT` is also honored), or
+   - leave it unset to let Earth Engine resolve its own default project.
+
+**Data location.** All caches, downloaded data, and outputs are written under a single data root. By default this is an OS-native per-user directory (`%LOCALAPPDATA%\pysephone` on Windows, `~/.local/share/pysephone` on Linux/macOS). Override it with the `PYSEPHONE_DATA_ROOT` environment variable — e.g. set `PYSEPHONE_DATA_ROOT=<repo>` to keep data inside a source checkout during development.
+
+<br>
+
+## Models
+
+| Category | Models |
+|---|---|
+| Baseline | Mean |
+| Process-based | GDD, Utah+GDD, ChillingDays+GDD, Dynamic+GDD |
+| Machine learning | Random Forest |
+| Deep learning | LSTM, Hybrid (TTCNN chilling + GDD forcing) |
+
+All models share a common `fit` / `predict` interface, making it easy to add new models or swap them in evaluation pipelines.
+
+<br>
+
+## Pipeline Overview
+
+```
+Data source (PEP725 / GMU Cherry)
+    ↓  preprocessing  (outlier removal, grid aggregation)
+Observations  (indexed by source, location, year, species, obs type)
+    ↓  paired with Calendar + meteorological feature provider
+Dataset  (yields season-windowed feature arrays per sample)
+    ↓
+Model.fit(target_fn, dataset)  →  Model.predict(sample)
+    ↓
+SingleTargetRegression.run(...)  →  metrics, error DataFrames, plots
+```
+
+The `Calendar` defines the season window (start date + length) for each entry. Feature providers retrieve the corresponding meteorological time series for each sample.
+
+<br>
+
+## Reproducing BloomBench
+
+[BloomBench](https://github.com/WUR-AI/BloomBench) is a multi-species benchmark for evaluating ML phenology models on fruit-tree flowering. The benchmark is shipped as a first-class library module: [`pysephone.benchmarks.bloombench`](src/pysephone/benchmarks/bloombench/).
+
+It exposes both a Python API and a thin CLI. Reproducing the benchmark needs the deep-learning, boosting, AgERA5, and stats extras (it does **not** use Earth Engine or Open-Meteo):
+
+```bash
+pip install "pysephone[deep,boost,agera5,stats]"
+```
+
+```bash
+# 1. Populate the AgERA5 cache once (Copernicus CDS credentials required).
+jupyter nbconvert --execute notebooks/download_agera5.ipynb
+
+# 2. Tune hyperparameters per (dataset, model) — overnight run.
+python -m pysephone.benchmarks.bloombench hpo
+
+# 3. Fit & evaluate every (seed, dataset, model) triple.
+python -m pysephone.benchmarks.bloombench run --seeds 0 1 2
+
+# 4. Friedman + Nemenyi + critical-difference plots.
+python -m pysephone.benchmarks.bloombench compare --seeds 0 1 2
+```
+
+The same flow as Python:
+
+```python
+from pysephone.benchmarks.bloombench import (
+    load_bloombench_datasets, run_benchmark, run_comparison, run_hpo,
+)
+
+datasets, _ = load_bloombench_datasets()
+run_hpo(datasets)                                      # one-time HPO
+results = run_benchmark(seeds=[0, 1, 2], datasets_dict=datasets)
+report = run_comparison(seeds=[0, 1, 2])
+```
+
+For the interactive flow with tables / heatmaps / critical-difference plots, see [`notebooks/bloombench_extended_hpo.ipynb`](notebooks/bloombench_extended_hpo.ipynb) (one-time HPO) and [`notebooks/bloombench_extended.ipynb`](notebooks/bloombench_extended.ipynb) (replication).
+
+<br>
+
+## Project Structure
+
+```
+.
+├── src/pysephone/
+│   ├── benchmarks/     # End-to-end benchmark suites (BloomBench, …)
+│   ├── data/           # Data ingestion and sources (PEP725, GMU Cherry, USA-NPN, AgERA5)
+│   ├── dataset/        # Observations, Dataset, Calendar, feature providers, registry
+│   ├── evaluation/     # Evaluation logic and regression metrics
+│   ├── models/         # Model implementations (CF, RF, LSTM, Hybrid, …)
+│   ├── utils/          # Shared utilities
+│   └── visualize/      # Visualisation helpers
+├── notebooks/          # Jupyter notebooks for exploration and analysis
+├── scripts/            # Standalone scripts
+├── tests/              # Test suite
+└── data/               # Raw and processed data (git-ignored)
+```
+
+<br>
+
+## Notebooks
+
+| Notebook | Description |
+|---|---|
+| `cherry_blossom_cf_models.ipynb` | Process-based model evaluation on GMU Cherry datasets |
+| `cf_models_pep725_fruit_trees.ipynb` | CF model evaluation across PEP725 fruit tree species |
+| `unusual_year_model_eval.ipynb` | Model comparison on climatologically unusual vs normal years |
+| `unusual_seasons_*.ipynb` | Exploration of unusual seasons in GMU / PEP725 data |
+| `dataset_adequacy_*.ipynb` | Sample sufficiency analysis per dataset |
+| `lstm_cherry_exploration.ipynb` | LSTM model exploration on cherry blossom data |
+| `model_exploration.ipynb` | General model exploration notebook |
+| `pvtt_winter_wheat.ipynb` | PVTT model for winter wheat phenology |
+
+<br>
+
+## Dependencies
+
+Base install: `pandas`, `numpy`, `scipy`, `scikit-learn`, `matplotlib`, `nlopt`, `tables`, `h5py`, `requests`, `requests-cache`, `retry-requests`, `tqdm`, `unidecode`, `platformdirs`.
+
+Heavier and source-specific dependencies (`torch`, `xgboost`, `cdsapi`, `openmeteo-requests`, `geopandas`/`shapely`/`rasterio`, `earthengine-api`, …) are opt-in via the [extras](#installation) above.

pysephone-0.1.0/README.md

@@ -0,0 +1,201 @@
+<div align="center">
+
+# pysephone
+
+![python](https://img.shields.io/badge/python-3.14%2B-blue)
+[![license](https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray)](LICENSE)
+
+</div>
+<br>
+
+## Description
+
+**pysephone** is a Python package for developing and benchmarking crop phenology models — models that predict the timing of key developmental events in plants, such as flowering, leaf-out, or harvest maturity. Accurate phenology predictions are essential for agricultural planning, yield forecasting, and understanding how ecosystems respond to climate variability and long-term change. As growing seasons shift under climate change, the ability to reliably model phenological timing across species and regions becomes increasingly important for both science and policy.
+
+pysephone provides a standardised pipeline that connects observational phenology databases with meteorological drivers, and a suite of models ranging from classical process-based approaches to deep learning, all sharing a common interface.
+
+The package is designed to make it straightforward to:
+- load and preprocess phenological observation data from multiple sources,
+- pair observations with season-windowed meteorological time series (ERA5 reanalysis supported out of the box; other drivers can be integrated),
+- define phenology datasets for standardised intercomparison of models,
+- fit and evaluate a variety of models, and
+- systematically compare model behaviour across species, regions, and climate conditions.
+
+<br>
+
+## Installation
+
+```bash
+git clone https://github.com/ronvree/pysephone.git
+cd pysephone
+pip install -e .
+```
+
+Requires Python ≥ 3.14.
+
+The base install is intentionally lightweight (process-based + scikit-learn models, datasets, evaluation). Heavier and source-specific dependencies are opt-in via extras:
+
+| Extra | Adds | Needed for |
+|---|---|---|
+| `deep` | PyTorch | LSTM / GRU / CNN / Transformer / hybrid / Beta-GDD / BSpline-GDD models |
+| `boost` | XGBoost | `XGBoostModel` |
+| `agera5` | cdsapi, xarray, netCDF4 | Downloading AgERA5 from Copernicus CDS |
+| `openmeteo` | openmeteo-requests | Downloading Open-Meteo ERA5 |
+| `geo` | geopandas, shapely, rasterio | Map visualizations, WorldClim rasters |
+| `earthengine` | earthengine-api | Fetching AlphaEarth embeddings |
+| `stats` | scikit-posthocs, autorank | Friedman/Nemenyi comparison + critical-difference plots |
+| `all` | everything above | Convenience meta-extra (every model + data source) |
+
+Install one or more with e.g. `pip install "pysephone[deep]"` or `pip install "pysephone[deep,agera5]"`. Accessing a model whose extra isn't installed raises a clear error telling you which extra to add.
+
+Reproducing **BloomBench** specifically needs `pip install "pysephone[deep,boost,agera5,stats]"` — its models are CNN/LSTM/Transformer (`deep`), XGBoost (`boost`), RandomForest/Mean/Linear (base); climate features come from AgERA5 (`agera5`); and the `compare` step's Nemenyi/critical-difference plots need `stats`. It does **not** use AlphaEarth/Earth Engine or Open-Meteo.
+
+<br>
+
+## Data Sources
+
+| Source | Description |
+|---|---|
+| **PEP725** | Pan-European Phenology Database — multi-species observations across Europe |
+| **GMU Cherry Blossom** | Cherry blossom bloom dates from Japan, Switzerland, and South Korea |
+| **USA-NPN** | USA National Phenology Network — deciduous fruit-tree observations |
+| **AgERA5** | Daily agrometeorological indicators from Copernicus CDS (downscaled temperature/radiation, Penman–Monteith inputs, etc.) |
+| **Open-Meteo ERA5** | ERA5 reanalysis via the Open-Meteo archive |
+
+Meteorological data is cached locally in HDF5 for fast repeated access. Additional providers can be integrated by implementing the `FeatureProvider` interface.
+
+Some reference datasets (e.g. the cherry-blossom bloom records) are bundled with the package. These third-party datasets retain their original licenses and attribution requirements — see [DATA_SOURCES.md](DATA_SOURCES.md). Note that `liestal.csv` is non-commercial-use only and `kyoto.csv` is provided for academic use with required citations.
+
+<br>
+
+## Authentication & configuration
+
+Some data sources reach external APIs that require **your own** account/project — pysephone ships no credentials and no default project. Set these up once before running the download steps:
+
+**Copernicus CDS (AgERA5).** Authentication uses the [`cdsapi`](https://cds.climate.copernicus.eu/how-to-api) convention — pysephone handles no keys itself. Provide your credentials via either:
+- a `~/.cdsapirc` file, or
+- the `CDSAPI_URL` and `CDSAPI_KEY` environment variables.
+
+**Google Earth Engine (AlphaEarth embeddings).** Requires a Google Cloud project with the Earth Engine API enabled:
+1. Authenticate once: `python -c "import ee; ee.Authenticate()"`.
+2. Tell pysephone which project to use, in priority order:
+   - pass `ee_project="your-gcp-project"` to `fetch_alphaearth_embeddings_batched(...)`, or
+   - set the `PYSEPHONE_EE_PROJECT` environment variable (Earth Engine's native `EARTHENGINE_PROJECT` is also honored), or
+   - leave it unset to let Earth Engine resolve its own default project.
+
+**Data location.** All caches, downloaded data, and outputs are written under a single data root. By default this is an OS-native per-user directory (`%LOCALAPPDATA%\pysephone` on Windows, `~/.local/share/pysephone` on Linux/macOS). Override it with the `PYSEPHONE_DATA_ROOT` environment variable — e.g. set `PYSEPHONE_DATA_ROOT=<repo>` to keep data inside a source checkout during development.
+
+<br>
+
+## Models
+
+| Category | Models |
+|---|---|
+| Baseline | Mean |
+| Process-based | GDD, Utah+GDD, ChillingDays+GDD, Dynamic+GDD |
+| Machine learning | Random Forest |
+| Deep learning | LSTM, Hybrid (TTCNN chilling + GDD forcing) |
+
+All models share a common `fit` / `predict` interface, making it easy to add new models or swap them in evaluation pipelines.
+
+<br>
+
+## Pipeline Overview
+
+```
+Data source (PEP725 / GMU Cherry)
+    ↓  preprocessing  (outlier removal, grid aggregation)
+Observations  (indexed by source, location, year, species, obs type)
+    ↓  paired with Calendar + meteorological feature provider
+Dataset  (yields season-windowed feature arrays per sample)
+    ↓
+Model.fit(target_fn, dataset)  →  Model.predict(sample)
+    ↓
+SingleTargetRegression.run(...)  →  metrics, error DataFrames, plots
+```
+
+The `Calendar` defines the season window (start date + length) for each entry. Feature providers retrieve the corresponding meteorological time series for each sample.
+
+<br>
+
+## Reproducing BloomBench
+
+[BloomBench](https://github.com/WUR-AI/BloomBench) is a multi-species benchmark for evaluating ML phenology models on fruit-tree flowering. The benchmark is shipped as a first-class library module: [`pysephone.benchmarks.bloombench`](src/pysephone/benchmarks/bloombench/).
+
+It exposes both a Python API and a thin CLI. Reproducing the benchmark needs the deep-learning, boosting, AgERA5, and stats extras (it does **not** use Earth Engine or Open-Meteo):
+
+```bash
+pip install "pysephone[deep,boost,agera5,stats]"
+```
+
+```bash
+# 1. Populate the AgERA5 cache once (Copernicus CDS credentials required).
+jupyter nbconvert --execute notebooks/download_agera5.ipynb
+
+# 2. Tune hyperparameters per (dataset, model) — overnight run.
+python -m pysephone.benchmarks.bloombench hpo
+
+# 3. Fit & evaluate every (seed, dataset, model) triple.
+python -m pysephone.benchmarks.bloombench run --seeds 0 1 2
+
+# 4. Friedman + Nemenyi + critical-difference plots.
+python -m pysephone.benchmarks.bloombench compare --seeds 0 1 2
+```
+
+The same flow as Python:
+
+```python
+from pysephone.benchmarks.bloombench import (
+    load_bloombench_datasets, run_benchmark, run_comparison, run_hpo,
+)
+
+datasets, _ = load_bloombench_datasets()
+run_hpo(datasets)                                      # one-time HPO
+results = run_benchmark(seeds=[0, 1, 2], datasets_dict=datasets)
+report = run_comparison(seeds=[0, 1, 2])
+```
+
+For the interactive flow with tables / heatmaps / critical-difference plots, see [`notebooks/bloombench_extended_hpo.ipynb`](notebooks/bloombench_extended_hpo.ipynb) (one-time HPO) and [`notebooks/bloombench_extended.ipynb`](notebooks/bloombench_extended.ipynb) (replication).
+
+<br>
+
+## Project Structure
+
+```
+.
+├── src/pysephone/
+│   ├── benchmarks/     # End-to-end benchmark suites (BloomBench, …)
+│   ├── data/           # Data ingestion and sources (PEP725, GMU Cherry, USA-NPN, AgERA5)
+│   ├── dataset/        # Observations, Dataset, Calendar, feature providers, registry
+│   ├── evaluation/     # Evaluation logic and regression metrics
+│   ├── models/         # Model implementations (CF, RF, LSTM, Hybrid, …)
+│   ├── utils/          # Shared utilities
+│   └── visualize/      # Visualisation helpers
+├── notebooks/          # Jupyter notebooks for exploration and analysis
+├── scripts/            # Standalone scripts
+├── tests/              # Test suite
+└── data/               # Raw and processed data (git-ignored)
+```
+
+<br>
+
+## Notebooks
+
+| Notebook | Description |
+|---|---|
+| `cherry_blossom_cf_models.ipynb` | Process-based model evaluation on GMU Cherry datasets |
+| `cf_models_pep725_fruit_trees.ipynb` | CF model evaluation across PEP725 fruit tree species |
+| `unusual_year_model_eval.ipynb` | Model comparison on climatologically unusual vs normal years |
+| `unusual_seasons_*.ipynb` | Exploration of unusual seasons in GMU / PEP725 data |
+| `dataset_adequacy_*.ipynb` | Sample sufficiency analysis per dataset |
+| `lstm_cherry_exploration.ipynb` | LSTM model exploration on cherry blossom data |
+| `model_exploration.ipynb` | General model exploration notebook |
+| `pvtt_winter_wheat.ipynb` | PVTT model for winter wheat phenology |
+
+<br>
+
+## Dependencies
+
+Base install: `pandas`, `numpy`, `scipy`, `scikit-learn`, `matplotlib`, `nlopt`, `tables`, `h5py`, `requests`, `requests-cache`, `retry-requests`, `tqdm`, `unidecode`, `platformdirs`.
+
+Heavier and source-specific dependencies (`torch`, `xgboost`, `cdsapi`, `openmeteo-requests`, `geopandas`/`shapely`/`rasterio`, `earthengine-api`, …) are opt-in via the [extras](#installation) above.

pysephone-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pysephone"
+version = "0.1.0"
+description = "A Python library for using machine learning to predict the timing of phenological events in plants"
+authors = [
+    { name = "Ron van Bree", email = "ronvbree@gmail.com" }
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.14"
+keywords = [
+    "phenology",
+    "machine-learning",
+    "bloom",
+    "agriculture",
+    "remote-sensing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+# Base install — lightweight core: datasets, observations, process-based and
+# scikit-learn models, evaluation. Heavy / source-specific dependencies live in
+# the optional-dependency groups below.
+dependencies = [
+    "pandas",
+    "numpy>=1.23",
+    "scipy",
+    "scikit-learn",
+    "matplotlib",
+    "tqdm",
+    "requests",
+    "requests-cache",
+    "retry-requests",
+    "unidecode",
+    "nlopt",
+    "tables",
+    "h5py",
+    "platformdirs",
+]
+
+[project.optional-dependencies]
+# Deep-learning models (LSTM, GRU, CNN, Transformer, hybrids, Beta/BSpline GDD).
+deep = ["torch>=2.0"]
+# Gradient-boosted-tree model.
+boost = ["xgboost>=1.7"]
+# AgERA5 (Copernicus CDS) downloading.
+agera5 = ["cdsapi", "xarray", "netCDF4"]
+# Open-Meteo ERA5 downloading.
+openmeteo = ["openmeteo-requests"]
+# Geospatial features (map visualizations, WorldClim rasters).
+geo = ["geopandas", "shapely", "rasterio"]
+# AlphaEarth embedding fetching via Google Earth Engine.
+earthengine = ["earthengine-api"]
+# Statistical model-comparison (Friedman/Nemenyi, critical-difference plots).
+stats = ["scikit-posthocs", "autorank"]
+# Everything — convenient for reproducing the full BloomBench benchmark.
+all = ["pysephone[deep,boost,agera5,openmeteo,geo,earthengine,stats]"]
+
+[project.urls]
+Homepage = "https://github.com/ronvree/pysephone"
+Repository = "https://github.com/ronvree/pysephone"
+
+[tool.setuptools]
+# Ship the license and the bundled-data attribution/NOTICE with every artifact.
+license-files = ["LICENSE", "DATA_SOURCES.md"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pysephone = [
+    "data/**/*.csv",
+    "data/**/*.geojson",
+    "data/**/*.md",
+]

pysephone-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pysephone-0.1.0/src/pysephone/__init__.py

@@ -0,0 +1,12 @@
+"""pysephone — machine-learning models for predicting plant phenology.
+
+The lightweight core (datasets, observations, season calendars, the feature-
+provider interface) is exported here. Models live under ``pysephone.models``
+and are loaded lazily so that importing the package does not pull heavyweight
+optional dependencies such as PyTorch.
+"""
+from pysephone.dataset import Dataset, Observations
+from pysephone.dataset.util.calendar import Calendar
+from pysephone.dataset.util.provider import FeatureProvider
+
+__all__ = ["Dataset", "Observations", "Calendar", "FeatureProvider"]

pysephone-0.1.0/src/pysephone/benchmarks/__init__.py

@@ -0,0 +1,9 @@
+"""Benchmark suites for evaluating phenology models.
+
+Each sub-module is a self-contained, reproducible benchmark: a curated
+collection of datasets, a fixed split, a model registry, and an evaluation
+loop.
+
+See :mod:`pysephone.benchmarks.bloombench` for the BloomBench fruit-tree
+flowering benchmark.
+"""