Zambia Power Stress Index — methodology

1. What this system measures

The Power Stress Index (PSI) is a directional read on electricity availability stress in Zambia, anchored on public Kariba hydrology and evidence of load-shedding severity from news and official sources. It is a short-horizon early warning signal (days to weeks), not seasonal climate prediction or an address-level outage map.

Ingest, human review, training, inference, and public publication can each be at different maturity. The homepage distinguishes operational vs experimental readings using confidence flags and governed snapshots where available.

1b. Regime context — what PSI measures in 2026

PSI measures hydrology-derived grid stress. In the current regime, import capacity (511 MW), commissioned solar (100 MW Chisamba), and forthcoming thermal expansion (Maamba Phase II, 300 MW) buffer the translation from hydrology stress to load-shedding. The structural improvements are not yet modeled.

PSI is a hydrology-channel stress indicator, not a load-shedding forecast. The score is designed to read pressure in the reservoir-linked hydrology channel first; the buffering context now sits beside that score so institutional users can distinguish physical hydrology stress from total grid availability.

The governing doctrine for this reframe lives in psi-regime-framing.md. That doctrine is the canonical reference for retrain gating, the `regime_context` output contract, and the repo boundary that keeps CopperCloud `human_summary` rendering on the orchestrator side.

Today, coupling_strength is interpretation metadata computed from pinned buffering constants until the grid-buffer rail (parked Q2) is live. That means the PSI row carries a transparent context block for imports, solar, thermal baseload, and the inferred coupling strength without pretending those values are daily modeled features.

2. Data sources and update cadence

Primary inputs: Zambezi River Authority (ZRA) hydrology, engineered rows in features_daily, and curated evidence in zesco_label_log (scraped media plus optional hydrology_implied weak labels, flagged by label_source). Bank of Zambia FX and LME copper are also ingested for macro context and Stage 2 feature accumulation.

Cadence: scrapers and feature jobs run on a schedule when deployed. Training is on demand under a governed manifest. Scheduled inference writes model output; public-facing PSI is limited to rows the public view treats as published. Today that publish filter exists at the schema level, but the scheduled PSI inference path still writes rows directly into published state while the manual promotion gate is being hardened.

3. Upper Zambezi / Chavuma (calibration context)

ZRA-published hydrology includes turbine discharge and related flows at Kariba. For interpretation only (not an extra model input in the current four-feature set), long-run mean discharge at Chavuma on the Upper Zambezi is on the order of ~637 m³/s in the project feature registry — useful when comparing daily discharge to basin-scale norms. This does not replace official ZRA methodology.

4. How the PSI score is computed

The current public PSI is generated by an XGBoost classifier on four hydrology-derived features:

• energy_supply_pressure
• level_vs_season_norm
• reservoir_level_7d_velocity (signed 7-day level change; legacy storage alias recharge_rate may appear in older docs)
• days_below_477m

Labels are ordinal severity classes (0 = easing through 3 = crisis language in source material). Where doctrine allows it, training may temporarily merge the rarest extreme class inside the fit matrix while leaving source labels unchanged in Supabase. The public dashboard still reports the published PSI score, regime, and confidence from inference.

Resolution rule per calendar day: scraped beats hydrology_implied; then highest confidence, then highest severity_class. Training uses balanced sample weights at small n.

Temporal split: training and validation are separated by calendar time rather than shuffled randomly, so reported metrics are at least directionally closer to real deployment conditions.

The dashboard headline score and regime come from published inference rows only. Confidence on the homepage reflects the latest published inference row, while the governance rail and data-adequacy strip describe the most recently published training snapshot.

5. Known limitations

This system is strongest as a short-horizon stress monitor, not a full causal model of every grid constraint.

• Public reporting and official releases do not capture every outage, dispatch constraint, or operational intervention.
• Hydrology is a strong structural signal, but it does not fully explain imports, thermal availability, network constraints, or emergency operating choices.
• Recovery and low-stress conditions are still the weakest part of the label history, so calm-period detection remains less mature than stress detection.
• Macro rails are live for context and feature growth, but the macro model is not yet a published product. It remains gated until it beats a naive baseline on a larger labeled window.

Public scrapes miss events; hydrology does not encode every grid constraint. Macro readouts depend on timely releases. Copy stays conservative ("pressure", "elevated risk") rather than false precision.

6. Label doctrine summary

• Scraped rows are primary evidence; hydrology_implied fills gaps only where rules fire and is explicitly flagged.
• Human review is required for uncertain severities when rows are used for training; off-topic scrapes should be removed.
• AI-assisted review may suggest a class, but a person confirms before treating a row as reviewed training evidence where policy requires it.
• Ordinal classes: 0 easing, 1 lighter stress, 2 heavy ongoing cuts, 3 crisis language (mapped to 2 for training in v4 only as noted above).
• Full policy text lives under docs/doctrine/ in the repository.

7. Production state and promotion

Stage 1 PSI is the live public product today. New PSI training runs emit dated psi_v* artifacts and sidecars; promotion is a governed manual step with a written decision record under artifacts/promotions/.

Current operational nuance: inference publication is not yet a separate scheduled workflow step. The public view is publish-filtered, but the scheduled PSI run still inserts rows as published immediately. That publication hardening remains a post-retrain governance task.

This page is intentionally staticand avoids hard-coding live counts or daily timestamps. For the currently published model version, publication time, and governance state, use the homepage "Model & governance" rail and the linked repository artifacts.

Stage 2 macro infrastructure is now live behind the scenes: FX and copper ingest daily, macro features accumulate automatically, and macro training can be rerun as history grows. The macro model is not published until it clears baseline performance.