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.

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 explicitly published (see infrastructure migration notes in the repo).

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/.

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.