Metadata-Version: 2.4
Name: anga-grid
Version: 0.5.0
Summary: Gridded climate indicators for East African agriculture
Project-URL: Repository, https://github.com/preston-56/anga-grid
Project-URL: Issues, https://github.com/preston-56/anga-grid/issues
Author-email: Preston Osoro <prestonosoro56@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Preston Osoro
        
        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.
License-File: LICENSE
Keywords: agriculture,chirps,climate,drought,east-africa,xarray
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: netcdf4>=1.6
Requires-Dist: numba>=0.59
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: pint>=0.23
Requires-Dist: pydantic>=2.5
Requires-Dist: xarray>=2024.0
Requires-Dist: xclim>=0.49
Requires-Dist: zarr<3,>=2.17
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# anga-grid

[![CI](https://github.com/preston-56/anga-grid/actions/workflows/ci.yml/badge.svg)](https://github.com/preston-56/anga-grid/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen.svg)](.github/workflows/ci.yml)
[![Region](https://img.shields.io/badge/region-East%20Africa-orange.svg)](doc/calendars.md)

Gridded climate indicators for East African agriculture — anchored in
Njoro and Molo (Nakuru County, Kenya), built for agronomy researchers
and operational drought-monitoring services.

> *anga* (Swahili) — sky, atmosphere.

---

## What this is

anga-grid takes raw gridded climate data — CHIRPS rainfall, AgERA5
reanalysis, TAMSAT African rainfall estimates, NEX-GDDP downscaled
climate projections — and produces the indicators that East African
agronomists and drought-monitoring agencies actually use, with the
seasonal calendars, topographic corrections, and provenance metadata
that operational work requires.

Most general-purpose climate libraries (`xclim`, `xarray`-based
toolkits) treat every region of the world the same way. They aggregate
to calendar quarters, apply uniform bias models, and compute
indicator windows centered on dates that don't match how rain actually
falls in East Africa. That's fine for global comparative work and not
fine for telling a farmer in Njoro whether the long rains are likely
to start in the third week of March or the first week of April.

anga-grid encodes the things you have to know to do this work
correctly in East Africa, and surfaces them as defaults rather than
buried configuration:

- **Bimodal seasonal calendars.** Long rains (*masika*, March–May) and
  short rains (*vuli*, October–December) are first-class concepts.
  Sub-regional variations — the unimodal pattern north of ~3° N, the
  delayed onset over the Rift Valley highlands — are configurable
  rather than averaged away.
- **Onset and cessation detection.** Not "rainfall in MAM" but "when
  did the rains actually start this season?" The library implements
  the operational onset definitions used in East African agromet —
  20mm in 3 days followed by no 10-day dry spell in the next 30 — and
  exposes them as composable rules.
- **Topographic awareness.** CHIRPS is known to underestimate rainfall
  over complex terrain like the Mau Escarpment and the slopes around
  Mt. Kenya. anga-grid surfaces these biases in metadata rather than
  silently passing them through, and offers documented correction
  options.
- **Agronomic indicators, not just meteorological ones.** Critical
  flowering-period dryness for maize, water-requirement satisfaction
  index, dry-spell frequency during land preparation windows — the
  indicators agronomists ask for, computed correctly for the cropping
  calendar.
- **NDMA-compatible outputs.** Drought severity categories match the
  Kenya Meteorological Department / National Drought Management
  Authority operational thresholds. County and ward-level rollups use
  the current administrative boundaries.
- **Provenance you can audit.** Every output carries a manifest:
  source dataset and version, spatial subset, temporal window,
  calendar definition, correction method, code version. The work is
  reproducible and the lineage is legible.

## What this is not

- **Not a replacement for `xarray` or `xclim`.** anga-grid uses
  `xarray` as its core data model and depends on it heavily. Where
  `xclim` already has a correct, well-tested implementation of a
  generic indicator, anga-grid calls into it rather than reinventing.
  The value-add is the East African specialization, not the
  underlying numerics.
- **Not a forecasting system.** anga-grid computes indicators from
  observational reanalysis and projection data. It doesn't run
  weather models, doesn't issue forecasts, and doesn't claim
  predictive skill beyond what the source datasets provide.
- **Not a global library.** It's anchored on East Africa. Some
  functions will work elsewhere (the dataset readers, the basic
  aggregations); the seasonal logic, the bias corrections, and the
  default geographic configuration are East African and we will not
  generalize them at the cost of correctness here.
- **Not a research framework.** Climate scientists building novel
  analyses should probably use `xarray` + `xclim` directly. anga-grid
  is opinionated toward operational reliability and reproducibility,
  not flexibility.

## Why it exists

I grew up in Njoro. The decisions that matter to farmers and to the
drought-response agencies that support them — when to plant, when to
trigger anticipatory action, how to allocate resources between
counties — are made against climate data products that were designed
for a global audience and then adapted, often badly, to local
realities.

The pattern I keep seeing: someone copies a generic SPI computation,
runs it against CHIRPS for Kenya, doesn't notice that the season
boundaries are wrong, and produces a "drought index" that says nothing
useful about the actual cropping season. The bug isn't in the SPI
math; it's in everything around it — the calendar, the spatial
subset, the source-data caveats nobody flagged.

anga-grid exists so that the work of doing this right, once, can be
shared across the agronomists and operational services that need it.

## Status

**v0.5 — under active development.** Current operational surface:

- **Providers** (four datasets): CHIRPS-2.0 daily rainfall, AgERA5
  daily reanalysis (eight variables), TAMSAT-3.1 African rainfall,
  NEX-GDDP-CMIP6 downscaled projections (five SSP scenarios).
- **Indicators**: SPI (gamma + fallback standardisation), operational
  onset, dry-spell counts, growing degree days (maize/sorghum/wheat),
  reference ET (FAO-56 Penman-Monteith), WRSI for maize/sorghum/beans,
  annual/seasonal trend, hot/cold/frost/tropical-night counts.
- **Classifications**: KMD seven-band SPI severity, NDMA four-phase
  drought categorisation, FEWS-NET tercile and quintile maps.
- **Spatial aggregation**: bbox-based and polygon-based rollups; ships
  with the Nakuru ward and county catalog plus cropping calendars for
  Nakuru, Embu, Kisumu, Mombasa, and Garissa.
- **Bias correction**: linear scaling, delta change, monthly linear
  scaling.
- **Storage**: zarr / NetCDF read/write with manifest preservation.

## Quick look

### Install

```bash
# Two install modes; pick the one that matches your situation.

# (a) As a system tool, on PATH everywhere:
uv tool install anga-grid

# (b) Inside a uv-managed project:
uv add anga-grid

# (c) Inside a plain venv (PEP 668 systems will reject pip outside a venv):
pip install anga-grid
```

### Run

The commands below work on a fresh clone — they point at the
committed synthetic fixtures under `tests/fixtures/data/`. Substitute
your real CHIRPS / AgERA5 path when you have one.

If you installed via mode (b) or are running from a checkout, prefix
each command with `uv run` (or `source .venv/bin/activate` once and
drop the prefix). Mode (a) puts `anga` on PATH directly.

```bash
mkdir -p out

# Fetch a CHIRPS subset over Njoro from the committed fixture.
# In v0.6 --source-override goes away in favour of network fetch.
uv run anga fetch chirps \
  --region njoro \
  --start 1991-01-01 \
  --end 1995-12-31 \
  --source-override tests/fixtures/data/chirps_njoro_1991_1995.nc \
  --output out/chirps-njoro.nc

# Compute SPI-3 for the long rains, against the in-window baseline.
uv run anga compute spi \
  --input out/chirps-njoro.nc \
  --window 3 \
  --season long-rains \
  --baseline 1991-1995 \
  --output out/spi3-longrains-njoro.nc

# Detect long-rains onset for each year in the input.
uv run anga compute onset \
  --input out/chirps-njoro.nc \
  --season long-rains \
  --output out/onset-longrains.nc

# Roll up SPI to county-level (the Njoro fixture sits inside the
# Nakuru county bbox; for ward-level rollups use a wider input).
uv run anga rollup \
  --input out/spi3-longrains-njoro.nc \
  --scope nakuru-county \
  --reducer mean \
  --output out/spi3-county.nc

# Classify SPI into the KMD seven-band severity, print a summary.
uv run anga classify \
  --input out/spi3-longrains-njoro.nc \
  --scheme kmd \
  --summary \
  --output out/severity.nc

# Compute a long-term seasonal trend.
uv run anga trend \
  --input out/chirps-njoro.nc \
  --season long-rains \
  --reducer sum \
  --output out/trend.nc

# Tercile classification with an explicit baseline window.
uv run anga quintile \
  --input out/spi3-longrains-njoro.nc \
  --scheme tercile \
  --baseline 1991-1995 \
  --output out/tercile.nc
```

See [examples/](examples/) for worked end-to-end analyses, including
a full WRSI(maize) computation against CHIRPS + AgERA5 reference ET,
and the trend + tercile chain over a synthetic decade.

## Documentation

Start at [doc/index.md](doc/index.md) for navigation by audience.
Highlights:

- [Installation](doc/installation.md) — uv-managed setup.
- [CLI reference](doc/cli.md) — every subcommand and its flags.
- [Data sources](doc/data-sources.md) — where to obtain CHIRPS,
  AgERA5, TAMSAT, NEX-GDDP local replicas.
- [Operations](doc/operations.md) — monthly drought-bulletin
  pipeline shape, observability, reproducibility contract.
- [Troubleshooting](doc/troubleshooting.md) — failure modes and fixes.
- [Architecture overview](doc/architecture.md) and
  [decision records](doc/adr/) — the non-obvious design choices.

## Contributing

Issues and pull requests welcome, especially from agronomists,
extension officers, and operational meteorologists who can tell us
where the defaults are wrong. Code-only contributions are also
welcome.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the local check loop and
[doc/contributing-calendars.md](doc/contributing-calendars.md) if
you're adding a regional cropping calendar.

## License

MIT. See [LICENSE](LICENSE).

## Acknowledgements

CHIRPS data is produced by the Climate Hazards Center at UC Santa
Barbara (Funk et al. 2015). AgERA5 is produced by ECMWF for the
Copernicus Climate Change Service. TAMSAT is produced by the
University of Reading. NEX-GDDP-CMIP6 is produced by NASA Earth
Exchange. anga-grid stands on the shoulders of `xarray`, `xclim`,
`pint`, `zarr`, and the broader Pangeo community.
