Every figure on this site is traceable back to a primary source. Nothing is invented, smoothed, or projected silently. This page lists the inputs and the editorial judgements behind the numbers we publish — so a researcher can see exactly where each reading comes from.
Every input below is fetched on a fixed schedule from a named primary source — never invented, interpolated, or estimated where a real reading exists. Where a value is missing we say so rather than fill the gap.
The official weekly state-of-dams report for the six WCWSS dams. DWS updates this Tuesday/Wednesday; we re-check daily so a late publication is picked up the same morning.
The City's own weekly briefing, published every Monday. The first page carries the headline consumption and per-person figures; later pages list month-to-date rainfall by station.
An ensemble-blended weather service drawing on ECMWF and GFS models, with the ERA5 reanalysis archive providing a 10-year climatology. We compare the live 7-day forecast for each dam catchment against what is normal for the same calendar week of the year.
ESA's open Sentinel-2 mission. We pull cloud-filtered scenes over Theewaterskloof and use a standard water index (NDWI) to distinguish open water from exposed lakebed — the same technique used in academic and government remote-sensing work.
The City's weekly dashboard is overwritten in place every Monday, so historical readings before we began capturing them ourselves are only available via the Internet Archive. Each archived snapshot is tagged with its capture date so the provenance of every historical row is traceable.
Reference data drawn directly from the City's own strategy and outlook publications: who gets the water (City 64%, agriculture 29%, other 7%), what new sources are planned, and the historical demand-side targets. Every figure is paired with the primary-source citation it came from.
Used to put per-person consumption (l/day) into a defensible denominator. Each year is recorded as a census reading, a StatsSA mid-year estimate, or a clearly-flagged projection — never silently interpolated.
Several of the most prominent figures aren't in any single source — they are computed from the inputs above. Here is each derivation, in plain terms, with the underlying constants.
The predictor runs a Monte Carlo simulation against 148 historical weekly readings (2017–2026). Per-month inflow and outflow are decomposed so the rainfall slider only scales the rainfall-driven component — moving "rainfall" to 50% in January doesn't paradoxically reduce summer drawdown.
We use the DWS "Total" row directly when it's present. If the row is missing or non-numeric, we fall back to an FSC-weighted average of the six dams: each dam's % is weighted by its full-storage capacity in Mm³, not by an equal share. Theewaterskloof (479.3 Mm³, ~53% of system FSC) therefore dominates the headline.
Other publishers sometimes use the simple mean across six dams, or include only the five "major" dams. Both produce different numbers from ours. We prefer the DWS-published total because it's the same arithmetic the operating authority uses.
The 7-day forecast sum is divided by the same-week 10-year mean. Ratio ≥ 1.25 prints "wet"; ≤ 0.75 prints "dry"; otherwise "average". A 25% deadband absorbs day-to-day model spread so the headline doesn't flip every refresh.
Per-dam totals are aggregated by FSC-weighted average, the same weighting used for the storage headline — keeping the two numbers comparable.
isFresh() returns true if a reading's ISO date is within the last 9 days. Nine, not seven, because the City PDF publishes weekly and is sometimes a day or two late — a strict 7-day window would falsely flag a normal release.
Year-on-year and week-on-week changes use relChange() — a relative percentage change, not the percentage-point difference. (50% → 25% is a 50% drop, not 25 points.)
These thresholds are editorial, not official. They sit slightly above the City's own restriction triggers so a reader has a margin of warning before the formal level changes.
The mini-trend on the barometer is built by re-parsing the eight most recent archived DWS HTML pages from src/data/dws-raw/. The archive grows by one file per scrape, so the sparkline becomes more granular over time without changing how anything else is computed.
DWS publishes weekly. The City's dashboard publishes weekly. We poll daily so a late publication is picked up the same day, but no figure on this site is ever fresher than its primary source. There is no live SCADA feed.
The Day Zero predictor is a stochastic model conditioned on 10 years of weekly readings. It captures seasonal pattern and inter-year variance; it does not capture climate trend, infrastructure changes (e.g. new desalination), or unprecedented droughts deeper than anything in the training window.
We track the six WCWSS surface dams that supply Cape Town. The City also draws ~4–11% of its current demand from groundwater and advanced water treatment plants outside this system; that share is set to grow under the New Water Programme and is not visible in our headline %.
Our weekly history starts in 2017 (148 readings, irregularly spaced). Anything earlier is qualitative reference only — we don't back-cast figures we couldn't verify against an archived primary source.