Sub-daily depth ratios — run & integration guide¶

Replaces the previously unsourced fallback ratio table with region-keyed, ECCC-sourced ratios plus a full audit trail. Aggregation unit is the terrestrial ecozone (climatic region), because sub-hourly:daily ratios are driven by storm type (convective vs synoptic), which tracks climate region, not province.

Dependencies: Python 3.9+ standard library only (no numpy/scipy/geopandas).

1. Verify it before trusting it (offline, no network)¶

python scripts/derive_subdaily_ratios.py --selftest

Exercises the IDF .txt parser, the Gumbel-MoM design-depth math, point-in- polygon assignment, and aggregation on synthetic fixtures (clearly labelled, no real data). All checks must print OK / ALL SELF-TESTS PASSED.

2. Produce the real ratios (needs ECCC + AAFC access — run on Windows)¶

If your environment can't reach collaboration.cmc.ec.gc.ca or agriculture.canada.ca, run this on a machine with internet access.

python scripts\derive_subdaily_ratios.py --scheme ecozone --rp 10 --out-dir ratio_outputs --cache-dir idf_cache

(One line. In CMD, ^ only continues a line when it's the last character on the line; pasted as one line the carets become stray arguments. In PowerShell the continuation char is a backtick `. Single-line avoids both.)

The default dataset version is v3.40 (Dec 2025), fetched as a single nested zip. For a newer release pass --idf-version <name> (browse the IDF host to find it) or --idf-zip-url <full-url>.

What it does: discovers the newest IDF version folder, downloads each province .zip (cached), parses Table 1 annual maxima, fits Gumbel-MoM per station/ duration, assigns each station to an ecozone by point-in-polygon against the official NEF v2.2 GeoJSON, aggregates by region (median + weighted mean + 90% CI), and writes the outputs in §4.

If the ecozone GeoJSON URL doesn't resolve, download it manually from the open-data record ("Terrestrial Ecozones of Canada", NEF v2.2) and pass it:

python scripts/derive_subdaily_ratios.py --geojson path\to\nef_ca_ter_ecozone_v2_2.geojson ...

Without a boundary file the script will not guess regions — it falls back to province aggregation with a warning.

Useful flags¶

Flag	Default	Purpose
`--scheme ecozone\\|ecoprovince`	`ecozone`	aggregation unit (15 vs ~53)
`--rp 10`	`10`	return period for the primary design-depth ratio
`--rps 2 10 100`	`2 10 100`	RP-sensitivity set stored in the CSV
`--min-years 10`	`10`	min valid annual maxima per duration
`--min-stations 5`	`5`	min stations for a `documented` flag
`--provinces ON QC`	all 13	restrict the download (faster testing)
`--region-prop NAME_EN`	auto	GeoJSON property holding the region name
`--write-template`	—	(re)write the unpopulated `ratios.py` template

3. Smoke-test against a couple of provinces first¶

python scripts/derive_subdaily_ratios.py --provinces PE NS --out-dir test_out

Small provinces → fast. Open test_out/ratios_by_station.csv and sanity-check: \(\text{ratio}(5\,\text{min}) \approx 0.10\text{–}0.22\) and \(\text{ratio}(1\,\text{h}) \approx 0.40\text{–}0.60\), monotone increasing with duration, anchor exactly \(1.00\).

4. Outputs¶

File	What
`ratios.py`	`RATIOS_BY_REGION`, `NATIONAL_AVERAGE`, `PROVINCE_CONVENIENCE`, `PROVINCE_TO_REGION`, `CONFIDENCE`, `SOURCE`, `POPULATED=True`. Minute keys; `1440 == 1.00`.
`ratios_by_station.csv`	audit trail: per station/duration ratios (design @ T and mean-AM cross-check), assigned region + method, province, lat/lon, years, n, native resolution.
`PROVENANCE.md`	regenerated, data-filled methodology record (per-region n / median / CI tables, crosswalk, citations).

examples/ contains the same three files generated from synthetic data so you can see the shapes now (marked "SYNTHETIC — do not use for design").

5. Wire into the tool¶

ratios.py shipped here is the unpopulated template (POPULATED=False); the tool can import it and must keep showing "source required" until you run the derivation, which overwrites it with real numbers.

Recommended Tier-3 lookup order once populated:

station lat/lon → ecozone → RATIOS_BY_REGION[region] (primary)
PROVINCE_CONVENIENCE[province] when no coordinates (planning-level)
NATIONAL_AVERAGE

Set the citation from SOURCE; surface the per-region CONFIDENCE flag in the IDF report so planning-level regions are visible. Keep the existing Provenance machinery gated on POPULATED.

Paste-in `source` string¶

Sub-daily depth ratios derived from ECCC Engineering Climate Datasets, Short-Duration Rainfall IDF v3.40 (Table 1 annual maxima), accessed . Per-station Gumbel (method-of-moments) design-depth ratios at the 10-yr return period, aggregated by terrestrial ecozone (median across stations) using the National Ecological Framework for Canada v2.2 (AAFC). Region/duration cells with fewer than 5 stations are flagged planning-level; cells with no station data are left undefined.

(The run writes the exact string, with the live version and date, into ratios.SOURCE.)