UK Home Insurance Geospatial Risk Map

What happened · The model · Sector map · Relative risk · Temperature · Methodology

---

Interactive choropleth of 2,736 UK postcode districts rating eight home-insurance perils — subsidence, weather damage, flood (rivers, sea and surface water), groundwater flooding, theft, escape of water, fire and accidental damage — the four weather-driven perils joined by a C-vine copula, the attritional four priced as independent legs (burglary does not arrive on the storm track, burst pipes answer to cold snaps, dwelling fires follow deprivation and dwelling type, and accidental damage follows the household itself), banded into 10 rating groups. A companion page decomposes good years vs bad years for the whole portfolio.

Coastal erosion is modelled in the vine but deliberately kept out of the premium — see Coastal erosion: modelled, not priced.

Every hazard input is open data, fetched by the scripts here — see DATA_SOURCES.md for all 29 datasets with their endpoints, licences, access quirks and the dead ends worth avoiding. Each peril's loss level is calibrated to published ABI claims payouts, and districts are weighted by census household counts.

⚠️ These are eight-peril technical premiums, not home insurance premiums. A real policy also carries expenses, commission and profit. Expect these figures to be a fraction of what you actually pay. This is a methodology demonstration, not a rating product.

The published site lives in docs/ and is regenerated by scripts/build_site.py; the standalone artefacts it wraps are built by build_map.py and build_analysis.py (both gitignored build outputs — run the pipeline below to produce them).

Repository layout

docs/                         the published website (GitHub Pages source)
  index.html                  landing page: findings + top-risk districts
  map.html                    interactive map (districts), site nav injected
  sectors.html                the same map at postcode-sector resolution
  relative.html               the premium as a multiple of the UK median
  years.html                  what happened: ABI record + good-vs-bad-years
  temperature.html            what 66 years of measured weather did to the model
  methodology.html            full methodology write-up
site/                         page templates + shared stylesheet for docs/
tests/test_copula.py          property tests for the copula machinery
tests/test_spectral.py        guards on the shallow-water dynamical core
.github/workflows/tests.yml   CI: tests + site rebuild + docs/ freshness
data/                         downloaded + derived data (see DATA_SOURCES.md)
scripts/
  fetch_bgs.py                BGS 625k bedrock geology (OGC API, paged)
  fetch_metoffice.py          5 Met Office climate grids (ArcGIS services),
                              incl. air-frost days for escape of water
  fetch_flood.py              river/sea flood extents -> per-district fractions
  fetch_surface_water.py      surface-water extents -> per-district fractions
  fetch_sw_depth_postcodes.py EA surface-water depth bands at unit-postcode
                              centroids -> sw_depth.csv (England)
  fetch_sw_depth.py           the same bands as an AREA share (superseded as
                              model input 2026-09-20; kept for the record)
  fetch_rs_depth_postcodes.py EA river/sea (RoFRS) depth bands at unit-postcode
                              centroids -> rs_depth.csv (England)
  merge_sw_wales.py           folds the 20m Wales re-render into sw_fractions
  fetch_groundwater.py        EA postcode groundwater flags -> district fractions
  fetch_erosion.py            EA NCERM coastal frontages -> erosion.csv (England)
  fetch_erosion_scotland.py   NatureScot Dynamic Coast eroded areas ->
                              erosion_scotland.csv (Scotland)
  fetch_countries.py          ONS country boundaries -> country.csv, the
                              coverage mask for every England-only dataset
  fetch_midas.py              mirrors MIDAS Open station wind obs from CEDA
  gusts_from_midas.py         station obs -> 1-in-50 gust per station (the
                              model's gust source since 2026-08-10)
  fetch_gusts.py              ERA5 gust extremes (fallback without a CEDA
                              account; the model's source before 2026-08-10)
  fetch_history.py            35 years of ERA5 hazard drivers -> backtest
  fetch_households.py         ONS/NRS census households per district (exposure)
  fetch_burglary.py           police.uk street-level burglary points -> counts
  fetch_premises.py           VOA non-domestic premises -> theft's residential share
                              per district (36-month archive, resumable)
  fetch_fires.py              dwelling fires -> annual rate per district
                              (England LSOA incidents, Scotland councils,
                              Wales FRAs; reconciles against FIRE0201)
  fetch_children.py           census dependent-children shares per district
                              (E&W Census 2021 TS003 via NOMIS, Scotland's
                              Census 2022 UV113 at output-area grain)
  scores_real.py              data -> per-district peril scores
  build_model.py              scores -> marginals -> 5-dim C-vine Monte Carlo ->
                              districts_risk.geojson + year_analysis.json
  sensitivity.py              perturbed re-runs -> data/sensitivity.json
  derive_sectors.py           Code-Point centroids -> postcode-SECTOR polygons
  validate_sectors_scotland.py scores them against NRS's official Scottish set
  compare_sector_model.py     sector model vs the published district one
  build_map.py                -> both map pages (district + sector)
  build_tiles.py              -> map/tiles/*.pmtiles, map/units/, map/*_index.json
  build_analysis.py           -> analysis/uk_risk_year_analysis.html
  build_site.py               wraps both + templates -> docs/
  make_images.py              favicon + social card, rendered from the geojson
  dependence_check.py         does the copula actually matter? -> dependence.json
  check_*.py                  small sanity-check helpers (calibration, geojson,
                              surface water, year buckets)
  nwp/                        shallow-water model on the sphere; measures how
                              far ahead weather is forecastable (not in the
                              pipeline - evidence only, see HANDOFF 2026-09-12)
map/template.html             map page (MapLibre GL, linked at build time)
analysis/template.html        good/bad-years page (hand-rolled SVG charts)
assets/maplibre-gl.{js,css}   MapLibre GL JS 5.6.1, linked from the map pages
assets/pmtiles.js             PMTiles 4.3.0 protocol handler

Map layers

Layer	What it shows
Rating group (1–10)	Decile band of the technical premium
Technical premium	E[loss] + 6% cost-of-capital × (TVaR₉₉ − E[loss])
Subsidence risk score	BGS shrink–swell clay geology (0–1)
Weather risk score	Met Office wind / rain exposure (0–1)
Flood risk score	EA / NRW / SEPA river, sea + surface-water zones (0–1)
Groundwater risk score	EA groundwater alert-area coverage (0–1)
1-in-200 combined loss	99.5% VaR of the eight-peril annual loss (C-vine + independent theft, escape of water, fire and accidental damage)
Capital charge	The district's Euler share of portfolio tail risk, in £
Surface-water depth	Mean depth at the homes that flood, from the EA depth bands sampled at unit-postcode centroids (England)
Coastal erosion (blight)	Land projected lost by 2105 under the adopted Shoreline Management Plan (England) or by 2100 under Dynamic Coast's RCP8.5 case (Scotland) — not insured
Climate repricing	Premium under the EA's future flood scenario vs present day (England)

The last three layers distinguish "not mapped" from "measured, and it is zero" — a distinction a single grey would destroy. 81% of districts have no projected coastal erosion, Wales and Scotland have no depth or climate product at all, and on the erosion layer a defended coast (Blackpool, Eastbourne) is a fourth state again: the sea would take land and the defences are stopping it. A plain quantile ramp would also have spent the whole colour scale on zeroes.

Erosion carries a fifth thing the others do not: two sources on different bases. England is NCERM's defences-maintained case at 2105, Scotland is Dynamic Coast's single "do nothing, defences standing" case at 2100 (added 2026-09-03), and Wales has no projection of its own — three border districts carry a trace only because NCERM's Severn and Dee frontages cross into them. er_head is the column the model scores from and er_basis says per district which source it came from — so Scotland's figures can never be mistaken for NCERM's, and the Scottish popup shows an emissions ladder where the English one shows a defended/undefended pair. See Coastal erosion: modelled, not priced.

There is deliberately no per-district "copula uplift" layer: at calibrated frequencies that difference is inside Monte Carlo noise, so the layer would have been drawing noise across the country. The dependence effect is real but lives in the aggregate — see the methodology.

Hover any district for its value; click for the full breakdown (all scores and underlying data values, expected losses per peril, VaR/TVaR under vine / Gaussian / independence, each pair's θ and tail dependence λᵤ).

Methodology

1. Peril scores — real open data (scripts/scores_real.py).

   • Subsidence: BGS Geology 625k bedrock (via ogcapi.bgs.ac.uk, fetched by scripts/fetch_bgs.py). Each of 11,244 formations is classified for shrink–swell susceptibility (London Clay/Thames Group 1.0, Gault/Weald/ Oxford/Kimmeridge/Ampthill Clays 0.9, … Mercia Mudstone 0.45; generic mudstone keywords down-weighted ×0.3 for pre-Mesozoic indurated rocks), then read at every live unit postcode (ONSPD centroids, point-in-polygon in British National Grid) and averaged over each district's postcodes, shrunk toward the postcode area under 20 postcodes (scripts/score_subsidence_postcodes.py; postcode share since 2026-09-06 — area-weighted by polygon intersection before, which read a district whose clay lies under fields and whose homes stand on gravel terraces as clay). This mirrors how BGS GeoSure's shrink–swell layer is derived. The 625k superficial map (--superficial) is then blended in as a modifier, because shrink–swell happens in the soil shallow foundations bear on and drift covers ~58% of GB: sub = (1 − W·cover)·bedrock + W·cover·drift with W = 0.5, where cover is the share of the district's postcodes on a classified deposit (57% of households; 50% by area). Its 14 deposits are enumerated explicitly rather than keyword-matched (lacustrine clay 0.75, clay-with-flints 0.70, brickearth 0.60, alluvium 0.50, till 0.45, granular deposits 0.05), so an unrecognised one raises instead of defaulting. Peat is excluded — it subsides by consolidation and oxidation, not shrink–swell — as is unmapped drift, and both fall back to bedrock. The half weight is the honest treatment of the one thing 625k does not publish: thickness. Effect: 1,452 districts raised, 749 lowered, exposure-weighted premium −0.2% (the ABI calibration re-pins the level), but 42.5% change rating group. Geology says which ground can shrink; since 2026-08-31 a drought climatology says how often it is made to: each district's 1991–2020 mean annual peak of the running water deficit max(cumsum(PET − rain), 0), reset every 1 January, from HadUK-Grid 1 km daily observations streamed on CI (174 GB that never touched a disk whole — scripts/haduk_1km_stream.py, reduced by scripts/make_smd_climatology.py to data/smd_climatology.csv). It enters claim frequency as a blend: sub_rel = (1 − 0.565) + 0.565 · deficit / mean, the share being the ABI's own drought-attribution arithmetic (13,000 of 2022's 23,000 claims; DATA_SOURCES.md #34), normalised to an exposure-weighted mean of 1 so the national level is untouched. Nationally the same index recovers (1976, 1995, 2003, 2018, 2022). The PET inside it is Hargreaves–Samani, ~a third high in a maritime climate — measured (, both 1 km and 5 km grids) to move the deficit's , which calibration re-pins, and not its (rank correlation ≥ +0.998 at PET × 0.85/0.70). Dependence is untouched: θ_WS still reads the geology score.

Re-run 2026-09-26, after seven weeks stale (the script had been failing since the council-tax severity landed — see HANDOFF). Four readings:

• The copula barely touches the ranking now: every dependence scenario moves ≤0.7% of districts, down from 7–26% in August. The attritional perils (escape of water, theft, fire, accidental damage) now carry most of the loss, and they are independent by construction.
• Flood's unanchored depth-damage curve moves the ranking as much as anything short of a 50% flood-frequency shock: ignoring depth altogether moves 12.3%, a curve half or 1.5× as steep 7.8% / 8.6%, and the JRC Europe residential curve 8.3%, all at an unchanged level (LIMITATIONS §6).
• The RoFRS High band's rate is anchored since 2026-09-29. It was the biggest lever while it sat at its band's floor, 3.3%, with nothing above it: 5% moved 10.7% of districts and 10% moved 30.7%. The EA's Recorded Flood Outlines put High homes at 1.67x Medium's flood rate over 1990-2025 (90% 1.30-2.18), so High is priced at 1.67x Medium (2.5%) and the scenarios are now the ends of that range, 1.30x and 2.18x, which move 4.8% / 5.5% of districts: no longer the biggest lever, and 5% and 10% sit far outside the evidence.
• The balance between river/sea and surface water moves it about as much as depth: their band frequencies ×2/3 or ×1.5 against each other move 15.5% / 13.6% of districts, the largest after a 50% flood- frequency shock (23.7%). The rest matter less: river/sea Medium:Low across its recorded range (anchored since 2026-10-06, 1.47 / 2.47) 5.3% either way, surface water's unanchored 5:1 at 2.5:1 / 10:1 3.9% / 2.9%, groundwater's share of flood 2.1–3.4% (the only one that moves the level), groundwater outside England and equal systemic loadings ≤1.8%.
• Severity σ is a check, not a lever: held at the mean it moves no premium and no rating group (Gate 3), but it raises catastrophic-year cost by 12.1%, because the year view draws realised claim sizes. Until this re-run the row scaled σ after the median was fixed. That raised every mean severity unevenly, which is where its old churn came from.
• Erosion stays out of the premium: no further intervention raises erosion exposure 2.3× (£4.5 → £10.5 per policy on the sample) and moves exactly zero districts, which is what "excluded from the premium" has to mean. (The flood–erosion tree-2 pair is left out of the ρ perturbations for the same reason.)

11. Good vs bad years (analysis/uk_risk_year_analysis.html, built by scripts/build_analysis.py). The 20,000 simulated portfolio years are ranked and bucketed (good = best 50%, typical = 50–90th pct, bad = 90–99th, catastrophic = worst 1%), with per-peril cost composition, claim incidence (share of districts claiming), an exceedance curve (vine vs independence), and the worst simulated year decomposed. The year view uses a Gaussian factor model per peril: each district mixes the national systemic factor (which carries the vine dependence) with idiosyncratic noise — spatial loadings weather 50% / flood 40% / subsidence 60% / groundwater 70%, theft 0.13% (derived, not assumed: the CV of the national claim count is ≈2.75·√w at theft's frequency, and the observed burglary series varies ±10–15% a year, which pins w near 0.001; a "felt reasonable" 0.20 would have implied worst years of 8–14× average claims and ~£13/policy of phantom capital), escape of water 2.6% (same derivation, different record: winter 2010's freeze doubled the year's burst-pipe bill, and at 1.06% frequency CV ≈ 0.43 pins w at 0.026 — twenty times theft's, which is why EoW buys real capital and theft does not), fire 0.004% (same derivation a third time: FIRE0201's 45-year series, detrended, has CV ≈2% with no spike years, so fire is priced as pure expected loss), accidental damage 0.012% (a fourth time: lockdown 2020–21 moved home AD declarations ~6%, CV ≈3%, so AD is pure expected loss too) — preserving district marginals exactly while giving realistic cross-district clustering (a pure common-random-numbers view is degenerate: no claims anywhere in 90% of years, then everything at once).

12. Backtest against real years (scripts/fetch_history.py, shown on the year-analysis page). The loss model can't be validated without claims data, but its hazard drivers can: 35 years of ERA5 reanalysis over twelve UK locations are reduced to per-year storm days, peak gust, wettest 5-day total and summer rainfall deficit. The years the model would call bad are the ones Britain remembers — 1990 (Burns' Day storm), 2015 (Desmond/Eva/Frank) and 2020 (Ciara & Dennis) top the storm rankings; 1995, 2018 and 2022 top the drought summers, which are exactly the known subsidence-surge years.

What climate change does to the premium

The EA publishes a climate-change edition of both flood products this model already uses. Re-running on those editions with the calibration held fixed — nothing moves but the hazard map — gives a per-district repricing (premium_cc, cc_uplift_pct, and a map layer).

Choosing the right pair mattered. A comparison between two differently derived products folds a method change into the climate change. Since 2026-09-25 England's rivers and sea read NaFRA2 rofrs_4band, and its climate sibling is rofrs_cc01_4band — same product, same legend, same 13 m/px — so that is the pair used. (Until then the model read the defended extents and paired them with their _CCP1 climate layers, for the same reason.) Where the climate edition is not published at all — "Unavailable" over 1.9% of English postcodes, all of PE11-PE25 and CB6, the Somerset Levels and the Lincolnshire coast — the postcode keeps its present-day band: no uplift where none was modelled, rather than the fall to zero that reading "Unavailable" as dry would give.

Two normalisations had to be pinned to the present day, or the exercise would have measured nothing: the depth multiplier (renormalising on future data divides out "water gets deeper everywhere") and the flood score's 95th-percentile anchor. Both runs share their random draws, so it is a paired comparison.

Stated plainly, four limits:

• A scenario, not a forecast — the EA's climate allowance, not a prediction.
• One rung, not a ladder. There is no choice of epoch or allowance to make: a GetCapabilities sweep of both climate services returns exactly one future layer per product — rofrs_cc01_4band for rivers/sea and rofsw_cc01 (plus its five depth bands) for surface water. So the model cannot show a 2050-vs-2080 or central-vs-upper progression the way the NCERM erosion columns do, where the EA really does publish two epochs and three allowances. This is a publishing limit, not a modelling choice.
• Nearly, not strictly, an uplift. Each future layer is a separate EA model run. On the RoFRS pair no English district's share of homes in the high band (>= 1% a year) falls by more than 1pp; 77 fall at all, worst −0.5pp (SS1). On the extent pair it used before 2026-09-25, 9 districts fell by more than 1pp, worst −25.5pp at HU12. Surface water: 5 districts (0.2%) fall by more than 1pp (12 at all), worst −4.6pp at HU20. The carried present-day band over the fens is an understatement there, not a fall.
• England only. Neither NRW nor SEPA publishes an equivalent, so Wales and Scotland are not modelled; the headline is quoted over covered districts, because a national average would dilute it with two countries that cannot move.

The direction of travel is not subtle. Summed over England's districts, the share of a district's homes (unit postcodes) in the river/sea high band grows +60.4% (+87.7% on the extent pair before 2026-09-25) and the share of homes inside the surface-water ≥1% AEP zone +35.4%. Estuary and defended lowland carry the fluvial/tidal side — ME11 (Queenborough, Sheppey) goes from 0% to 47% of its postcodes, DN32 (Grimsby) 19% → 52%, YO8 (Selby) 15% → 49%, HU1 (Hull) 21% → 49%, NG2 (Nottingham, on the Trent) 7% → 40%, E6 (East Ham) 0% → 32% — while surface water concentrates on dense urban drainage: SW8 (Nine Elms) 14% → 33%, N1C (King's Cross) 10% → 26%, E8 (Hackney) 32% → 48%, RM9 (Dagenham) 38% → 52%.

Coastal erosion: modelled, not priced

The model carries one further peril — coastal erosion, from the EA's NCERM National 2024 frontages (scripts/fetch_erosion.py) — and it is deliberately kept out of premium.

Why it is excluded. Gradual coastal erosion is not covered by standard UK household policies. Putting it in the technical premium would price a loss no policy pays, and would quietly wreck the rating: erosion is a total loss of the property rather than a repair, so where it bites it dwarfs everything else. It is carried instead as blight and valuation exposure — the thing that actually shows up in mortgage and insurability decisions on an eroding coast — in its own columns (el_er, er_*) and its own map layer.

Why it is still in the vine. Erosion is storm-driven: cliffs and beaches retreat in a handful of surge events, not on calm days. So it belongs in the dependence structure even though it is not priced. It enters the C-vine as a fifth dimension with a Gumbel pair to weather (θ_we) and, given weather, the strongest of the tree-2 Gaussian pairs to flood (ρ_FE|W = 0.35) — coastal flooding and coastal erosion are driven by the same storm surges.

What is modelled. A property inside the strip projected to be lost by the 2105 epoch is lost within that horizon, so the annual hazard is the district's zone fraction spread over 80 years, at a sum-insured severity. Two assumptions worth stating plainly: households are taken as spread uniformly across the district (coastal populations actually cluster towards the shore, so this if anything understates it), and the SMP scenario is used — defences maintained as currently planned. The unmanaged NFI case is carried alongside for contrast, and is a sensitivity scenario.

Why it is absent from the good-vs-bad-years view. Erosion is chronic, not episodic. Including it would add a near-constant charge to every simulated year and blur precisely the contrast that page exists to show. Capital is likewise allocated against insured losses only.

The scenario contrast is stark and is the interesting output: nationally the adopted plans hold the 2105 land loss to 250 km² against 435 km² undefended, and several major seafronts — Blackpool (FY1), Eastbourne (BN21), Bognor (PO21/PO22), Crosby (L22) — go from substantial unmanaged erosion to exactly zero under their "Hold the Line" plans. Where the defences are not there, the fastest-eroding coast in Europe shows up correctly: Hornsea (HU18) and Withernsea (HU19) on Holderness top the table, followed by Southwold (IP18) on the Suffolk coast.

Does the copula actually matter?

Worth asking of any model that spends this much effort on dependence. scripts/dependence_check.py measures it (60 districts × 400,000 years) and the answer splits in two:

• For one home, modelling the perils jointly makes a multi-peril year 99× more likely (0.12% vs 0.0012% under independence) — but both are rare, so that home's own 99% TVaR barely moves: +3.1%, 95% CI −7.6% to +14.6%, i.e. indistinguishable from zero. (The interval straddling zero is the finding; its point estimate wanders between runs precisely because it is noise, which is why nothing is priced off it.)
• For the portfolio, the rare joint events stop cancelling: catastrophic years cost ~8% more than independence implies. That is the number capital is set against, and the reason the vine is here.

This is why there is no per-district "copula uplift" map layer — at calibrated frequencies it would be drawing Monte Carlo noise. Removing it is the finding.

Design & accessibility

The site is checked, not assumed:

• WCAG 2.1 AA contrast verified programmatically on all four pages in light and dark mode (measured from computed styles, not from the palette on paper). --ink-muted and link colours were darkened after that audit failed 23 elements; chart series colours are unchanged, since those are marks not text.
• Mobile verified at 375×812 on the live site: no page-level horizontal overflow anywhere, wide tables and charts scroll inside their own containers, nav fits without sideways scrolling, tap targets ≥24px.
• Colours follow a validated data-viz palette; the peril hues (subsidence orange, weather blue, flood aqua, groundwater violet, theft bronze, escape-of-water teal, fire brick red, accidental-damage plum, erosion rose) are used consistently across map, charts, favicon and social card. The erosion rose is contrast-checked live in both themes (5.12:1 light, 8.11:1 dark) because it carries text as well as fill; the theft bronze (5.61:1 light, 9.24:1 dark), the escape-of-water teal (5.7:1 light, 9.5:1 dark), the fire brick red (6.9:1 light, 8.1:1 dark) and the accidental-damage plum (6.7:1 light, 9.8:1 dark) were chosen the same way.

Tests

.venv/Scripts/python -m pytest tests -q

Property tests for the machinery the model rests on: Gumbel h-function inversion round-trips to 1e-8, sampled margins pass Kolmogorov–Smirnov against U(0,1), every vine pair recovers its target Kendall's τ, Gumbel shows upper-tail dependence where the tau-matched Gaussian does not, the 5-dim vine-implied correlation matrix stays positive definite across the whole θ range, and the severity distributions reproduce the published ABI means.

The newer perils get their own guards: erosion's frequency must annualise over the horizon and must not be touched by the ABI frequency scaling (it has no published payout to calibrate against), the flood–erosion tree-2 pair must come out as the strongest of the three, and the depth multiplier must leave the exposure-weighted national mean at exactly 1.0 while still ranking a deep district above a shallow one — plus a fallback test proving the model still runs when the depth product is absent, as it is outside England. Theft's guards pin its severity mean to the ABI average, its claim frequency to the scaled burglary rate, and its expected loss to the analytic p × E[severity] — the last one exists because the simulated estimate was +17% biased (all districts share one theft draw stream) and would silently drift the level. Escape of water carries the same three guards (severity mean, rate pass-through — including the 0.5 clip a raw relativity would have saturated — and the analytic EL), for the same reasons. Fire carries them too, plus one more learned at its own expense: the end-of-run identity test (el_total = Σ el_*) must gain the new leg as part of the wiring — the fire evidence run failed that check at minute 55 with the artifact upload skipped, because the leg was in the fixtures but not the identity. Accidental damage carries the full set (severity mean, child-share rate pass-through, analytic EL), and its identity tolerance widened with the leg count in the same commit as the wiring: the budget is (N legs + 1) × 0.05 of 1dp roundings, 0.45 for eight.

CI additionally rebuilds the whole site from committed data and fails if docs/ has drifted from its templates.

Layout regression tests (tests/test_layout.py) render the built site in headless Chromium and assert what static checks cannot see: no page scrolls sideways at phone or laptop width, no SVG text renders below 9px (an SVG scales its type down with its viewBox — "nothing overflows" is not "it is readable"), the map's zoom/layer/popup-close controls actually receive a tap at their own centre (elementFromPoint, which is how two controls were once found buried under panels), the district popup stays inside the map and scrolls when it overflows, and the map page keeps its accessible routes to the data. They need extra dependencies and skip cleanly without them:

.venv/Scripts/python -m pip install pytest playwright
.venv/Scripts/python -m playwright install chromium
.venv/Scripts/python -m pytest tests/test_layout.py -q

Rebuild from scratch

py -3.13 -m venv .venv
.venv/Scripts/python -m pip install -r requirements.txt
git clone --depth 1 https://github.com/missinglink/uk-postcode-polygons.git data/uk-postcode-polygons

.venv/Scripts/python scripts/fetch_bgs.py            # BGS 625k bedrock -> data/bgs_625k_bedrock.geojson (~32MB)
.venv/Scripts/python scripts/fetch_metoffice.py      # Met Office grids -> data/metoffice/*.csv
# The three flood fraction products are POSTCODE shares (river/sea and surface
# water since 2026-09-06, the depth conditional since 2026-09-20): the same EA /
# NRW / SEPA masks, sampled at ONSPD unit-postcode centroids instead of measured
# over a polygon's area. Every flood share (frequency and depth, both perils)
# weighs each postcode by its Census households since 2026-09-28 (Nomis P002 +
# NRS 2022 index, fetched into data/cache before the first tile). fetch_onspd.py
# writes the centroids and needs OSTN15.
# The area fetchers below them still work and are how the masks were validated,
# but their output is no longer model input - see DATA_SOURCES #41.
.venv/Scripts/python -u scripts/fetch_onspd.py             # -> data/postcode_centroids.csv
.venv/Scripts/python -u scripts/fetch_flood_postcodes.py   # river/sea -> data/flood_fractions.csv
.venv/Scripts/python -u scripts/fetch_sw_postcodes.py --flags england   # and --flags wales, --flags scotland
.venv/Scripts/python -u scripts/fetch_sw_postcodes.py      # surface water -> data/sw_fractions.csv
.venv/Scripts/python -u scripts/fetch_sw_depth_postcodes.py --flags     # five depth layers, England (~1 h)
.venv/Scripts/python -u scripts/fetch_sw_depth_postcodes.py             # -> data/sw_depth.csv
.venv/Scripts/python -u scripts/fetch_rs_depth_postcodes.py --flags     # band + five depth layers, England (~2 h; rs-depth.yml does it in 4 parts)
.venv/Scripts/python -u scripts/fetch_rs_depth_postcodes.py             # -> data/rs_depth.csv
.venv/Scripts/python scripts/fetch_erosion.py        # NCERM coastal erosion -> data/erosion.csv (~3 min, England)
.venv/Scripts/python scripts/fetch_countries.py      # ONS country boundaries -> data/country.csv (~1 min).
                                                     # Run this BEFORE build_model: it is the coverage mask that
                                                     # stops the England-only layers being read as GB-wide.
# Climate-change scenario (optional; without these the repricing view is simply absent):
.venv/Scripts/python -u scripts/fetch_flood_postcodes.py --climate  # -> data/flood_fractions_cc.csv
.venv/Scripts/python -u scripts/fetch_sw_postcodes.py --flags england --climate
.venv/Scripts/python -u scripts/fetch_sw_postcodes.py --climate   # -> data/sw_fractions_cc.csv
.venv/Scripts/python -u scripts/fetch_sw_depth_postcodes.py --flags --climate
.venv/Scripts/python -u scripts/fetch_sw_depth_postcodes.py --climate  # -> data/sw_depth_cc.csv
.venv/Scripts/python -u scripts/fetch_rs_depth_postcodes.py --flags --climate
.venv/Scripts/python -u scripts/fetch_rs_depth_postcodes.py --climate  # -> data/rs_depth_cc.csv
# download Postcodes_Risk_Assessment_All.csv (see DATA_SOURCES.md #13) to data/ea_postcode_risk.csv, then:
.venv/Scripts/python scripts/fetch_groundwater.py    # groundwater flags -> data/gw_fractions.csv
# Gusts - data/gusts.csv is MIDAS station extremes (since 2026-08-10). To
# refresh it you need a (free) CEDA account and token (DATA_SOURCES.md #24):
.venv/Scripts/python -u scripts/fetch_midas.py       # mirror uk-mean-wind-obs -> data/midas/ (~8 GB, resumable)
.venv/Scripts/python scripts/gusts_from_midas.py data/midas/uk-mean-wind-obs
#                                                    # -> data/gusts_midas.csv; copy over data/gusts.csv
# No CEDA account? The previous source still works as a fallback:
#   .venv/Scripts/python scripts/fetch_gusts.py      # ERA5 -> data/gusts.csv (Open-Meteo free tier has a daily
#                                                    # quota - if it 429s, rerun next day; the weather blend
#                                                    # auto-includes gusts once >=60 points exist)
.venv/Scripts/python scripts/fetch_history.py        # 35yr ERA5 hazard drivers -> data/history.csv (backtest,
#                                                    # and the anchor for TAIL_FREQ_RATIO - DATA_SOURCES #15)
# data/abi_annual.csv is HAND-TRANSCRIBED from the ABI's full-year property
# releases (one every February) - there is no feed and the site bot-blocks
# scrapers. When the next one lands, add its rows with the source URL and a
# published/derived flag, DO NOT overwrite prior years (the ABI restates
# them, and both readings are kept side by side), then re-run:
#   .venv/Scripts/python scripts/anchor_budget.py           # instant
#   .venv/Scripts/python scripts/backtest_coverage.py       # ~40 min, one full sim
# Optional, not a model input: derive postcode-SECTOR polygons (open data;
# only Scotland publishes official ones) - DATA_SOURCES.md #23:
#   .venv/Scripts/python scripts/fetch_codepoint.py
#   .venv/Scripts/python -u scripts/derive_sectors.py   # -> data/sectors_gb.gpkg
.venv/Scripts/python scripts/fetch_households.py     # ONS lookup + census -> data/households.csv (exposure, ~22MB dl)
.venv/Scripts/python -u scripts/fetch_burglary.py    # police.uk archive (1.7 GB, resumable download) -> data/burglary.csv
.venv/Scripts/python -u scripts/fetch_premises.py    # VOA NDR stock by LSOA -> data/premises.csv (theft denominator)
                                                     # (~6 min once the archive is cached; checkpoints every 100 files)
.venv/Scripts/python -u scripts/fetch_fires.py       # Home Office LSOA incidents + SFRS + Welsh FRAs -> data/fires.csv
                                                     # (~40 MB of ODS; parses content.xml directly - pandas' odf
                                                     # engine takes >10 min on these files)
.venv/Scripts/python -u scripts/fetch_children.py    # NOMIS TS003 (E&W LSOA) + Scotland UV113 (OA) -> data/children.csv
                                                     # (dependent-children household shares; conserves 27.29m households)
.venv/Scripts/python scripts/build_model.py          # calibrate + vine sim -> districts_risk.geojson + year_analysis.json (~55 min;
                                                     # the 5th vine dimension roughly doubled this - the extra Gumbel
                                                     # h-inverse bisection for erosion is the dominant cost)
.venv/Scripts/python scripts/sensitivity.py          # perturbed re-runs -> data/sensitivity.json (~60 min, optional)
.venv/Scripts/python scripts/make_images.py          # favicon + 1200x630 social card, rendered from the data
.venv/Scripts/python scripts/build_map.py            # -> both map pages (district and sector)
.venv/Scripts/python scripts/build_tiles.py          # -> vector tiles, popup shards, name index (~3 min).
                                                     # The pages read these over HTTP, by byte range, so they
                                                     # need a server: `python -m http.server` inside docs/
.venv/Scripts/python scripts/build_analysis.py       # -> analysis/uk_risk_year_analysis.html

Every step is deterministic (fixed RNG seed 42); re-running build_model.py reproduces the shipped outputs exactly given the same inputs. CI enforces this: it rebuilds the whole site from committed data and fails if docs/ has drifted from its templates.

Two notes on running it:

• build_model.py holds ~25 transient (BATCH × N_SIM) arrays, so BATCH is set to 80. Raising it to 250 needs ~1 GB and thrashes on an 8 GB machine — slower in wall-clock terms despite fewer batches.
• The Open-Meteo free tier has a daily volume quota. fetch_gusts.py and fetch_history.py are resumable; if they start returning HTTP 429, rerun the next day. The weather score folds gusts in automatically once ≥60 grid points exist and falls back cleanly below that.
• fetch_sw_depth.py (the superseded area fetch) writes a checkpoint to data/cache/ after every tile column, so a machine that sleeps mid-run costs you one column, not the whole fetch — rerun it plain to resume, or pass --restart to start over. fetch_sw_depth_postcodes.py, which writes the table the model reads, splits instead with --part i/n. Both fetchers degrade gracefully: if sw_depth.csv is missing the model falls back to a flat surface-water severity, and if erosion.csv is missing the erosion peril is simply zero everywhere.
• A dropped tile is invisible in the output — it reads as "no flood risk here", indistinguishable from real data. The raster fetchers therefore retry six times with exponential backoff and, if a tile is still lost, write to <name>.partial instead of the real filename so an incomplete fetch cannot quietly become model input. This is not hypothetical: a DNS blip mid-run silently cost one tile before the guard existed.
• With the climate files present, build_model.py runs the simulation twice (present and future), so budget ~110 min rather than ~55.

Publishing

GitHub Pages serves main + /docs, so a push deploys. The one thing that is not automated is the repository's own social preview image: GitHub exposes no API for it (usesCustomOpenGraphImage is read-only in GraphQL). Upload docs/assets/social-github.png by hand under Settings → General → Social preview — Edit opens a menu, and the file dialog is behind "Upload an image…" inside it. That file is generated at 1280×640 opaque RGB specifically for this: GitHub asks for that size, and its image processing has been seen to reject RGBA PNGs without reporting an error. (social.png stays 1200×630 with alpha — the Open Graph size the site's own pages reference.)

To check whether it took:

gh api graphql -f query='{repository(owner:"SMcode-source",name:"uk-home-insurance-risk-map"){usesCustomOpenGraphImage}}'

false means it did not stick; a custom image is also served from repository-images.githubusercontent.com rather than opengraph.githubassets.com.

Set and verified 2026-08-02. Worth recording why it took several attempts: the 1200×630 RGBA card was rejected silently every time, and the 1280×640 opaque RGB copy worked immediately. If it ever needs redoing, use social-github.png. Either way this is cosmetic — the site's pages carry their own Open Graph tags and preview correctly already, so links to the map itself are unaffected.

Caveats & production path

The hazard inputs are real (BGS geology, Met Office climatologies, EA/NRW/ SEPA flood maps, EA groundwater alert areas — all OGL), but this is still not a priced product:

• the formation→susceptibility lookup is a public-literature approximation of BGS GeoSure (the licensed product adds an integrated susceptibility rating, tree cover and drought interaction — and GeoClimate adds UKCP18 projections);
• 625k-scale geology is coarse: district edges inherit the dominant formation, and superficial clays (e.g. till over chalk) are not counted — though not for want of open data. BGS publishes bgsgeology625ksuperficial on the same open OGC API as the bedrock layer this model already uses: 10,651 features, same paging, carrying lex_d/rock_d in the same vocabulary the classifier keys off (TILL, ALLUVIUM, CLAY, SILT AND SAND). What is genuinely missing is thickness. Without it there is no principled way to decide whether the superficial cover or the bedrock governs foundation behaviour, and a thin gravel over London Clay would score like a thick one. Peat is a further complication: a serious subsidence hazard, but through consolidation and oxidation rather than shrink-swell, so folding it into this peril would conflate two mechanisms. Adding the layer is therefore a modelling decision, not a fetch — but it is not licence-blocked, and the earlier wording here implied it was;
• the 1-in-50 gust is fitted per MIDAS station and IDW-interpolated from 191 points (median 15 km to the nearest station), so station siting still leaves local noise a licensed storm event set would not; stations above 300 m are excluded because they measure summits, not homes;
• the flood fractions are area-based (13–100 m rasters) from defended present-day extents — property-level receptor counts and defence-failure scenarios are not included; FRAW (Wales) is notably more conservative than EA RoFSW for surface water; Northern Ireland has no anonymous flood service (GB-only boundaries make this moot);
• groundwater uses alert-area coverage, not modelled emergence probability, and is England-only;
• flood severity is depth-conditioned (surface water, and since 2026-09-26 rivers/sea), but only in England: Wales and Scotland publish no depth product, so they keep the flat severity. That is an asymmetry in the spread of severity, not its level — each multiplier is renormalised to a mean of 1.0 per claim — but it means English districts are differentiated on depth and the rest are not;
• coastal erosion is England-only (NCERM), assumes households are spread uniformly across the district when they in fact cluster towards the shore, and annualises an 80-year projection into a flat yearly hazard. It is reported separately and is not in the premium — see Coastal erosion: modelled, not priced;