anga-grid 0.5.0__tar.gz

anga_grid-0.5.0/.dockerignore

@@ -0,0 +1,27 @@
+.github
+.venv
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.hypothesis
+__pycache__
+*.pyc
+*.pyo
+.coverage
+htmlcov
+build
+dist
+*.egg-info
+tests
+doc
+examples
+.editorconfig
+.pre-commit-config.yaml
+CHANGELOG.md
+CONTRIBUTING.md
+SECURITY.md
+CODE_OF_CONDUCT.md
+CLAUDE.md
+data
+*.zarr
+*.nc

anga_grid-0.5.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{md,yml,yaml,toml,json}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

anga_grid-0.5.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug report
+about: Report unexpected behaviour with a synthetic-data reproducer
+labels: bug
+---
+
+## What you expected
+
+<!-- What anga-grid was supposed to do. -->
+
+## What actually happened
+
+<!-- What it did instead. Include the exception trace if any. -->
+
+## Reproducer
+
+```python
+from anga_grid.synthetic import synthetic_chirps
+# minimal code that triggers the issue against synthetic data
+```
+
+## Environment
+
+- anga-grid version:
+- Python version:
+- OS:
+- xarray / xclim versions (from `uv pip list | grep -E 'xarray|xclim'`):
+
+## Manifest contents
+
+If the issue is about provenance / output attrs, paste the relevant
+attrs of the offending dataset:
+
+```
+ds.attrs
+```

anga_grid-0.5.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Propose a new indicator, provider, calendar, or operational hook
+labels: enhancement
+---
+
+## Operational context
+
+<!-- Which operational workflow needs this. Bulletin generation,
+     early-warning trigger, county dashboard, research analysis,
+     etc. -->
+
+## What's missing today
+
+<!-- How are people working around the absence of this feature? -->
+
+## Proposed shape
+
+<!-- Either an API sketch (function signature, CLI invocation) or a
+     reference to an existing implementation we could model on
+     (FEWS NET, ICPAC, KMD, an xclim indicator, a paper). -->
+
+## Citations / authoritative sources
+
+<!-- KMD bulletin, ICPAC GHACOF statement, peer-reviewed paper,
+     county extension service report. The default thresholds in this
+     library are anchored on cited sources; new ones should be too. -->

anga_grid-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+## What changed
+
+<!-- One sentence per logical change. If this PR bundles unrelated
+     changes, please split it. -->
+
+## Why it matters
+
+<!-- The operational or analytical context. Who notices this and
+     when? -->
+
+## Local check
+
+- [ ] `uv run ruff check src/ tests/` clean
+- [ ] `uv run mypy src/` clean
+- [ ] `uv run pytest --cov=anga_grid --cov-fail-under=80` passes
+- [ ] If touching defaults / thresholds: citation included in
+      commit body or doc/
+
+## Provenance impact
+
+- [ ] Output `Manifest` history records the new operation
+- [ ] Caveats list updated if the change affects bias notes
+- [ ] No-op if this PR doesn't touch indicator outputs
+
+## Docs touched
+
+- [ ] CHANGELOG updated
+- [ ] README Quick Look still accurate
+- [ ] doc/ files affected by the change updated

anga_grid-0.5.0/.github/dependabot.yml

@@ -0,0 +1,30 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Africa/Nairobi"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    ignore:
+      # zarr 3.x is a breaking rewrite; pinned <3 deliberately until
+      # the upstream xarray + zarr-3 stack is proven on this codebase.
+      - dependency-name: "zarr"
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "ci"
+    commit-message:
+      prefix: "ci"
+      include: "scope"

anga_grid-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: pin python
+        run: uv python install ${{ matrix.python }}
+
+      - name: install
+        run: uv sync --extra dev --python ${{ matrix.python }}
+
+      - name: ruff
+        run: uv run --python ${{ matrix.python }} ruff check src/ tests/
+
+      - name: mypy
+        run: uv run --python ${{ matrix.python }} mypy src/
+
+      - name: pytest
+        run: uv run --python ${{ matrix.python }} pytest --cov=anga_grid --cov-report=term-missing --cov-fail-under=80

anga_grid-0.5.0/.gitignore

@@ -0,0 +1,54 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+.python-version
+
+# uv
+uv.lock
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.hypothesis/
+
+# Type checkers
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Local data caches
+/data/
+*.zarr/
+*.nc
+!tests/fixtures/**/*.nc
+
+# Editor / system droppings
+*~
+*.bak
+.~lock.*
+
+# Jupyter checkpoints picked up by users running examples in notebooks
+.ipynb_checkpoints/

anga_grid-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy on src/
+        entry: uv run mypy src/
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]

anga_grid-0.5.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project go here. Format follows Keep a
+Changelog; this project does not yet ship pinned releases - everything
+below is on `main`.
+
+## Unreleased — v0.5 work in progress
+
+### Added
+
+- `temperature_extremes` indicator: hot_days, cold_days, frost_days,
+  tropical_nights with WMO-ETCCDI default thresholds.
+- `severity.quintile` module: tercile and quintile classification with
+  optional baseline-period reference.
+- `severity.summary` module: per-band fraction breakdown of a
+  classified output.
+- Per-region cropping calendars: Embu, Kisumu, Mombasa, Garissa.
+- CLI: `anga trend` and `anga quintile` subcommands.
+- README badges: CI, Python, license, ruff, coverage, region.
+- Project setup docs: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md,
+  CHANGELOG.md, CITATION.cff, doc/installation.md, doc/cli.md,
+  doc/operations.md, doc/data-sources.md, doc/troubleshooting.md,
+  doc/glossary.md, doc/roadmap.md, doc/index.md,
+  doc/contributing-calendars.md.
+- ADRs 0002 (no default network fetch), 0003 (manifest as attrs),
+  0004 (eight test layers).
+- Build infra: Dockerfile, .dockerignore, Makefile, .editorconfig,
+  .pre-commit-config.yaml, .github/dependabot.yml,
+  .github/ISSUE_TEMPLATE/{bug_report,feature_request}.md,
+  .github/PULL_REQUEST_TEMPLATE.md, .github/FUNDING.yml.
+- CI: Python 3.13 added to the test matrix.
+- Storage: `.cdf` accepted as a NetCDF suffix.
+- Tests: hypothesis property tests for cropping windows + temperature
+  extremes monotonicity; synthetic-data builder consistency contract.
+
+### Changed
+
+- README install instructions now use `uv tool install` as the
+  primary path; the previous `pip install` line broke on PEP 668
+  systems.
+- README Quick Look fetch example flags `--source-override` since
+  network fetch is still roadmap in v0.5.
+- `severity.quintile` now drops the stray `quantile` coord that
+  `xr.quantile` adds, fixing apply_ufunc dimension errors on
+  spatial inputs.
+
+## v0.4 (2026-01)
+
+- NEX-GDDP-CMIP6 provider with five-scenario catalog and unit conversion.
+- Polygon-based rollups via vectorised ray-casting (no shapely dep).
+- `cropping/` module: phenological windows + Nakuru calendars.
+- `anga_grid.synthetic` public package; runnable examples/.
+- Top-level files reshaped into themed sub-packages: types, exceptions,
+  logging, aggregation, correction, severity, storage, provenance,
+  season.
+
+## v0.3 (2025-12)
+
+- TAMSAT-3.1 provider as the third precipitation reader.
+- Provider sub-package refactor: chirps/, agera5/ split into
+  provider/schema/manifest/variables modules.
+- Indicator sub-package refactor: spi/, onset/, dry_spell/, gdd/.
+- Reference ET (FAO-56 Penman-Monteith).
+- WRSI for maize, sorghum, beans.
+- Four new test layers: smoke, regression, performance, roundtrip.
+
+## v0.2 (2025-11)
+
+- Provenance Manifest as a first-class concept.
+- Storage helpers (zarr/netcdf write/read with manifest preservation).
+- AgERA5 provider for ECMWF/Copernicus reanalysis.
+- Dry-spell count and growing degree days indicators.
+- Bias correction: linear scaling, delta change, monthly linear scaling.
+- County/ward rollups with the Nakuru ward catalog.
+- KMD severity bands and NDMA drought phase classification.
+- CLI: `anga rollup` and `anga classify` subcommands.
+
+## v0.1 (2025-09 → 2025-10)
+
+- Initial release: CHIRPS provider, Season type with KMD/ICPAC catalog,
+  SPI and onset indicators, basic CLI, behavioural test suite, CI.

anga_grid-0.5.0/CITATION.cff

@@ -0,0 +1,49 @@
+cff-version: 1.2.0
+message: "If you use anga-grid in published work, please cite it."
+title: "anga-grid"
+abstract: >
+  Gridded climate indicators for East African agriculture, with
+  KMD/ICPAC seasonal calendars, FAO-56 reference ET, WRSI, and
+  KMD/NDMA/FEWS-NET drought classification baked in.
+authors:
+  - family-names: Osoro
+    given-names: Preston
+    email: prestonosoro56@gmail.com
+license: MIT
+repository-code: "https://github.com/preston-56/anga-grid"
+type: software
+keywords:
+  - climate
+  - agriculture
+  - east-africa
+  - drought
+  - chirps
+  - xarray
+references:
+  - type: article
+    authors:
+      - family-names: Funk
+        given-names: Chris
+    title: >
+      The climate hazards infrared precipitation with stations - a new
+      environmental record for monitoring extremes
+    journal: "Scientific Data"
+    year: 2015
+    volume: 2
+    number: 150066
+    doi: 10.1038/sdata.2015.66
+  - type: article
+    authors:
+      - family-names: Camberlin
+        given-names: Pierre
+      - family-names: Okoola
+        given-names: Raphael E.
+    title: >
+      The onset and cessation of the long rains in eastern Africa
+      and their interannual variability
+    journal: "Theoretical and Applied Climatology"
+    year: 2003
+    volume: 75
+    issue: 1
+    start: 43
+    end: 54

anga_grid-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,44 @@
+# Code of conduct
+
+anga-grid is a small project but its contributors include researchers,
+operational meteorologists, and extension officers across multiple
+institutions and countries. We expect everyone interacting in project
+spaces (issues, pull requests, discussions, email) to behave the way
+they'd want a colleague at a regional climate forum to behave.
+
+## Concretely
+
+- Be respectful of different domain expertise. A peer-reviewed
+  climatologist and an extension officer running monthly drought
+  bulletins both have things to teach each other.
+- Critique ideas, not people. If you disagree with a proposed default
+  threshold or season window, say why with citations rather than
+  dismissing the contributor.
+- Assume good faith on language differences. Many contributors won't
+  have English as a first language; phrasing that reads tersely or
+  abruptly is rarely intended that way.
+- No harassment, sexualised content, ad hominem attacks, or
+  political-affiliation flame wars in project spaces.
+
+## Enforcement
+
+If you experience or observe unacceptable behaviour, please email
+**prestonosoro56@gmail.com**. Reports will be handled confidentially.
+
+For minor issues, the maintainer may simply ask the offending party
+to adjust their behaviour. For repeated or severe issues, the
+maintainer may temporarily or permanently ban the contributor from
+project spaces.
+
+## Scope
+
+This Code of Conduct applies to all project spaces (the GitHub
+repository, related issue trackers, mailing lists, and any
+project-affiliated communication channels) and to public spaces when
+an individual is representing the project.
+
+## Attribution
+
+Inspired by the Contributor Covenant, adapted for a smaller-scale
+project where individual judgement is preferred over a long
+prescriptive ruleset.

anga_grid-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to anga-grid
+
+Thanks for considering a contribution. anga-grid is built for
+operational use by East African agronomy and drought-monitoring
+services, and the project particularly welcomes input from people
+working in those domains.
+
+## What we want
+
+The most useful contributions, in order of impact:
+
+1. **Domain corrections.** If a default season window, planting DOY,
+   bias caveat, or threshold is wrong for the region you work in,
+   open an issue with the correction and a citation we can ground
+   the change in (KMD bulletin, ICPAC GHACOF statement, peer-reviewed
+   paper, county-level extension service report).
+2. **New regional cropping calendars.** The catalog in
+   `src/anga_grid/cropping/calendar.py` covers Nakuru, Embu, Kisumu,
+   Mombasa, and Garissa. Adding a calendar for your county requires
+   planting DOY, days-to-flower / fill / harvest for each crop, and
+   the season key it anchors to.
+3. **New dataset providers.** If your operational pipeline uses a
+   dataset we don't ship a reader for, the fastest path is a PR
+   modelled on `providers/chirps/` or `providers/agera5/`.
+4. **Bug reports.** Especially ones that include a synthetic-data
+   reproducer using `anga_grid.synthetic.*`.
+
+## What we don't want
+
+- Generalisation to other regions at the cost of East African
+  correctness. The library is opinionated for a reason; the
+  README's "Not a global library" line is load-bearing.
+- New abstractions for hypothetical future flexibility. Three
+  similar lines is better than a premature abstraction.
+- Changes to default thresholds without a citation. The defaults
+  match operational KMD/ICPAC/NDMA practice; if you change them
+  you owe an explanation.
+
+## How to contribute
+
+### Bug reports and feature requests
+
+Open an issue on
+[GitHub](https://github.com/preston-56/anga-grid/issues). Please
+include:
+
+- What you expected to happen
+- What actually happened
+- A minimal reproducer (synthetic input is fine; see
+  `anga_grid.synthetic.*` for ready-made data builders)
+- Your Python and `anga-grid` versions
+
+### Code contributions
+
+1. Fork the repo and create a topic branch.
+2. Set up a dev environment: `uv sync --extra dev`.
+3. Make your change with tests. Every new module needs a
+   corresponding `tests/unit/test_*.py`.
+4. Run the full local check before opening a PR:
+
+   ```bash
+   uv run ruff check src/ tests/
+   uv run mypy src/
+   uv run pytest --cov=anga_grid --cov-fail-under=80
+   ```
+
+5. Open a PR with a description of *why* the change matters
+   (operational context > technical motivation).
+
+### Commit conventions
+
+- Use a leading scope tag: `feat(providers): ...`, `fix(rollup): ...`,
+  `doc: ...`, `test: ...`, `ci: ...`, `refactor(season): ...`.
+- Keep each commit to one logical change. The history reads better
+  when each commit's diff matches one claim in its subject line.
+- Don't bundle code + tests + docs into one giant commit when they
+  can land separately.
+
+## Code style
+
+- `ruff check` and `mypy --strict` must pass; CI enforces this.
+- Default to no comments. Only add one when the *why* of the code is
+  non-obvious. Avoid godoc-style `// FuncName does X` blocks on every
+  function; well-named identifiers should carry the load.
+- New modules go inside themed sub-packages, not flat at the root.
+  See `src/anga_grid/correction/` and `src/anga_grid/severity/` for
+  the two-file split pattern.
+- Public API symbols are exported via the package `__init__.py`
+  re-exports. Internal helpers stay underscore-prefixed.
+
+## Testing layers
+
+The test tree has eight layers, each with its own pytest marker:
+
+- `tests/unit/` — per-module behavioural tests
+- `tests/providers/` — per-provider integration against synthetic data
+- `tests/integration/` — cross-module end-to-end (CLI etc.)
+- `tests/property/` — hypothesis-driven invariants
+- `tests/smoke/` — minimum import / wiring sanity
+- `tests/regression/` — pinned past-bug behaviours
+- `tests/performance/` — bounded-time benchmark checks
+- `tests/roundtrip/` — write-then-read symmetry tests
+
+When adding a substantive new module, please touch the relevant
+layer(s) — at minimum `tests/unit/` and `tests/smoke/`.
+
+## License
+
+By contributing you agree your changes are released under the MIT
+License (see `LICENSE`).

anga_grid-0.5.0/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim-bookworm
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libnetcdf-dev \
+        libhdf5-dev \
+        ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir uv==0.4.18
+
+WORKDIR /app
+
+COPY . .
+
+RUN uv pip install --system --no-cache .
+
+ENTRYPOINT ["anga"]
+CMD ["--help"]

anga_grid-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+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.

anga_grid-0.5.0/Makefile

@@ -0,0 +1,41 @@
+.PHONY: help install test lint typecheck cover clean
+
+help:
+	@echo "make install     - uv sync with dev extras"
+	@echo "make test        - run the full pytest suite"
+	@echo "make lint        - ruff check"
+	@echo "make typecheck   - mypy on src/"
+	@echo "make cover       - pytest with coverage report"
+	@echo "make smoke       - just the smoke test layer"
+	@echo "make clean       - remove caches and build artifacts"
+
+install:
+	uv sync --extra dev
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check src/ tests/
+
+typecheck:
+	uv run mypy src/
+
+cover:
+	uv run pytest --cov=anga_grid --cov-report=term-missing --cov-fail-under=80
+
+smoke:
+	uv run pytest -m smoke -q
+
+regression:
+	uv run pytest -m regression -q
+
+performance:
+	uv run pytest -m performance -q
+
+roundtrip:
+	uv run pytest -m roundtrip -q
+
+clean:
+	rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache .coverage htmlcov .hypothesis
+	find . -type d -name __pycache__ -exec rm -rf {} +