africas2s 0.2.0__tar.gz

africas2s-0.2.0/.github/workflows/add-to-kanban.yml

@@ -0,0 +1,14 @@
+name: Add issues to Kanban
+
+on:
+  issues:
+    types: [opened, reopened]
+
+jobs:
+  add-to-kanban:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v1.0.2
+        with:
+          project-url: https://github.com/orgs/accord-research/projects/2
+          github-token: ${{ secrets.KANBAN_TOKEN }}

africas2s-0.2.0/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,18 @@
+name: publish-testpypi
+on:
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  build-publish-test:
+    runs-on: ubuntu-latest
+    environment: testpypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

africas2s-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: publish
+
+# PyPI releases are cut MANUALLY, never on a push to main.
+#
+# To release:
+#   1. Bump `version` in pyproject.toml (in a commit to main).
+#   2. Actions tab -> "publish" -> "Run workflow".
+#
+# The job publishes only if that version isn't already on PyPI, so re-running
+# without a version bump is a safe no-op (it fails fast with a clear message).
+# pyproject.toml's `version` is the single source of truth. Publishing uses
+# PyPI Trusted Publishing (no tokens).
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --extra dev
+      - run: |
+          uv run pytest tests/ \
+            --ignore=tests/test_agreement.py \
+            --ignore=tests/test_corrdiff.py \
+            --ignore=tests/test_corrdiff_integration.py \
+            -m "not gpu and not integration" -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Refuse to republish an existing version
+        run: |
+          VERSION=$(grep -E '^version = ' pyproject.toml | head -1 | sed -E 's/version = "(.*)"/\1/')
+          echo "pyproject.toml version: $VERSION"
+          if curl -sf "https://pypi.org/pypi/africas2s/$VERSION/json" > /dev/null; then
+            echo "::error::africas2s $VERSION is already on PyPI — bump 'version' in pyproject.toml first."
+            exit 1
+          fi
+          echo "$VERSION is new on PyPI; proceeding to publish."
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

africas2s-0.2.0/.github/workflows/s2s_testbed.yml

@@ -0,0 +1,341 @@
+name: s2s testbed
+
+on:
+  schedule:
+    - cron: '0 2 * * *'   # 02:00 UTC daily
+  workflow_dispatch:
+    inputs:
+      lookback_days:
+        description: 'How many days back to scan for missed issuances'
+        required: false
+        default: '14'
+
+permissions:
+  contents: write   # We push to the issuance-store branch.
+
+env:
+  CDSAPI_KEY: ${{ secrets.CDSAPI_KEY }}
+  MARS_API_KEY: ${{ secrets.MARS_API_KEY }}
+  MARS_API_EMAIL: ${{ secrets.MARS_API_EMAIL }}
+  COUNTRIES: '["kenya","ethiopia","nigeria"]'
+
+jobs:
+
+  detect_issuances:
+    name: detect new issuances per country
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.build.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: issuance-store
+          path: issuance-store-checkout
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install africas2s (no extras)
+        run: uv sync
+
+      - name: Build (country, issuance) matrix
+        id: build
+        run: |
+          set -euo pipefail
+          LOOKBACK=${{ github.event.inputs.lookback_days || '14' }}
+          MATRIX='[]'
+          for COUNTRY in $(echo "$COUNTRIES" | jq -r '.[]'); do
+            ISSUANCES=$(uv run python -m scripts.s2s.detect_new_issuances \
+              --store-root issuance-store-checkout \
+              --country "$COUNTRY" \
+              --lookback-days "$LOOKBACK")
+            MATRIX=$(jq --argjson m "$MATRIX" --arg c "$COUNTRY" --argjson is "$ISSUANCES" \
+              -n '$m + [$is[] | {country: $c, issuance: .}]')
+          done
+          echo "matrix=$(echo "$MATRIX" | jq -c '{include: .}')" >> "$GITHUB_OUTPUT"
+
+  forecast:
+    name: forecast (${{ matrix.country }} @ ${{ matrix.issuance }})
+    needs: detect_issuances
+    if: ${{ needs.detect_issuances.outputs.matrix != '{"include":[]}' }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      # ECDS allows multiple concurrent requests per user (the legacy MARS
+      # WEB-API's 1-queued-per-user limit is gone now that we're off it).
+      # Three parallel shards keeps total cron wall-clock down without
+      # hammering ECDS or running out of GitHub-hosted runner concurrency.
+      max-parallel: 3
+      matrix: ${{ fromJSON(needs.detect_issuances.outputs.matrix) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: issuance-store
+          path: issuance-store-checkout
+      - uses: actions/checkout@v4
+        with:
+          repository: accord-research/rosetta
+          path: rosetta
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install africas2s + rosetta
+        run: |
+          uv sync
+          uv pip install -e ./rosetta
+
+      - name: Configure nuthatch cache location
+        run: |
+          mkdir -p ~/.cache/nuthatch
+          cat > ~/.nuthatch.toml <<EOF
+          [tool.nuthatch]
+          filesystem = "~/.cache/nuthatch"
+          skipped_filesystems = ["gs://sheerwater-datalake/caches"]
+          EOF
+
+      - name: Restore nuthatch cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/nuthatch
+          # Per-(country, issuance) cache keyed on the rosetta files whose
+          # contents define cache semantics (catalog units, normalization
+          # logic, _CACHE_VERSION). When those change, the cache invalidates.
+          key: nuthatch-${{ matrix.country }}-${{ matrix.issuance }}-${{ hashFiles('rosetta/src/rosetta/catalog.yaml', 'rosetta/src/rosetta/normalize.py', 'rosetta/src/rosetta/fetch.py') }}
+          restore-keys: |
+            nuthatch-${{ matrix.country }}-${{ matrix.issuance }}-
+            nuthatch-${{ matrix.country }}-
+            nuthatch-
+
+      - name: Write .cdsapirc
+        run: |
+          umask 077
+          cat > ~/.cdsapirc <<EOF
+          url: https://ecds.ecmwf.int/api
+          key: ${CDSAPI_KEY}
+          EOF
+
+      - name: Write .ecmwfapirc
+        run: |
+          umask 077
+          cat > ~/.ecmwfapirc <<EOF
+          {
+            "url": "https://api.ecmwf.int/v1",
+            "key": "${MARS_API_KEY}",
+            "email": "${MARS_API_EMAIL}"
+          }
+          EOF
+
+      - name: Run issuance
+        env:
+          S2S_STORE_ROOT: issuance-store-checkout/issuances
+        run: |
+          uv run python -m scripts.s2s.run_issuance \
+            --country "${{ matrix.country }}" \
+            --issuance "${{ matrix.issuance }}" \
+            --config scripts/s2s/s2s.yml
+
+      - name: Commit + push new issuance to issuance-store
+        working-directory: issuance-store-checkout
+        run: |
+          set -euo pipefail
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add issuances/
+          if git diff --cached --quiet; then
+            echo "Nothing to commit for ${{ matrix.country }} @ ${{ matrix.issuance }}"
+            exit 0
+          fi
+          git commit -m "forecast: ${{ matrix.country }} @ ${{ matrix.issuance }}"
+          # Retry-pull-rebase to absorb concurrent matrix shards.
+          for attempt in 1 2 3 4 5; do
+            git pull --rebase origin issuance-store && git push origin issuance-store && exit 0
+            sleep $((attempt * 5))
+          done
+          echo "Push failed after 5 attempts" >&2
+          exit 1
+
+  verify:
+    name: verification pass
+    needs: forecast
+    if: ${{ always() }}   # Run even if some forecast shards failed; verify is independent.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: issuance-store
+          path: issuance-store-checkout
+      - uses: actions/checkout@v4
+        with:
+          repository: accord-research/rosetta
+          path: rosetta
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install africas2s + rosetta
+        run: |
+          uv sync
+          uv pip install -e ./rosetta
+
+      - name: Configure nuthatch cache location
+        run: |
+          mkdir -p ~/.cache/nuthatch
+          cat > ~/.nuthatch.toml <<EOF
+          [tool.nuthatch]
+          filesystem = "~/.cache/nuthatch"
+          skipped_filesystems = ["gs://sheerwater-datalake/caches"]
+          EOF
+
+      - name: Restore nuthatch cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/nuthatch
+          # Verify is a single job that needs obs for every country, so use one
+          # shared verify-scoped cache. Restores from the forecast shards' caches
+          # too (they fetched the same CHIRPS dates) via the `nuthatch-` prefix.
+          key: nuthatch-verify-${{ github.run_id }}-${{ hashFiles('rosetta/src/rosetta/catalog.yaml', 'rosetta/src/rosetta/normalize.py', 'rosetta/src/rosetta/fetch.py') }}
+          restore-keys: |
+            nuthatch-verify-
+            nuthatch-
+
+      - name: Write .cdsapirc
+        run: |
+          umask 077
+          cat > ~/.cdsapirc <<EOF
+          url: https://ecds.ecmwf.int/api
+          key: ${CDSAPI_KEY}
+          EOF
+
+      - name: Write .ecmwfapirc
+        run: |
+          umask 077
+          cat > ~/.ecmwfapirc <<EOF
+          {
+            "url": "https://api.ecmwf.int/v1",
+            "key": "${MARS_API_KEY}",
+            "email": "${MARS_API_EMAIL}"
+          }
+          EOF
+
+      - name: Run verification
+        run: |
+          uv run python -m scripts.s2s.verify \
+            --store-root issuance-store-checkout/issuances \
+            --verification-root issuance-store-checkout/verification \
+            --config scripts/s2s/s2s.yml
+
+      - name: Commit + push verification updates
+        working-directory: issuance-store-checkout
+        run: |
+          set -euo pipefail
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add verification/
+          if git diff --cached --quiet; then
+            echo "No new scores to commit"
+            exit 0
+          fi
+          git commit -m "verify: $(date -u +%Y-%m-%dT%H:%MZ)"
+          for attempt in 1 2 3 4 5; do
+            git pull --rebase origin issuance-store && git push origin issuance-store && exit 0
+            sleep $((attempt * 5))
+          done
+          exit 1
+
+  publish:
+    name: render + publish dashboard
+    needs: verify
+    if: ${{ always() }}   # Publish whatever data made it through.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4               # main: code + site/ shell
+      - uses: actions/checkout@v4
+        with:
+          ref: issuance-store
+          path: issuance-store-checkout         # data: issuances/ + verification/
+      - uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages-checkout               # publish target
+      - uses: actions/checkout@v4
+        with:
+          repository: accord-research/rosetta
+          path: rosetta
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install africas2s + rosetta
+        run: |
+          uv sync
+          uv pip install -e ./rosetta
+
+      - name: Configure nuthatch cache location
+        run: |
+          mkdir -p ~/.cache/nuthatch
+          cat > ~/.nuthatch.toml <<EOF
+          [tool.nuthatch]
+          filesystem = "~/.cache/nuthatch"
+          skipped_filesystems = ["gs://sheerwater-datalake/caches"]
+          EOF
+
+      - name: Restore nuthatch cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/nuthatch
+          # Share with the verify job's cache — render fetches the same CHIRPS
+          # climatology for the comparison-grid obs panel.
+          key: nuthatch-publish-${{ github.run_id }}-${{ hashFiles('rosetta/src/rosetta/catalog.yaml', 'rosetta/src/rosetta/normalize.py', 'rosetta/src/rosetta/fetch.py') }}
+          restore-keys: |
+            nuthatch-verify-
+            nuthatch-
+
+      - name: Write .cdsapirc
+        run: |
+          umask 077
+          cat > ~/.cdsapirc <<EOF
+          url: https://ecds.ecmwf.int/api
+          key: ${CDSAPI_KEY}
+          EOF
+
+      - name: Render dashboard into a build dir
+        run: |
+          uv run python -m scripts.s2s.render_dashboard \
+            --store-root issuance-store-checkout/issuances \
+            --verification-root issuance-store-checkout/verification \
+            --dashboard-root build/s2s \
+            --config scripts/s2s/s2s.yml
+
+      - name: Assemble gh-pages tree (hub + theme + s2s/)
+        run: |
+          uv run python -m scripts.s2s.publish_pages \
+            --site-src site \
+            --s2s-build build/s2s \
+            --pages-root gh-pages-checkout
+
+      - name: Commit + push gh-pages
+        working-directory: gh-pages-checkout
+        run: |
+          set -euo pipefail
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add index.html theme.css
+          [ -d s2s ] && git add -A s2s || true
+          if git diff --cached --quiet; then
+            echo "No site changes to commit"
+            exit 0
+          fi
+          git commit -m "pages: $(date -u +%Y-%m-%dT%H:%MZ)"
+          for attempt in 1 2 3 4 5; do
+            git pull --rebase origin gh-pages && git push origin gh-pages && exit 0
+            sleep $((attempt * 5))
+          done
+          exit 1

africas2s-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: |
+          uv run pytest tests/ \
+            --ignore=tests/test_agreement.py \
+            --ignore=tests/test_corrdiff.py \
+            --ignore=tests/test_corrdiff_integration.py \
+            -m "not gpu and not integration" \
+            -v

africas2s-0.2.0/.gitignore

@@ -0,0 +1,54 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*.so
+
+# Local virtual environments
+.venv/
+venv/
+
+# Test and tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Notebook and editor noise
+.ipynb_checkpoints/
+.DS_Store
+
+# Local outputs/artifacts
+demo_cache/
+examples/output/
+*.png
+*.nc
+*.zarr/
+
+# PyCPT working directories
+tmp_iri_*/
+
+# Scripts cache and output
+scripts/cache/
+scripts/output/
+
+# CPT Fortran source (downloaded by scripts/DWN_CPT_SRC.sh)
+CPT_SRC/
+
+# S2S pipeline outputs (regenerated by run_issuance / verify / render_dashboard;
+# published to an orphan branch or external bucket, not tracked on the code branch)
+dashboard/
+verification/
+issuances/
+
+# Local session / tooling artifacts (Claude Code, superpowers, ad-hoc dumps)
+.superpowers/
+docs/superpowers/
+.old_claude_env
+github-issues.json
+
+# Credential files (never commit)
+.cdsapirc
+.ecmwfapirc
+.netrc

africas2s-0.2.0/AGENTS.md

@@ -0,0 +1,33 @@
+# Agent instructions for africas2s
+
+Instructions for any AI coding agent (Claude Code, Codex, OpenCode, etc.) working in this repository.
+
+## Before you start
+
+Read [`skills/africas2s/SKILL.md`](skills/africas2s/SKILL.md) before writing or modifying code that uses africas2s. It is the authoritative quick reference for the public API, data conventions, method/metric/strategy registries, and the statistical discipline rules (tercile leakage, grid rules, CV requirements), with deeper detail in `skills/africas2s/references/`. If your harness supports Agent Skills natively, load the skill instead of re-deriving the API from source.
+
+## Keep the docs and skill in sync — this is a hard requirement
+
+The skill is a snapshot of the source. Any change that alters observable behavior MUST update the matching documentation **in the same PR**:
+
+| If you change... | You must update... |
+|---|---|
+| Public verb signatures/behavior (`downscale`, `optimize`, `train`, `calibrate`, `ensemble`, `skill`, `skill_compare`, `seasonal_mme`, `flex_forecast`, ...) or result dataclasses | `skills/africas2s/SKILL.md` + `skills/africas2s/references/api.md` |
+| `Index` (`indices.py`): named indices, `REGIONS`, `transform`/`weights`/`baseline`, `reduce` signature | `skills/africas2s/references/api.md` |
+| Analog selection (`analog.py`), scenario completion (`completion.py`), climate positioning (`climate.py`), scalar-series calibration (`series.py`), calendar/season-step utilities (`time.py`) | `skills/africas2s/references/analog-completion.md` (+ `SKILL.md` "Analog completion & climate positioning") |
+| Methods, calibrators, ensemble strategies, CV schemes, `pool_ensembles` (`ensemble.py`), tercile combination/masking (`combine.py`) — add/remove/rename, parameter changes | `skills/africas2s/references/methods.md` |
+| Metrics, tercile conversion, boundaries, significance tools (`metrics/significance.py`, `metrics/cross_validation.py`) | `skills/africas2s/references/metrics-and-terciles.md` |
+| Plotting/reporting functions or export formats — incl. `plotting/maps.py`, `plotting/scenarios.py`, `plotting/forecasts.py` | `skills/africas2s/references/plotting-reporting.md` |
+| Error messages, extras, environment requirements | `skills/africas2s/references/troubleshooting.md` |
+| Rosetta integration / input data shapes | `skills/africas2s/SKILL.md` ("Getting data in") |
+| Anything user-facing | `README.md` if it covers the topic |
+
+Also update `skills/africas2s/examples/` if a change breaks or obsoletes an example. If you are unsure whether a change is documented, grep `skills/` and `README.md` for the function, method name, or parameter you touched — stale docs are treated as bugs.
+
+## Repo conventions
+
+- Package layout: `src/africas2s/` (import name `africas2s`, distribution `africas2s`). Python ≥ 3.10, `uv` for dependency management.
+- Methods/metrics/strategies/calibrators are looked up by name via `africas2s/registry.py` — new capabilities register there rather than being hard-wired.
+- Tests: bare `pytest` must stay fast (< 30 s) and green; markers `integration`, `agreement`, `gpu` gate slow/real-data suites. Coverage target > 85% on `src/africas2s`. New behavior needs tests.
+- Statistical honesty is a design invariant: cross-validated outputs must never leak held-out years (use `to_tercile_cv`, nested CV safeguards). Do not weaken these paths for convenience.
+- CCA numerics intentionally match CPT Fortran 17.8.3 — changes there must preserve parity (`scripts/reproduce.py`, `agreement` tests).

africas2s-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 accord-research
+
+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.