PlanX Urban Resilience — Academic Reference Manual

Covering Urban Resilience v1.26.2 · 43 Algorithms · 10 Tool Groups
Yusuf Eminoğlu · github.com/YusufEminoglu/planx_urban_resilience

How to Use This Manual

This manual documents every Processing algorithm in the PlanX Urban Resilience suite. It is written for spatial planners, disaster-risk researchers, graduate students and QGIS practitioners who need both the scientific rationale and the operational guidance to run each tool correctly.

Every algorithm entry follows an identical eight-section template:

1. Overview — what the tool produces and its planning purpose.
2. Theoretical Background — academic lineage, assumptions, and limits.
3. Mathematical Formulation — equations, algorithms, and complexity.
4. Input Data Requirements — layer types, fields, and preprocessing.
5. Parameters — every parameter, its type, default, and operational guidance.
6. Output Description — every output field, its type, units, and typical range.
7. Symbolic Representation — recommended QGIS renderers, colour ramps, and classification.
8. Interpretation Guide — thresholds, benchmark bands, diagnostic readings, and planning actions.

Each entry closes with Academic References. All equations are rendered with MathJax and numbered. The manual uses these typographic conventions: monospace for parameter names, field names, and Processing IDs; bold for key concepts on first introduction; italic for journal and book titles.

Introduction to PlanX Urban Resilience

PlanX Urban Resilience is a 43-algorithm QGIS Processing suite for city-scale resilience screening. It spans the full disaster-risk reduction cycle: hazard exposure (seismic, heat, flood, air quality, drought), vulnerability (social, infrastructure, accessibility), response (emergency access, evacuation, shelter siting), and synthesis (multi-hazard composite, equity-adjusted priority, cost-benefit, lifecycle economics).

The suite is offline-first: every algorithm runs on local vector and raster data without cloud dependencies, API calls, or external solvers. This design serves planning studios in low-connectivity environments, classroom reproducibility, and audit-grade deterministic workflows. All Monte Carlo modules expose a seed parameter so results are exactly replicable.

Architecture

The suite is organised as a QGIS ProcessingProvider (planx_urban_resilience) with ten tool groups. Each algorithm is a self-contained Python class following QGIS's QgsProcessingAlgorithm contract. Shared functionality — clamping, classification helpers, weight parsing, reproducible random numbers — lives in processing/_helpers.py. Network algorithms share a graph builder in processing/accessibility/_network_graph.py. The companion dashboard.py QGIS panel provides a scrollable, searchable module catalogue with one-click launch shortcuts.

The Ten Tool Groups

Design Principles

• Offline-first. No cloud APIs, no external solvers, no internet dependency. Every algorithm runs on local data alone.
• Deterministic. All stochastic modules expose a seed parameter. Same seed + same inputs = identical outputs, every run.
• Screening, not compliance. These are planning-support indices for prioritisation and classroom analysis. They are not substitutes for site-specific engineering studies, hydrodynamic models, or structural assessments.
• Transparent weights. Every composite algorithm exposes user-controlled weights with sensible defaults. Defaults are documented and justified in the relevant Theoretical Background section.
• Pure Python. The suite carries no compiled dependencies. Statistical modules (Gi*, LISA, correlation, IDW) run in pure Python for auditability and zero-install deployment.

0. Demo & QA

The Demo group provides a single synthetic-data generator. It produces a self-contained artificial study area with buildings, roads, impervious surfaces, green infrastructure, water bodies, shelters, social-unit polygons, and sensitive receptors — all with plausible geometries and essential attribute fields. Use it for classroom demonstrations, smoke-testing the full suite, or prototyping a workflow before acquiring real data.

Synthetic Resilience Demo Dataset

Processing ID: planx_urban_resilience:synthetic_resilience_demo_dataset

1. Overview

Generates a complete artificial resilience-study dataset in a single run. The output consists of nine layers — buildings (with floor_count and construction_year fields), roads (with capacity and class), impervious surfaces, green patches, water bodies, shelter points, social-unit polygons (with population, elderly, children, disability, and low-income fields), and sensitive-receptor points. A SCALE parameter controls spatial extent. Every output is in a projected CRS suitable for metric analysis.

2. Theoretical Background

Synthetic datasets are a standard tool in spatial-algorithm validation (Fisher & Tate, 2006). The generator uses a fixed geometric layout — a central spine road with perpendicular branches, clustered buildings along each branch, and concentric land-use zones — to produce a dataset where every resilience module can find its required inputs. The geometry is deterministic (no random component), so two runs with the same scale produce identical layers.

3. Mathematical Formulation

The layout follows a simple cellular template. A spine road runs east–west at y = 0; N branch roads run north–south at regular x-intervals. Building footprints are placed along each branch with fixed offsets. Green patches and water bodies are placed in the inter-branch zones. Shelter points are placed at the midpoint of each branch. Social-unit polygons are regular grid cells covering the entire extent.

4. Input Data Requirements

5. Parameters

6. Output Description

Nine output layers, each added to the QGIS project. Field schemas are designed to match the input requirements of the hazard, vulnerability, emergency, and synthesis modules. The building layer includes floor_count (integer, 1–8), construction_year (integer, 1960–2020), and land_use (string). Roads include capacity_ph (persons/hour), class (arterial/collector/local), and direction (both/ft/bt). Social units include population, elderly, children, disability, and low_income — all numeric counts.

7. Symbolic Representation

Buildings: single-symbol fill, 20% opacity, dark grey. Roads: categorised by class — arterial = 1.0 mm dark grey, collector = 0.6 mm, local = 0.3 mm light grey. Green: solid #4dac26 fill at 40% opacity. Water: solid #0571b0 fill. Shelters: green triangle markers, size 4 mm. Sensitive receptors: red circle markers, size 3 mm. Social units: graduated by population, OrRd ramp, 5 natural-breaks classes.

8. Interpretation Guide

The synthetic dataset is a workflow validation tool, not a real-city substitute. After generating it, run each hazard module in sequence, join scores to the social-unit polygons via Join Hazard Scores to Planning Units, and feed the result into the Multi-Hazard Composite and Adaptation Priority Synthesis tools. Confirm that all 43 algorithms accept the outputs without errors before switching to real data. The deterministic layout means every student in a classroom sees the same starting dataset.

Academic References

Fisher, P.F. & Tate, N.J. (2006). "Causes and consequences of error in digital elevation models." Progress in Physical Geography, 30(4), 467–489.

1. Seismic: Debris & Logistics

The Seismic group models post-earthquake building collapse, debris generation, and evacuation-network degradation. The single algorithm uses a Monte Carlo framework driven by a user-supplied moment magnitude scenario and building-age fragility functions. It produces six output layers spanning static network topology through dynamic debris envelopes to post-disaster clearance corridors.

Post-Earthquake Collapse, Debris & Evacuation Network (Monte Carlo)

Processing ID: planx_urban_resilience:seismic_debris_monte_carlo

1. Overview

Simulates a single earthquake scenario on a city block. For each building, computes a collapse probability from construction year and moment magnitude (Mw), then performs a Monte Carlo draw to decide whether it collapses. Collapsed buildings generate a debris envelope (horizontal spread proportional to building height) that is subtracted from the road network. The output is a six-layer cascade: net logistics network topology, morphological encroachment areas, per-building vulnerability points, dissolved debris envelope, cumulative road-blockage areas, and the surviving post-disaster clearance corridors.

2. Theoretical Background

The fragility model follows the empirical age–vulnerability curves synthesised in HAZUS-MH (FEMA, 2003) and the debris-spread formulation of Goretti & Sarli (2006), who calibrated horizontal debris extent from Italian post-earthquake surveys. Base collapse probabilities are stratified by construction era: pre-1985 (0.85), 1985–2000 (0.60), 2001–2018 (0.25), post-2018 (0.05). The magnitude scaling factor is exponential in Mw: mag_factor = exp(0.8 × (Mw − 7.0)). The debris spread coefficient k and void/solid volume ratio follow FEMA P-58 guidance. The engine is in processing/seismic/monte_carlo_debris.py; reproducible randomness is provided by SeededRng (64-bit LCG, Knuth MMIX constants) from processing/_helpers.py.

3. Mathematical Formulation

where \(H\) = floor count × floor height, \(k\) = debris spread coefficient, \(v_r\) = void/solid volume ratio, and \(A_{\text{footprint}}\) = building polygon area. Debris geometry is a square-end-cap buffer of radius debris_radius around the footprint. Road blockage = intersection of debris envelope with the net road network. Clearance corridors = net road network minus the union of all road-blockage geometries.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Vulnerability points: graduated by collapse_prob, Viridis ramp, 5 natural-breaks classes, marker size 2.0–6.0 mm. Debris envelope: semi-transparent red fill (30% opacity), no stroke. Blockage areas: solid dark red fill at 50% opacity. Clearance corridors: bright green lines, 0.8 mm width — the surviving routes. Net road network: light grey fill with 0.3 mm dark grey stroke.

8. Interpretation Guide

Collapse probability: sort descending to identify retrofit priorities. Values above 0.80 indicate pre-code construction under >M7.0. Total blocked area (printed to the log) is the headline metric — compare across Mw 6.5 vs 7.5 to see the non-linear jump in road loss. Clearance corridors: map these with Network Emergency Accessibility to answer "after the quake, which shelters can still be reached?".

Academic References

FEMA. (2003). HAZUS-MH MR4 Technical Manual. Federal Emergency Management Agency, Washington, DC.

Goretti, A. & Sarli, V. (2006). "Road network and damaged buildings in urban areas: short and long-term interaction." Bulletin of Earthquake Engineering, 4(2), 159–175. DOI: 10.1007/s10518-006-9004-3

FEMA. (2018). Seismic Performance Assessment of Buildings, Volume 1 — Methodology (FEMA P-58-1), Second Edition. Washington, DC.

2. Heat: Comfort & Exposure

The Heat group provides an offline-first urban heat comfort risk screening model. It combines impervious surface share, building density, green/cooling deficit (distance to parks and water), and optional vulnerable-asset exposure into a 0–100 heat risk score on a user-defined grid. It is a planning-support index, not a microclimate simulation.

Urban Heat Comfort Risk (screening)

Processing ID: planx_urban_resilience:urban_heat_comfort_risk

1. Overview

Scores every cell of a user-defined grid for heat risk using four additive components: impervious surface share (roads, hardscape), building density, green deficit / cooling distance (distance to nearest park or water body), and vulnerable asset exposure (schools, hospitals, elderly housing). Each component is normalised 0–100 and weighted by user-controlled coefficients. The output includes a full heat-risk grid, a priority-cooling-zone layer (cells scoring ≥ 55), and an exposed-assets layer.

2. Theoretical Background

The model draws on the urban heat island (UHI) literature: Oke's (1982) foundational work on the energetic basis of UHI; the surface-cover framework of Stewart & Oke (2012) for Local Climate Zones (LCZ); and the cooling-distance thresholds validated by Bowler et al. (2010) in their meta-analysis of park cooling effects (200–400 m typical). Weight defaults reflect the relative contribution found in Voogt & Oke (2003): imperviousness and green deficit are the dominant drivers; building density and vulnerable-population proximity are amplifying factors. The engine is in processing/heat/urban_heat_comfort.py.

3. Mathematical Formulation

where \(I\) = impervious share × 100, \(B\) = building share × 100, \(D_g\) = (1 − green_share) × 100, \(C\) = clamp(dist_to_cooling / cooling_distance × 100), \(V\) = clamp(vulnerable_count × 20), and all weights are user-supplied.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Heat risk grid: graduated by heat_score, YlOrRd ramp (5-class quantile), 0.3 mm border in light grey. Priority cooling zones: same ramp, 0.5 mm darker border, 60% opacity — these are the intervention targets. Exposed assets: categorised by risk_class — Very High = red markers, High = orange, Moderate = yellow, Low = not shown.

8. Interpretation Guide

heat_score ≥ 75 (Very High): dense building clusters with almost no green space and distant from water — classic UHI core. heat_score 55–74 (High): residential districts with moderate tree cover but high impervious share. heat_score 35–54 (Moderate): suburban fringe with mix of green and built cover. heat_score < 35 (Low): park-adjacent or water-adjacent cells. Priority cooling zones (≥55) should be cross-referenced with Population-Weighted Exposure to identify cells where high heat risk coincides with high population density. Feed priority zones into Cost-Benefit Analyzer to rank green-infrastructure interventions.

Academic References

Oke, T.R. (1982). "The energetic basis of the urban heat island." Quarterly Journal of the Royal Meteorological Society, 108(455), 1–24.

Stewart, I.D. & Oke, T.R. (2012). "Local Climate Zones for urban temperature studies." Bulletin of the American Meteorological Society, 93(12), 1879–1900. DOI: 10.1175/BAMS-D-11-00019.1

Bowler, D.E. et al. (2010). "Urban greening to cool towns and cities: a systematic review." Landscape and Urban Planning, 97(3), 147–155.

3. Flood: Pluvial Susceptibility

The Flood group provides an offline-first pluvial (rainfall-driven) flood susceptibility screening model. It uses a DEM to compute relative low-elevation, flat-slope proxy, and drainage proximity scores on a user-defined grid. The model identifies low-lying, poorly-drained urban cells and marks exposed buildings and road segments. It is a planning-support index, not a hydrodynamic model.

Pluvial Flood Susceptibility (screening)

Processing ID: planx_urban_resilience:pluvial_flood_susceptibility

1. Overview

Scores every grid cell for pluvial flood susceptibility using three additive components: relative low elevation (how low a cell sits within the study area's elevation range), flat / low-slope proxy (local relief within a user-defined neighbourhood radius), and drainage proximity (distance to the nearest stream or water body). Buildings and road segments intersecting high-score cells are flagged as exposed.

2. Theoretical Background

The model adopts the topographic-wetness-index logic of Beven & Kirkby (1979) but simplifies it for planning-scale screening: elevation relative to the study-area envelope replaces catchment-contributing area, and local relief within a fixed radius replaces slope-angle computation. This is the approach used by Tehrany et al. (2014) for rapid flood-susceptibility mapping. The drainage-proximity term is informed by the distance-to-stream component of the FEMA HAZUS-MH Flood Model methodology. DEM sampling is clamped to the raster extent with a half-pixel inset, preventing out-of-range reads at study-area boundaries. The engine is in processing/flood/pluvial_flood_susceptibility.py.

3. Mathematical Formulation

where \(r\) is the neighbourhood radius and local relief is max − min of four cardinal samples at distance \(r\). If no drainage layer is supplied, \(D\) defaults to 50.0 (neutral).

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Flood susceptibility grid: graduated by flood_score, Blues ramp (5-class natural breaks), 0.3 mm border. Exposed buildings: red markers, size scaled by flood_score. Exposed roads: categorised — red for high exposure (≥75), orange for moderate. Overlay with a hillshade of the DEM at 50% transparency for terrain context.

8. Interpretation Guide

flood_score ≥ 75: cells in the lowest 25% of the elevation range, with minimal local relief and near a stream — classic floodplain floor. flood_score 55–74: transitional slopes near drainage corridors. flood_score < 35: ridge-top or hillslope cells far from water. Exposed buildings: cross-reference with Social Vulnerability Index to identify high-flood-exposure + high-social-vulnerability neighbourhoods. Feed exposed-road outputs into Network Criticality to see whether key evacuation routes lie in flood-prone cells.

Academic References

Beven, K.J. & Kirkby, M.J. (1979). "A physically based, variable contributing area model of basin hydrology." Hydrological Sciences Journal, 24(1), 43–69.

Tehrany, M.S., Pradhan, B. & Jebur, M.N. (2014). "Flood susceptibility mapping using a novel ensemble weights-of-evidence and support vector machine models in GIS." Journal of Hydrology, 512, 332–343.

4. Social: Vulnerability & Equity

The Social group provides a weighted social vulnerability index (SVI) following the Cutter et al. (2003) framework. It normalises neighbourhood- or census-polygon indicators (elderly, children, disability, low-income, population density) to 0–100 and combines them with user-controlled weights. Missing data fields are flagged but do not block the computation.

Social Vulnerability Index (screening)

Processing ID: planx_urban_resilience:social_vulnerability_index

1. Overview

Computes a normalised 0–100 Social Vulnerability Index per polygon from up to five demographic indicators. All indicators are treated as risk-increasing (higher count or rate = higher vulnerability). Each indicator is min-max normalised across the study area, then combined via weighted arithmetic mean. The output includes the composite score, a class label, population density, and a data-quality flag listing any missing fields.

2. Theoretical Background

The index follows the SoVI (Social Vulnerability Index) framework of Cutter, Boruff & Shirley (2003), who demonstrated that social vulnerability to environmental hazards can be operationalised from census variables. The five default indicators — elderly, children, disability, low-income, and population density — map to the dimensions Cutter identified as most predictive of adverse outcomes: age extremes, socioeconomic status, special-needs populations, and population pressure. Weight defaults (elderly 0.25, low-income 0.25, disability 0.20, children 0.15, density 0.15) reflect the factor loadings reported in Cutter & Finch (2008). All normalisation is min-max within the supplied layer — the index is relative to the study area, not to a national baseline. The engine is in processing/social/social_vulnerability_index.py.

3. Mathematical Formulation

where \(k\) ∈ {elderly, children, disability, low_income, density} and \(w_k\) is the user-supplied weight. Indicators with zero weight or missing fields are excluded from the summation. Population density = population / area_ha.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by svi_score, YlOrBr ramp, 5-class quantile classification, 0.3 mm border. Overlay with the hazard-score layer being analysed (heat, flood, etc.) to visually identify high-hazard + high-vulnerability coincidences. Alternatively, feed both into Bivariate Choropleth Symbology for a formal 3×3 matrix renderer.

8. Interpretation Guide

svi_score ≥ 75: the most vulnerable neighbourhoods — multiple overlapping indicators. These are the equity-priority targets. svi_score 55–74: elevated vulnerability, typically driven by one dominant factor. data_flags: if any indicator with non-zero weight is missing, the flag reminds you the score is based on incomplete information. Feed SVI into Equity-Adjusted Adaptation Priority to raise the priority of high-hazard + high-vulnerability units. Feed into Risk-Recovery Priority Matrix alongside a recovery-capacity score to find the gap.

Academic References

Cutter, S.L., Boruff, B.J. & Shirley, W.L. (2003). "Social vulnerability to environmental hazards." Social Science Quarterly, 84(2), 242–261. DOI: 10.1111/1540-6237.8402002

Cutter, S.L. & Finch, C. (2008). "Temporal and spatial changes in social vulnerability to natural hazards." Proceedings of the National Academy of Sciences, 105(7), 2301–2306.

5. Emergency: Accessibility, Evacuation & Networks

The Emergency group is the largest operational cluster in the suite — seven algorithms spanning Euclidean shelter coverage, network-based accessibility routing, edge-betweenness criticality, capacity-constrained evacuation simulation with optional timestep queuing, seismic cascade analysis, and optimal shelter siting via greedy maximal-coverage location. Together they model the full emergency-response spatial chain: who can reach a shelter → which roads are bottlenecks → how long does evacuation take → what happens to the network after the quake → where should new shelters go?

Emergency Accessibility and Shelter Coverage

Processing ID: planx_urban_resilience:emergency_accessibility_shelter_coverage

1. Overview

Creates a Euclidean grid-based access-deficit map from shelter or safe-assembly points. Each cell's score is the distance to the nearest shelter, normalised between a target service distance and a critical distance, with an optional barrier-overlap penalty. Underserved assets (buildings or population points beyond the service distance) are flagged in a separate layer.

2. Theoretical Background

This is an Euclidean nearest-neighbour screening model. It implements the service-area logic of the two-step floating catchment area (2SFCA) method (Luo & Wang, 2003) but simplifies it to a single-step distance decay. The barrier penalty follows the impedance-surface approach: cells overlapped by barrier polygons (e.g. waterways, highways without crossings) receive a proportional score increase. The engine is in processing/accessibility/emergency_accessibility.py.

3. Mathematical Formulation

where \(d\) = Euclidean distance to nearest shelter, clamped to \(d_{\text{critical}}\) if no shelter found.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Access grid: graduated by access_score, RdYlGn ramp (reversed: green = low deficit, red = high deficit), 5-class natural breaks. Underserved assets: red markers, size 3 mm. Overlay shelters as green triangles at size 5 mm.

8. Interpretation Guide

access_class = Critical: >75% of the way from service to critical distance — these cells lack any nearby shelter. Underserved: 55–74%. Watch: 35–54%, within reach but not comfortable. Covered: <35%. Cross-reference underserved assets with Social Vulnerability Index to find vulnerable populations with poor shelter access.

Academic References

Luo, W. & Wang, F. (2003). "Measures of spatial accessibility to health care in a GIS environment." Environment and Planning B, 30(6), 865–884.

Network Emergency Accessibility

Processing ID: planx_urban_resilience:network_emergency_accessibility

1. Overview

Computes road-network distance and travel time from population origins to the nearest shelter using multi-source Dijkstra on a graph built from line-segment vertices. Each origin receives net_dist_m, time_min, an access class, and a QA flag (large_snap_distance if the origin's snap to the graph exceeds 5× the tolerance). Origins classified as Underserved, Critical, or Unreachable are written to a separate underserved layer.

2. Theoretical Background

The graph is constructed by snapping road vertices at a user-defined tolerance, following the node-snapping approach of Cardinal et al. (2011). Shortest paths use multi-source Dijkstra (Dijkstra, 1959) initialised from all destination nodes simultaneously, which reduces the runtime from O(origins × edges log vertices) to O(edges log vertices) — a single traversal of the graph. The engine uses the shared graph builder in processing/accessibility/_network_graph.py.

3. Mathematical Formulation

where \(f\) assigns Covered (≤ target), Watch (≤ mid), Underserved (≤ critical), Critical (> critical), or Unreachable (net_dist = −1).

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by time_min, RdYlGn ramp (reversed: green = fast access, red = slow/critical), 5-class quantile. Underserved origins: red markers. Graph node count and edge count are printed to the Processing log for diagnostic use.

8. Interpretation Guide

qa_flag = large_snap_distance: the origin is far from any road vertex — check the road layer for gaps or increase snap tolerance. not_connected: the road subgraph containing this origin has no path to any destination — the analysis reveals a genuine network-disconnection problem. Feed underserved outputs into Optimal Shelter Siting to find candidate sites that close the access gap.

Academic References

Dijkstra, E.W. (1959). "A note on two problems in connexion with graphs." Numerische Mathematik, 1, 269–271.

Cardinal, J. et al. (2011). "A unified framework for rich routing problems." Computers & Operations Research, 38(5), 831–843.

Network Criticality (edge betweenness proxy)

Processing ID: planx_urban_resilience:network_criticality

1. Overview

For every origin → nearest-destination shortest path on the road network, counts how many times each edge is used. The resulting per-edge count is normalised 0–100 as criticality_score. High-score edges are bottlenecks: closing one forces the most reroutes. This is an offline proxy for edge betweenness centrality — computationally O(O × V log V) against the full O(VE) betweenness.

2. Theoretical Background

Edge betweenness centrality (Girvan & Newman, 2002) measures how many shortest paths traverse an edge. The full computation (Brandes, 2001) is O(VE) and impractical for interactive QGIS use. This algorithm approximates it by running single-source Dijkstra from each origin to its single nearest destination and recording edge usage — an origin–destination (OD) proxy. The engine is in processing/accessibility/network_criticality.py.

3. Mathematical Formulation

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by criticality_score, OrRd ramp, 5-class natural breaks, line width 0.3–1.5 mm (scaled by score). The top 5% of edges (score ≥ 90) are the critical bottlenecks — render these at 1.5 mm in dark red.

8. Interpretation Guide

Edges with criticality_score ≥ 90 are the system's single points of failure — close one and a large share of origins lose their shortest path. score 50–89: important secondary corridors. Feed the output into the Seismic Cascade debris layer: do blocked segments coincide with high-criticality edges? That is the cascade scenario to prioritise. Pair with Evacuation Time Simulation to verify that the bottleneck edges also carry the highest evacuation load.

Academic References

Girvan, M. & Newman, M.E.J. (2002). "Community structure in social and biological networks." Proceedings of the National Academy of Sciences, 99(12), 7821–7826.

Brandes, U. (2001). "A faster algorithm for betweenness centrality." Journal of Mathematical Sociology, 25(2), 163–177.

Evacuation Time Simulation

Processing ID: planx_urban_resilience:evacuation_time_simulation

1. Overview

Greedy capacity-constrained shelter assignment on a road network. Origins with population are assigned to shelters along shortest paths, respecting shelter capacity. An optional timestep queue defers departures when road segments exceed per-interval flow capacity. Outputs include per-origin travel time, delay, and evacuation class; per-shelter utilisation; and per-edge trip count, population load, congestion percentage, and bottleneck score. The Processing log reports P50 and P95 evacuation times.

2. Theoretical Background

The model implements a greedy nearest-capacity assignment (Church & ReVelle, 1974) with optional dynamic queuing. Road capacity comes from either a numeric field or a road-class lookup (arterial = 1800 pph, collector = 1200 pph, local = 600 pph). The timestep-queue mechanism defers departures frame-by-frame when a segment's cumulative load in that interval exceeds its per-interval capacity — a macroscopic approximation of the link-transmission model (Yperman, 2007). The engine is in processing/accessibility/evacuation_simulation.py.

3. Mathematical Formulation

where \(t\) is the timestep index, \(\Delta\) is the timestep interval in minutes, and \(s\) is the assigned shelter. When timestep = 0 (instant mode), \(t = 0\) and assignment is purely greedy by distance.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Origins: categorised by evac_class — OnTime = green, Watch = yellow, Late = orange, Unassigned = red. Edges: graduated by congestion_pct, YlOrRd ramp, line width 0.3–2.0 mm. Shelters: graduated by cap_pct, Blues ramp — full shelters are dark blue.

8. Interpretation Guide

Unassigned origins: either the origin cannot snap to the graph, or all reachable shelters are full — increase shelter capacity or add sites. congestion_pct > 100: the segment's assigned load exceeds its hourly capacity — a bottleneck. P95 evacuation time (in log): the time by which 95% of the assigned population has reached a shelter. Compare instant mode vs timestep-queue mode to see the congestion delay. Feed congested edges into Cost-Benefit Analyzer to rank road-widening interventions.

Academic References

Church, R.L. & ReVelle, C.S. (1974). "The maximal covering location problem." Papers of the Regional Science Association, 32, 101–118.

Yperman, I. (2007). The Link Transmission Model for Dynamic Network Loading. PhD thesis, KU Leuven.

Seismic Cascade: Debris → Network Degradation

Processing ID: planx_urban_resilience:seismic_cascade_accessibility

1. Overview

Pipes the seismic debris polygon output into the road network, drops blocked edges, then re-runs multi-source Dijkstra on the degraded network and compares pre- vs post-hazard accessibility per origin. Outputs include pre- and post-hazard distances, delta, reachability flags, and a status label (Newly cut off / Always cut off / Worse / Same / Recovered). This is the suite's headline cross-domain cascading-hazard analysis.

2. Theoretical Background

Cascading hazard models link a primary event (earthquake) to secondary consequences (network degradation, accessibility loss). The approach follows the NIST Community Resilience Planning Guide methodology: a baseline network model is perturbed by physical damage, and the resulting service gap is measured. The engine builds two graphs — pre (all edges) and post (edges not intersecting debris polygons) — and runs multi-source Dijkstra from all destinations on each. The engine is in processing/accessibility/seismic_cascade.py.

3. Mathematical Formulation

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Categorised by cas_status: Newly cut off = dark red, Always cut off = grey, Worse = orange, Same = green. Pipe into a QGIS layout with the pre and post maps side-by-side for a before/after atlas page.

8. Interpretation Guide

Newly cut off: origins that were reachable pre-quake but are now isolated — the intervention priority class. Worse: still reachable but via a significantly longer detour (≥1% distance increase). Median pre- and post-hazard distances are printed to the log — the gap between them is the aggregate accessibility loss from the scenario. Run this algorithm for multiple Mw values (6.5, 7.0, 7.5) and compare the "Newly cut off" counts to identify the magnitude threshold where the network fails catastrophically.

Academic References

NIST. (2015). Community Resilience Planning Guide for Buildings and Infrastructure Systems. NIST Special Publication 1190.

Optimal Shelter Siting (greedy maximal coverage)

Processing ID: planx_urban_resilience:optimal_shelter_siting

1. Overview

Solves the Maximal Covering Location Problem (MCLP): from a set of candidate shelter sites, pick K so the population covered within a maximum walking distance is maximised. Uses greedy selection — at each step pick the candidate that adds the most uncovered demand. This is a 0.63-of-optimal approximation in the worst case (Cornuéjols et al., 1977) but is the de-facto practical choice. An optional existing-shelter layer pre-covers some demand so the K new picks fill the gaps.

2. Theoretical Background

The MCLP was formalised by Church & ReVelle (1974). The greedy algorithm's approximation bound of (1 − 1/e) ≈ 0.63 was proved by Cornuéjols, Fisher & Nemhauser (1977) for submodular maximisation. In practice, greedy MCLP solutions routinely achieve >95% of the optimal coverage for spatial facility-location problems (Daskin, 2013). The engine uses Euclidean distance for speed; for network-distance coverage, pre-process demand through Network Emergency Accessibility first. The engine is in processing/accessibility/optimal_shelter_siting.py.

3. Mathematical Formulation

where \(C\) = candidate set, \(S\) = already-selected set, \(D\) = demand units, \(r_{\max}\) = coverage radius. Repeat K times.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Categorised by oss_selected: selected = green star markers (size scaled by rank), not selected = small grey circles. Per-step coverage curve is printed to the log — export this to chart cumulative coverage vs K.

8. Interpretation Guide

The per-step log shows diminishing returns — the first 2–3 sites typically cover 60–80% of demand; additional sites add progressively less. Use this curve to justify the K budget. The "top 10 uncovered demand units" log entry identifies the hardest-to-reach populations — these may need mobile response rather than fixed shelters.

Academic References

Church, R.L. & ReVelle, C.S. (1974). "The maximal covering location problem." Papers of the Regional Science Association, 32, 101–118.

Cornuéjols, G., Fisher, M.L. & Nemhauser, G.L. (1977). "Location of bank accounts to optimize float." Management Science, 23(8), 789–810.

Daskin, M.S. (2013). Network and Discrete Location: Models, Algorithms, and Applications. 2nd ed., Wiley.

Evacuation Shelter Arrival Summary

Processing ID: planx_urban_resilience:evacuation_arrival_summary

1. Overview

Post-processes the Evacuation Time Simulation origin outputs into a per-shelter arrival table with optional per-timestep/minute breakdown and a standalone HTML report. The core operational question it answers: "Which shelters fill first, and which receive arrivals late into the evacuation window?" The algorithm bins each origin's evac_min (total evacuation time, including queue delay when timestep mode is active) into timestep-width intervals and aggregates arrival counts per shelter per bin. The output HTML report includes a stacked-bar timeline visualisation showing the arrival profile of each shelter.

2. Theoretical Background

Cumulative arrival curve analysis is a standard tool in emergency operations planning (FEMA, 2019; NIST, 2015). The key metrics — P50 arrival time, P95 arrival time, and time-to-50%-capacity — operationalise the concepts of shelter service speed and catchment balance. A shelter that reaches 90% capacity within the first 10 minutes of an evacuation has a compressed arrival profile: its catchment population is both nearby and unimpeded. A shelter that reaches only 30% capacity after 40 minutes has either a distant catchment, severe congestion on access routes, or both. The arrival-curve shape — steep initial ramp, long tail, bimodal — carries diagnostic information about the road network topology and shelter distribution that a single average access-time figure cannot capture. The engine is in processing/reporting/evacuation_arrival_summary.py.

3. Mathematical Formulation

where \(\Delta\) is the timestep interval in minutes, \(t_o =\) evac_min for origin \(o\), \(s\) is the assigned shelter, and \(B\) is the maximum timestep bin. The summary log also prints P50 and P95 cumulative-percentage arrival times per shelter — the evacuation-operations equivalents of the P50/P95 metrics from the parent simulation.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

The HTML report uses a stacked-bar chart where each shelter is one bar subdivided by timestep-bin colour (early bins = dark green, late bins = orange/red). Shelters with long red tails are the congestion-affected ones needing either capacity expansion or road-network improvements. In the QGIS table, graduate by cumulative_pct at the critical timestep (e.g., 30 minutes) with a RdYlGn (reversed) ramp.

8. Interpretation Guide

Time-to-50%-capacity < 5 minutes: the shelter's catchment is highly localised and uncongested — an efficient assignment. Time-to-90%-capacity > 40 minutes: the shelter's assigned population is taking too long to arrive — either the catchment is too large (geographically distant origins), too congested (bottleneck edges), or both. Cross-reference with the edge-load output from Evacuation Time Simulation: are the edges leading to this shelter at >100% congestion? Shelters with final cumulative_pct < 100%: some assigned origins have evac_min = ∞ (unassigned or stalled in the queue) — check the parent simulation's qa_flag field. Bimodal arrival curves: two distinct peaks suggest two distinct catchment sub-populations — one nearby (first peak) and one distant (second peak); consider splitting the distant catchment to a closer shelter. Use the arrival-summary table to feed the per-shelter P95 arrival time into Optimal Shelter Siting as a coverage-gap diagnostic: shelters with high P95 times are candidates for additional nearby sites.

Academic References

FEMA. (2019). CPG 101: Developing and Maintaining Emergency Operations Plans, Version 3.0. Federal Emergency Management Agency, Washington, DC. DOI: 10.1007/978-3-030-04624-8_5

NIST. (2015). Community Resilience Planning Guide for Buildings and Infrastructure Systems. NIST Special Publication 1190. DOI: 10.6028/NIST.SP.1190

Yperman, I. (2007). The Link Transmission Model for Dynamic Network Loading. PhD thesis, KU Leuven.

Daganzo, C.F. (1994). "The cell transmission model: a dynamic representation of highway traffic consistent with the hydrodynamic theory." Transportation Research Part B, 28(4), 269–287. DOI: 10.1016/0191-2615(94)90002-7

Church, R.L. & ReVelle, C.S. (1974). "The maximal covering location problem." Papers of the Regional Science Association, 32, 101–118. DOI: 10.1007/BF01942293

Daskin, M.S. (2013). Network and Discrete Location: Models, Algorithms, and Applications. 2nd ed., Wiley. DOI: 10.1002/9781118033883

Cova, T.J. & Johnson, J.P. (2003). "A network flow model for lane-based evacuation routing." Transportation Research Part A, 37(7), 579–604. DOI: 10.1016/S0965-8564(03)00007-7

Southworth, F. (1991). "Regional evacuation modeling: a state-of-the-art review." Oak Ridge National Laboratory, ORNL/TM-11740.

Murray-Tuite, P. & Wolshon, B. (2013). "Evacuation transportation modeling: an overview of research, development, and practice." Transportation Research Part C, 27, 25–45. DOI: 10.1016/j.trc.2012.11.005

Stepanov, A. & Smith, J.M. (2009). "Multi-objective evacuation routing in transportation networks." European Journal of Operational Research, 198(2), 435–446. DOI: 10.1016/j.ejor.2008.09.025

6. Air: Exposure Screening

The Air group provides a planning-support exposure grid combining road proximity, industrial/emission-source proximity, sensitive-receptor density, and green-buffer mitigation. It is a spatial screening index, not an atmospheric dispersion model.

Air Quality / Urban Exposure (screening)

Processing ID: planx_urban_resilience:air_quality_exposure_screening

1. Overview

Scores each grid cell for air-quality exposure using four additive components: road proximity risk (distance to major traffic corridors), emission-source proximity (industrial/point sources), sensitive-receptor density (schools, hospitals, housing clusters), and green-buffer mitigation (tree belts and green patches that reduce exposure). The composite subtracts the green-buffer term — green infrastructure reduces the score.

2. Theoretical Background

Proximity-based air-quality screening follows the land-use regression (LUR) tradition (Briggs et al., 1997; Hoek et al., 2008), where road distance and source proximity are the strongest predictors of intra-urban NO₂ and PM₁₀ variation. The green-buffer mitigation term draws on the meta-analysis of Nowak et al. (2006), who found urban tree cover reduces local particulate concentrations by 7–24%. The engine is in processing/air/air_quality_exposure.py.

3. Mathematical Formulation

where \(R\) = road proximity score (0–100), \(S\) = source proximity score, \(E\) = sensitive-receptor score (count × 25), \(G\) = green-buffer area share, and the final subtraction can reduce but not zero the score.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by air_score, Purples ramp, 5-class natural breaks. Exposed receptors: red markers. Overlay with the heat-risk grid to find cells that are both hot AND polluted — double environmental burden.

8. Interpretation Guide

air_score ≥ 75: cells within 50 m of a major road, downwind of an industrial source, and lacking green buffers — the environmental-justice hotspots. Cross-reference with Social Vulnerability Index to test the double-burden hypothesis. Feed exposed receptors into Recommended Actions Report for curated intervention checklists.

Academic References

Briggs, D.J. et al. (1997). "Mapping urban air pollution using GIS: a regression-based approach." International Journal of Geographical Information Science, 11(7), 699–718.

Nowak, D.J., Crane, D.E. & Stevens, J.C. (2006). "Air pollution removal by urban trees and shrubs in the United States." Urban Forestry & Urban Greening, 4(3–4), 115–123.

7. Drought: Green Infrastructure Stress

The Drought group ranks parks, green patches, and tree-canopy polygons by drought and thermal stress sensitivity using impervious context, distance to water, patch size, and tree density. It is an ecological planning-support index, not a plant-physiology or irrigation model.

Drought and Green Infrastructure Stress

Processing ID: planx_urban_resilience:green_infrastructure_drought_stress

1. Overview

For each green-infrastructure polygon, computes four stress components: impervious context (share of impervious surface in a buffer around the patch), water distance (distance to nearest blue infrastructure), patch size sensitivity (smaller patches = more vulnerable to edge effects and drought), and tree density deficit (sparse tree cover within the patch). The weighted composite is a 0–100 stress score. Patches scoring ≥55 are written to a priority-intervention layer.

2. Theoretical Background

The stress model draws on island biogeography (MacArthur & Wilson, 1967) — smaller patches have higher edge-to-core ratios and are more sensitive to surrounding land use — and urban-ecology findings that impervious surfaces within 100–200 m of a green patch raise its local temperature and water stress (McDonald et al., 2008). Tree density thresholds follow the i-Tree Eco sampling protocol (Nowak et al., 2008). The engine is in processing/drought/green_infrastructure_stress.py.

3. Mathematical Formulation

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by stress_score, YlOrBr ramp, 5-class natural breaks. High-priority patches: darker outline, 0.8 mm stroke. Overlay with the heat-risk grid to identify patches that are both stressed AND in hot areas — these need both irrigation and shade-tree planting.

8. Interpretation Guide

stress_score ≥ 75: small, isolated patches surrounded by impervious surfaces, far from water, with sparse trees — acute drought vulnerability. tree_count = 0: the patch has no tree points at all — a planting opportunity. Feed high-priority patches into Cost-Benefit Analyzer to rank irrigation and tree-planting interventions by cost-effectiveness. Cross-reference with Population-Weighted Exposure (using nearby population polygons) to quantify the human population dependent on each stressed green space.

Academic References

MacArthur, R.H. & Wilson, E.O. (1967). The Theory of Island Biogeography. Princeton University Press.

McDonald, R.I. et al. (2008). "The implications of current and future urbanization for global protected areas and biodiversity conservation." Biological Conservation, 141(6), 1695–1703.

Nowak, D.J. et al. (2008). "A ground-based method of assessing urban forest structure and ecosystem services." Arboriculture & Urban Forestry, 34(6), 347–358.

8. Synthesis: Multi-Hazard, Adaptation & Priority

The Synthesis group is the intellectual core of the suite — 16 algorithms that compose, compare, prioritise, and stress-test resilience scores. They fall into four sub-themes: spatial joins (Join Scores to Planning Units brings hazard-layer outputs onto a common polygon layer), composite indices (Climate Adaptation Priority, Multi-Hazard Composite, Recovery Capacity, Hazard Frequency), equity and climate adjustment (Equity-Adjusted Priority, Climate Projection Overlay), and prioritisation (Risk-Recovery Matrix, Scenario Sensitivity, Population-Weighted Exposure, Critical Infrastructure Exposure, Vulnerability Surface IDW).

Join Hazard Scores to Planning Units

Processing ID: planx_urban_resilience:join_scores_to_planning_units

1. Overview

Spatially joins up to five hazard/score layers onto planning-unit polygons by taking the maximum score among intersecting features. This is the standard "collect and align" step after running hazard modules: join the Heat, Flood, Social, Air, and Drought score fields onto a common neighbourhood or grid-cell layer, then feed the result into Multi-Hazard Composite or Adaptation Priority Synthesis. The output planning units preserve all original attributes and accumulate new numeric score columns ready for composite-index construction.

2. Theoretical Background

The max-intersection spatial join is a conservative aggregation strategy grounded in the precautionary principle of environmental risk assessment (Kriebel et al., 2001; Stirling, 2007). When a planning unit intersects multiple source features with different scores, the maximum is taken — if any part of the unit is exposed to a high score, the whole unit inherits that score. This avoids the dilution problem of areal-weighted averaging, where a small high-hazard sliver (e.g., a flood-prone stream corridor crossing a large census tract) is averaged away by the tract's predominantly low-hazard area (Gotway & Young, 2002). The cost is potential overestimation: a unit with 90% low-risk area and 10% high-risk area is classified entirely at the high-risk level. Users who require areal-weighted joins should pre-process with zonal statistics in QGIS or GRASS. The engine is in processing/synthesis/join_scores_to_units.py.

3. Mathematical Formulation

where \(u\) is a planning unit, \(S\) is the joined score source layer, \(f_s\) is the numeric score field value on feature \(f\), and \(\text{clamp}\) bounds the result to \([0, 100]\). If no source feature intersects the unit (or all intersecting features have NULL scores), the output field is NULL for that unit. The max operator is applied independently per source layer; no cross-layer normalisation is performed.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

After joining, the planning-unit layer carries multiple score columns. Visualise each score independently with a graduated renderer before building composites — this reveals spatial concordance/discordance between hazard dimensions. Recommended: Apply Resilience Symbology with preset "Risk score 0–100" for each joined column.

8. Interpretation Guide

NULL score fields: the planning unit's geometry does not intersect any feature in that source layer. For grid-based source layers (e.g., Heat Risk Grid), this typically means the unit lies outside the study-area extent used when generating the grid. For vector-based sources, check that both layers share the same CRS and that source features cover the full extent of the planning units. All scores = 0 on the same feature: the source layers may be using a neutral default for missing data — verify the source field names are correct. Cross-score consistency check: sort planning units by each joined score and compare the top-10 lists. If the same units dominate all hazards, the study area has a concentrated multi-hazard problem; if the lists are disjoint, the hazards are spatially independent and the composite must respect that separation.

Academic References

Kriebel, D., Tickner, J., Epstein, P., Lemons, J., Levins, R., Loechler, E.L., Quinn, M., Rudel, R., Schettler, T. & Stoto, M. (2001). "The precautionary principle in environmental science." Environmental Health Perspectives, 109(9), 871–876. DOI: 10.1289/ehp.01109871

Gotway, C.A. & Young, L.J. (2002). "Combining incompatible spatial data." Journal of the American Statistical Association, 97(458), 632–648. DOI: 10.1198/016214502760047140

Stirling, A. (2007). "Risk, precaution and science: towards a more constructive policy debate." EMBO Reports, 8(4), 309–315. DOI: 10.1038/sj.embor.7400953

Goodchild, M.F. (2011). "Scale in GIS: an overview." Geomorphology, 130(1–2), 5–9. DOI: 10.1016/j.geomorph.2010.10.004

Openshaw, S. (1984). "The modifiable areal unit problem." Concepts and Techniques in Modern Geography, 38. Geo Books, Norwich.

Fotheringham, A.S. & Wong, D.W.S. (1991). "The modifiable areal unit problem in multivariate statistical analysis." Environment and Planning A, 23(7), 1025–1044. DOI: 10.1068/a231025

Flowerdew, R. & Green, M. (1992). "Developments in areal interpolation methods and GIS." The Annals of Regional Science, 26(1), 67–78. DOI: 10.1007/BF01581481

Cutter, S.L., Boruff, B.J. & Shirley, W.L. (2003). "Social vulnerability to environmental hazards." Social Science Quarterly, 84(2), 242–261. DOI: 10.1111/1540-6237.8402002

Climate Adaptation Priority Synthesis

Processing ID: planx_urban_resilience:climate_adaptation_priority_synthesis

1. Overview

Combines up to six 0–100 hazard/deficit score fields already joined onto a common polygon layer into a single weighted adapt_score. Outputs the composite, a priority class, the top three driving hazards (with their scores), and a list of missing fields.

2. Theoretical Background

This is a linear weighted-sum multi-criteria decision analysis (MCDA) model — the simplest and most transparent form, following the ISO 14044 lifecycle impact assessment aggregation convention. Weight defaults reflect a balanced-all-hazards prior: heat 0.20, flood 0.20, social 0.20, air 0.15, access 0.15, drought 0.10. The engine is in processing/synthesis/adaptation_priority_synthesis.py.

3. Mathematical Formulation

Missing fields are excluded; their weight is redistributed across present fields.

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by adapt_score, RdYlGn ramp (reversed), 5-class natural breaks. Add labels showing the drivers field for the top 10 units.

8. Interpretation Guide

adapt_class = Immediate: units where multiple hazards score ≥75 simultaneously. drivers: tells you which hazard(s) dominate — "flood:92.1, heat:45.0" means the unit is a flood priority, not a heat priority. Use this to assign hazard-specific interventions. Feed into Equity-Adjusted Priority to re-rank by vulnerability. Feed into Risk-Recovery Priority Matrix with rc_score to find high-hazard + low-recovery gaps.

Multi-Hazard Composite Index

Processing ID: planx_urban_resilience:multi_hazard_composite_index

1. Overview

Combines N hazard score fields (each 0–100) per planning unit into a single composite with diagnostic transparency: which hazard dominates?, how diverse is the stress profile?, and how many data gaps exist? The Adaptation Priority Synthesis collapses everything to one score; this algorithm keeps the breakdown visible.

2. Theoretical Background

The multi-hazard index draws on the IPCC AR5 "reasons for concern" framework, where multiple climate risks are assessed jointly. The Shannon entropy diversity index transforms the hazard profile into a 0–100 measure where 0 = a single hazard explains everything (concentrated risk) and 100 = all hazards contribute equally (diffuse, multi-stressed risk). The engine is in processing/synthesis/multi_hazard_composite.py.

3. Mathematical Formulation

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by mh_score, RdYlGn (reversed). Bivariate option: mh_score × mh_diversity via Bivariate Choropleth Symbology — high-score + low-diversity = concentrated single-hazard risk; high-score + high-diversity = diffuse multi-hazard stress (arguably harder to address).

8. Interpretation Guide

mh_dominant: the hazard to target first. mh_diversity ≥ 70: the unit is genuinely multi-stressed — a single-hazard intervention won't suffice. mh_data_gap > 0: the composite is based on incomplete data; the missing hazards are not factored in. Units combining high mh_score with high mh_diversity are the most complex cases — feed them into Scenario Sensitivity Analysis to test whether their rank is stable under weight uncertainty.

Equity-Adjusted Adaptation Priority

Processing ID: planx_urban_resilience:equity_adjusted_priority

1. Overview

Re-ranks adaptation priority by multiplying a hazard/composite score (0–100) by an equity factor derived from the Social Vulnerability Index. Units that are both high-hazard and high-vulnerability rise to the top. The equity weight w controls amplification: w = 0 returns the raw hazard score; w = 1 doubles the score at SVI = 100.

2. Theoretical Background

The equity adjustment follows the distributive-justice framework for climate adaptation (Shi et al., 2016), which argues that adaptation resources should be allocated proportionally to both physical exposure AND social vulnerability. The multiplicative form factor = 1 + w × (SVI/100) ensures that at w = 0, the output equals the input (no equity adjustment), and at w = 1, a fully vulnerable unit (SVI = 100) doubles in priority.

3. Mathematical Formulation

5. Parameters

6. Output Description

7. Symbolic Representation

Side-by-side maps: raw hazard score (OrRd) vs equity-adjusted score (same ramp). The units that change colour the most are the equity story — map them with labels showing both scores.

8. Interpretation Guide

Units where eq_adjusted_score > eq_hazard by >10 points are the equity findings: physically moderate hazard but high social vulnerability pushes them up the priority list. Use w = 0.5 (default) for balanced prioritisation; use w = 1.0 for a strongly equity-first ranking.

Academic References

Shi, L. et al. (2016). "Roadmap towards justice in urban climate adaptation research." Nature Climate Change, 6(2), 131–137. DOI: 10.1038/nclimate2841

Climate Projection Overlay

Processing ID: planx_urban_resilience:climate_projection_overlay

1. Overview

Applies a literature-based amplification factor to a today's hazard/composite score so planners can see the unit-level impact of a warming scenario. Offline-first — no CMIP/downscaled rasters required. Built-in scenarios: Stable (×1.00), Mild +1.5°C ~2050 (×1.15), Moderate +2°C ~2070 (×1.30), High +3°C ~2100 (×1.60), plus a custom override. Outputs include projected score, delta, and delta class.

2. Theoretical Background

The amplification factors are drawn from the IPCC AR6 WG1 regional fact sheets, which project heatwave frequency increases of 1.3–1.6× per degree of warming, and flood magnitude increases of 1.1–1.5×. Because this is a generic overlay, users should run it once per hazard with hazard-specific custom factors. The engine is in processing/synthesis/climate_projection_overlay.py.

3. Mathematical Formulation

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by cp_delta, diverging RdBu ramp (blue = improved/stable, red = major increase), 5-class. Overlay with today's score as a hatch pattern for the compounding effect: high today + high delta = the worst future.

8. Interpretation Guide

cp_delta_class = Major increase (>25 points): units that cross a risk-class threshold under the scenario — e.g. from Moderate (45) to High (72). These are the units where climate change qualitatively changes the risk profile. Run for all four built-in scenarios and compare the "Major increase" counts to show the non-linear escalation of risk.

Academic References

IPCC. (2021). Climate Change 2021: The Physical Science Basis. Contribution of Working Group I to the Sixth Assessment Report. Cambridge University Press.

Recovery Capacity Index

Processing ID: planx_urban_resilience:recovery_capacity_index

1. Overview

Measures the opposite side of resilience — how well a unit can bounce back after a shock. Composites four offline-derivable proxies: land-use diversity (HHI-based from multiple share fields), redundancy (road-access count, scaled), green coverage (0–1 or 0–100), and social cohesion (0–100 proxy, e.g. home-ownership rate). Missing sub-scores are excluded from the weighted mean. Outputs each sub-score, the composite, a class, and a data-gap count.

2. Theoretical Background

The index operationalises the "adaptive capacity" dimension of the IPCC AR5 vulnerability framework (IPCC, 2014). Diversity uses the Hirschman-Herfindahl Index (HHI) adapted for land-use entropy (Cervero & Kockelman, 1997). Redundancy follows the "multiple paths" principle from network resilience theory (Gao et al., 2016). Green coverage and social cohesion are drawn from the recovery-capacity indicators validated by Cutter et al. (2014). The engine is in processing/synthesis/recovery_capacity_index.py.

3. Mathematical Formulation

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by rc_score, Greens ramp (high = good recovery), 5-class natural breaks. Pair with Risk-Recovery Priority Matrix using this as the recovery field.

8. Interpretation Guide

rc_score < 20 (Very Low): units with zero or one sub-score — they lack the economic, infrastructural, and social resources to self-recover. rc_class = Very High (≥80): well-connected, diverse, green neighbourhoods — they can absorb shocks. The gap between Climate Adaptation Priority (risk side) and Recovery Capacity (response side) is the resilience deficit — feed both into Risk-Recovery Priority Matrix.

Academic References

Cutter, S.L., Ash, K.D. & Emrich, C.T. (2014). "The geographies of community disaster resilience." Global Environmental Change, 29, 65–77.

Cervero, R. & Kockelman, K. (1997). "Travel demand and the 3Ds: density, diversity, and design." Transportation Research Part D, 2(3), 199–219.

Gao, J., Barzel, B. & Barabási, A.L. (2016). "Universal resilience patterns in complex networks." Nature, 530, 307–312.

Risk-Recovery Priority Matrix

Processing ID: planx_urban_resilience:risk_recovery_priority_matrix

1. Overview

Combines a hazard/adaptation score (0–100) with a recovery capacity score (0–100) into a single priority: high hazard + low recovery → highest priority. Uses the same multiplicative-deficit form as Equity-Adjusted Priority: priority = hazard × (1 + w × deficit/100), where deficit = 100 − recovery. Normalised back to 0–100.

2. Theoretical Background

This is a bivariate risk matrix — the standard decision-support tool in ISO 31000 risk management. The multiplicative form follows the "risk = hazard × vulnerability / coping capacity" convention of the UNDRR Global Risk Assessment Framework (GAR, 2019). The engine is in processing/synthesis/risk_recovery_priority.py.

3. Mathematical Formulation

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by rr_priority_score, YlOrRd ramp, 5-class natural breaks. Add labels showing rr_hazard and rr_recovery for the top 10 units. Alternatively, use Bivariate Choropleth Symbology with risk and recovery axes for a 3×3 matrix.

8. Interpretation Guide

rr_priority_class = Immediate: high hazard AND low recovery — the intervention gap where resources matter most. High hazard + High recovery: exposed but resilient — monitoring may suffice. Use the matrix to triage a long list of planning units into four quadrants: Act now (↑↓), Prepare (↑↑), Support recovery (↓↓), Monitor (↓↑).

Academic References

UNDRR. (2019). Global Assessment Report on Disaster Risk Reduction. United Nations Office for Disaster Risk Reduction, Geneva.

Hot-Spot Cluster Analysis (Getis-Ord Gi*)

Processing ID: planx_urban_resilience:hotspot_analysis_getis_ord

1. Overview

Tags each feature as a statistically significant hot spot (cluster of high values), cold spot (cluster of low values), or not significant using the Getis-Ord Gi* local statistic. Supports inverse-distance and fixed-distance spatial weights. Includes Benjamini-Hochberg FDR-adjusted p-values and class labels to control for multiple testing across n simultaneous local tests. Pure Python implementation — no numpy dependency.

2. Theoretical Background

Getis & Ord (1992) and Ord & Getis (1995) developed the Gi* statistic as a local indicator of spatial association (LISA) complementary to Anselin's Local Moran's I. Gi* measures the degree to which each feature's local neighbourhood mean deviates from the global mean, standardised as a z-score. The FDR adjustment follows Benjamini & Hochberg (1995), controlling the expected proportion of false discoveries among rejected null hypotheses. The engine is in processing/synthesis/hotspot_analysis.py.

3. Mathematical Formulation

where \(s\) is the global standard deviation, \(w_{ij}\) is the spatial weight (inverse-distance or binary), and self is included (Gi* not Gi).

5. Parameters

6. Output Description

7. Symbolic Representation

Categorised by gi_class_fdr: Hot-99 = dark red, Hot-95 = red, Hot-90 = light red, Not significant = grey, Cold-90 = light blue, Cold-95 = blue, Cold-99 = dark blue. Use on any 0–100 score: composite, SVI, recovery capacity.

8. Interpretation Guide

Hot-99 (FDR): features whose local mean is significantly higher than the global mean at p < 0.01 after FDR correction — the strongest spatial-concentration signal. Not significant (FDR): features where the clustering evidence is weak after correcting for multiple tests. The raw gi_class will always show more significant features than gi_class_fdr — FDR is more conservative. Run Gi* on the same score with different distance bands (250, 500, 1000 m) to explore the scale of clustering.

Academic References

Getis, A. & Ord, J.K. (1992). "The analysis of spatial association by use of distance statistics." Geographical Analysis, 24(3), 189–206.

Ord, J.K. & Getis, A. (1995). "Local spatial autocorrelation statistics: distributional issues and an application." Geographical Analysis, 27(4), 286–306.

Benjamini, Y. & Hochberg, Y. (1995). "Controlling the false discovery rate." Journal of the Royal Statistical Society: Series B, 57(1), 289–300.

LISA Local Moran's I (cluster + outlier)

Processing ID: planx_urban_resilience:lisa_local_moran

1. Overview

Companion to Hot-Spot Gi* — adds outlier detection to cluster detection. Tags each feature as HH (high-high cluster), LL (low-low cluster), HL (high-low outlier — a high-value feature in a low-value neighbourhood), LH (low-high outlier), or Not significant. The HL and LH classes expose under-served pockets Gi* cannot identify. Uses Anselin (1995) analytic randomization moments for significance and Benjamini-Hochberg FDR adjustment.

2. Theoretical Background

Anselin (1995) defined the Local Moran's I as \(I_i = z_i \sum_j w_{ij} z_j\), decomposing the global Moran statistic into per-feature contributions. The randomization moments (eq. 13–14 in Anselin 1995) give E[I_i] and Var[I_i] per feature from row-standardised weights and sample kurtosis. The engine is in processing/synthesis/lisa_local_moran.py.

3. Mathematical Formulation

Quadrant: z_i > 0, lag > 0 → HH; z_i < 0, lag < 0 → LL; z_i > 0, lag < 0 → HL; z_i < 0, lag > 0 → LH.

5. Parameters

Same as Hot-Spot Gi*: INPUT, VALUE_FIELD, DISTANCE, WEIGHT_METHOD.

6. Output Description

7. Symbolic Representation

Categorised by lisa_quad_fdr: HH = dark red, LL = dark blue, HL = pink (high in a low neighbourhood), LH = light blue (low in a high neighbourhood), Not significant = light grey. The HL and LH outliers are the map's most policy-relevant features — label them with both the feature's own value and its neighbourhood's mean.

8. Interpretation Guide

HL (high-low outlier): a high-value unit surrounded by low-value neighbours — in resilience context, this is a well-resourced pocket in an under-served district. LH (low-high outlier): a low-value unit surrounded by high-value neighbours — the equity gap Gi* cannot see. Feed HL and LH units into Equity-Adjusted Priority to see whether the equity adjustment changes their rank. The Processing log prints a breakdown of quadrant counts for both raw and FDR-adjusted significance.

Academic References

Anselin, L. (1995). "Local indicators of spatial association — LISA." Geographical Analysis, 27(2), 93–115.

Population-Weighted Exposure

Processing ID: planx_urban_resilience:population_weighted_exposure

1. Overview

Translates a 0–100 hazard score into a human-impact estimate: how many people live inside each risk class? Population comes from either a field on the scored layer or a separate point/polygon layer. Per-unit outputs: pop_total, pop_exposed (= score/100 × pop), exposure_intensity, exposure_class. The Processing log prints a study-area summary: total population, breakdown by risk class, and top 10 units by exposed population.

2. Theoretical Background

Population-weighted exposure is the standard bridge from physical hazard to human impact in the disaster-risk literature (UNDRR, 2019). The linear exposure model (exposed = score/100 × pop) assumes risk is proportional to the hazard score — a first-order approximation that is transparent and defensible for screening. The engine is in processing/synthesis/population_weighted_exposure.py.

3. Mathematical Formulation

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by pop_exposed, OrRd ramp, 5-class natural breaks. The study-area summary table in the log is formatted for direct paste into a report.

8. Interpretation Guide

pop_exposed > 5 000: large exposed populations — the humanitarian-priority units. The log's "Top units by exposed population" table is the audience-ready headline. Compare pop_exposed rankings with the raw score rankings: units with moderate hazard but very high population may rank higher on exposure than on hazard — a classic finding that justifies this module's existence.

Multi-Period Hazard Frequency Aggregation

Processing ID: planx_urban_resilience:hazard_frequency_aggregation

1. Overview

Collapses 2–8 temporal hazard snapshots (e.g., flood model runs for 2020/2030/2050, or seismic Monte Carlo across multiple magnitudes) into one composite score per planning unit. Captures both frequency (how many periods scored above threshold) and intensity (mean/max/min across periods). Three aggregation modes: Mean of all periods, Maximum, or Frequency-weighted mean (mean × freq/N — units high in both many periods AND high intensity rise to the top).

2. Theoretical Background

Multi-period hazard aggregation addresses the temporal compounding problem in risk assessment (IPCC, 2012; Zscheischler et al., 2018). A single hazard snapshot (e.g., a 100-year flood map at current sea level) captures spatial variation at one point in time but misses the temporal persistence dimension: a unit that scores 80 in every period represents a fundamentally different risk profile from one that scores 95 in one period and 30 in all others, even if their mean scores are identical. The frequency-weighted mean aggregation mode operationalises the IPCC AR5 "Reasons for Concern" framework (IPCC, 2014), where both the magnitude and the frequency of climate impacts determine the risk level. The default threshold of 50 corresponds to the Moderate/High breakpoint in the suite's standard classification, ensuring that "above-threshold" represents at least a "High" classification. The max-intersection spatial join (same conservative convention as Join Scores to Planning Units) ensures that the unit inherits the highest score from each source layer. The engine is in processing/synthesis/hazard_frequency.py.

3. Mathematical Formulation

where \(N\) is the number of source layers (2–8), \(s_k(u)\) is the maximum intersecting score from source layer \(k\) at planning unit \(u\), \(\tau\) is the frequency threshold (default 50), and \([\cdot]\) is the Iverson bracket. All scores are clamped to \([0, 100]\). The frequency-weighted mean penalises units that are high in only a few periods: a unit with mean 80 and freq = 1/5 gets a composite of 16, while a unit with mean 80 and freq = 5/5 keeps 80.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by hf_composite, YlOrRd ramp, 5-class natural breaks. For temporal analysis, create a small-multiples layout: one map per source period in a row, with the composite map below. Use labels on hf_frequency to annotate composite values so the viewer sees both "how bad" and "how persistent".

8. Interpretation Guide

hf_frequency = N (all periods above threshold): persistent, chronic exposure — these units need structural, long-term adaptation, not just emergency response. hf_frequency = 1, hf_max ≥ 75: a single-period spike — investigate whether this is a real trend driven by a specific scenario assumption or a model artefact. Compare the mean and max: if max ≫ mean, the unit has high inter-period variability (one bad year, several mild years). If max ≈ mean, the exposure is stable across periods. Frequency-weighted mean (default): use this for prioritisation when both persistence and intensity matter — it is the most conservative composite for identifying units that are chronically exposed. Mean mode: use when you want to compare average exposure independent of persistence. Max mode: useful for worst-case preparedness planning.

Academic References

IPCC. (2012). Managing the Risks of Extreme Events and Disasters to Advance Climate Change Adaptation (SREX). Cambridge University Press. DOI: 10.1017/CBO9781139177245

IPCC. (2014). Climate Change 2014: Impacts, Adaptation, and Vulnerability. Part A: Global and Sectoral Aspects. Cambridge University Press.

Zscheischler, J., Westra, S., van den Hurk, B.J.J.M., Seneviratne, S.I., Ward, P.J., Pitman, A., AghaKouchak, A., Bresch, D.N., Leonard, M., Wahl, T. & Zhang, X. (2018). "Future climate risk from compound events." Nature Climate Change, 8(6), 469–477. DOI: 10.1038/s41558-018-0156-3

AghaKouchak, A., Chiang, F., Huning, L.S., Love, C.A., Mallakpour, I., Mazdiyasni, O., Moftakhari, H., Papalexiou, S.M., Ragno, E. & Sadegh, M. (2020). "Climate extremes and compound hazards in a changing world." Annual Review of Earth and Planetary Sciences, 48, 519–548. DOI: 10.1146/annurev-earth-071719-055228

Ward, P.J., Jongman, B., Aerts, J.C.J.H., Bates, P.D., Botzen, W.J.W., Diaz Loaiza, A., Hallegatte, S., Kind, J., Kwadijk, J., Scussolini, P. & Winsemius, H.C. (2017). "A global framework for future costs and benefits of river-flood protection in urban areas." Nature Climate Change, 7(9), 642–646. DOI: 10.1038/nclimate3350

Hallegatte, S., Green, C., Nicholls, R.J. & Corfee-Morlot, J. (2013). "Future flood losses in major coastal cities." Nature Climate Change, 3(9), 802–806. DOI: 10.1038/nclimate1979

UNDRR. (2019). Global Assessment Report on Disaster Risk Reduction. United Nations Office for Disaster Risk Reduction, Geneva.

Kreibich, H., Di Baldassarre, G., Vorogushyn, S., Aerts, J.C.J.H., Apel, H., Aronica, G.T., Arnbjerg-Nielsen, K., Bouwer, L.M., Bubeck, P., Caloiero, T. et al. (2017). "Adaptation to flood risk: results of international paired flood event studies." Earth's Future, 5(10), 953–965. DOI: 10.1002/2017EF000606

Vulnerability Surface (IDW interpolation)

Processing ID: planx_urban_resilience:vulnerability_surface_idw

1. Overview

Interpolates sparse point measurements (sensor readings, survey scores, social-cohesion samples) into a continuous surface as polygon grid cells using inverse-distance weighting (IDW). Parameters: IDW power (higher = sharper local peaks), optional search radius, and optional neighbour cap. Pure Python — no raster dependencies.

2. Theoretical Background

Inverse-distance weighting (Shepard, 1968) is the simplest deterministic spatial interpolator. It assumes values at unobserved locations are a distance-weighted average of observed values. The power parameter controls locality: p = 1 gives gentle gradients; p = 4 gives sharp peaks around each sample. The engine is in processing/synthesis/vulnerability_surface_idw.py.

3. Mathematical Formulation

5. Parameters

6. Output Description

8. Interpretation Guide

vs_n_points = 0: no source point within radius — the cell is an extrapolation gap. Reduce IDW power or increase radius. vs_n_points = 1: the cell's value equals the single nearest point — an exact-interpolation artefact; consider increasing radius.

Academic References

Shepard, D. (1968). "A two-dimensional interpolation function for irregularly-spaced data." Proceedings of the 1968 ACM National Conference, 517–524.

Critical Infrastructure Exposure

Processing ID: planx_urban_resilience:critical_infrastructure_exposure

1. Overview

Crosses a hazard score layer with a critical-facility layer (schools, hospitals, fire stations, power/water assets) to produce a combined exposure score. Each facility's hazard score is sampled at its centroid using spatial containment against hazard polygons. A user-supplied criticality field (numeric, any scale) is min-max normalised to 0–100 across all facilities. The combined score = (hazard/100) × criticality_norm × 100, producing a joint measure that elevates facilities that are both highly exposed AND highly critical — the right shortlist for retrofit and hardening programmes. The Processing log prints the top 10 most exposed facilities and the mean combined score by facility class.

2. Theoretical Background

Critical infrastructure exposure analysis bridges two parallel literatures: natural hazard risk assessment (where exposure is "what is in harm's way") and infrastructure systems engineering (where criticality is "what function is lost if this asset fails"). The multiplicative form — hazard × criticality — follows the standard risk equation \(R = H \times V \times E\) codified in the UNDRR Global Risk Assessment Framework (UNDRR, 2019) and the IPCC AR5 risk framework (IPCC, 2014). The min-max normalisation of the criticality field is a pragmatic choice: it makes the algorithm usable with any user-supplied criticality scale (1–5, 1–100, monetary replacement value, population served, etc.) without prior knowledge of the scale bounds. The centroid-based hazard sampling is conservative: a facility is considered exposed if its geographic centre lies inside a hazard polygon — this avoids the complexity of partial-overlap weighting while ensuring that polygon facilities (e.g., a hospital campus spanning multiple blocks) are assessed at a representative location. The engine is in processing/synthesis/critical_infrastructure_exposure.py.

3. Mathematical Formulation

where \(H_i\) is the hazard score (0–100) at facility \(i\)'s centroid, \(c_i\) is the raw criticality value, and \(E_i\) is the combined exposure score (0–100). If no hazard polygon contains the facility centroid (e.g., the facility lies outside the hazard model extent), \(H_i = 0\).

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by ci_combined, OrRd ramp, 5-class natural breaks. For facilities, use circles scaled by ci_combined (2–8 mm) with dark stroke. Label the top 5 facilities by name from the log. Overlay with the hazard layer at 30% opacity for context. The log's "Mean combined score by facility class" table is suitable for direct inclusion in a report.

8. Interpretation Guide

ci_exposure_class = Critical (≥75): a facility that is both in a high-hazard zone AND highly critical — the top retrofit/hardening priority. ci_hazard high but ci_combined moderate: a critical facility in a low-hazard area — its criticality is normalised but its location is favourable. This is a resilience asset, not a priority target. ci_hazard and ci_criticality both are uniformly distributed: all facilities get similar combined scores; the min-max normalisation compresses diversity. In this case, try using a wider criticality scale (e.g., 1–100 instead of 1–5) to spread the distribution. Cross-reference with Social Vulnerability Index: facilities serving high-SVI populations that score Critical on exposure are the equity+exposure double priority. Feed the top-N facilities into Cost-Benefit Analyzer to rank retrofit options by cost-effectiveness.

Academic References

UNDRR. (2019). Global Assessment Report on Disaster Risk Reduction. United Nations Office for Disaster Risk Reduction, Geneva.

IPCC. (2014). Climate Change 2014: Impacts, Adaptation, and Vulnerability. Part A: Global and Sectoral Aspects. Cambridge University Press.

NIST. (2015). Community Resilience Planning Guide for Buildings and Infrastructure Systems. NIST Special Publication 1190. DOI: 10.6028/NIST.SP.1190

Rinaldi, S.M., Peerenboom, J.P. & Kelly, T.K. (2001). "Identifying, understanding, and analyzing critical infrastructure interdependencies." IEEE Control Systems Magazine, 21(6), 11–25. DOI: 10.1109/37.969131

Ouyang, M. (2014). "Review on modeling and simulation of interdependent critical infrastructure systems." Reliability Engineering & System Safety, 121, 43–60. DOI: 10.1016/j.ress.2013.06.040

FEMA. (2018). Seismic Performance Assessment of Buildings, Volume 1 — Methodology (FEMA P-58-1), Second Edition. Washington, DC.

Pederson, P., Dudenhoeffer, D., Hartley, S. & Permann, M. (2006). Critical Infrastructure Interdependency Modeling: A Survey of U.S. and International Research. Idaho National Laboratory, INL/EXT-06-11464.

Cutter, S.L., Ash, K.D. & Emrich, C.T. (2014). "The geographies of community disaster resilience." Global Environmental Change, 29, 65–77. DOI: 10.1016/j.gloenvcha.2014.08.005

Buldyrev, S.V., Parshani, R., Paul, G., Stanley, H.E. & Havlin, S. (2010). "Catastrophic cascade of failures in interdependent networks." Nature, 464, 1025–1028. DOI: 10.1038/nature08932

FEMA. (2003). HAZUS-MH MR4 Technical Manual. Federal Emergency Management Agency, Washington, DC.

Scenario Sensitivity Analysis

Processing ID: planx_urban_resilience:scenario_sensitivity

1. Overview

Stress-tests composite scores by varying component weights via Latin Hypercube Sampling (LHS). Each weight may vary by ± the perturbation fraction around its nominal value. Per unit, computes the baseline composite (nominal weights), mean, standard deviation, p05/p95, range, and a 0–100 stability score (100 = identical across all samples, 0 = highly sensitive). Units with low stability change rank under reasonable weight uncertainty — flag them for qualitative review.

2. Theoretical Background

Latin Hypercube Sampling (McKay, Beckman & Conover, 1979) is a stratified Monte Carlo method that ensures the full range of each weight dimension is explored with fewer samples than brute-force random sampling. In multi-criteria decision analysis, weight sensitivity is the primary source of rank uncertainty (Saltelli et al., 2004). The engine is in processing/synthesis/scenario_sensitivity.py.

5. Parameters

6. Output Description

8. Interpretation Guide

ss_stability < 50: the unit's rank is fragile — changing weights by ±50% shifts its score by more than 12.5 points on average. Flag these units in the report as "rank uncertain; review qualitatively." ss_stability ≥ 90: the unit's score is robust to weight choice — high-confidence prioritisation.

Academic References

McKay, M.D., Beckman, R.J. & Conover, W.J. (1979). "A comparison of three methods for selecting values of input variables." Technometrics, 21(2), 239–245.

Saltelli, A. et al. (2004). Sensitivity Analysis in Practice. Wiley.

Risk Trend Hot-Spot (Gi* x Delta score)

Processing ID: planx_urban_resilience:risk_trend_hotspot

1. Overview

Fuses temporal trend (delta score between two snapshots) with spatial clustering (Getis-Ord Gi* on the later snapshot) into a single label per unit. The nine-class typology — Rising / Stable / Cooling hot spot, Rising / Stable / Cooling cold spot, Hot/Cold no cluster, Not significant — answers the planner question: "which neighbourhoods are both rising in risk AND clustered with other high-risk areas?". This is the suite's early-warning algorithm: a "Rising hot spot" label means the unit is in a spatially concentrated high-value cluster AND its score is increasing.

2. Theoretical Background

The algorithm operates at the intersection of two distinct analytical traditions: temporal trend analysis (longitudinal studies using paired snapshots; Diggle, 2014) and local spatial autocorrelation (Getis & Ord, 1992). The fusion approach follows the space-time scan statistic literature (Kulldorff, 1997) but uses a simpler two-stage method: first compute the hot-spot significance on the most recent data, then annotate with the temporal trajectory. This avoids the computational complexity of full space-time scan statistics while preserving the key operational insight: a hot spot that is rising represents an emerging threat; a hot spot that is cooling represents a successful intervention or natural hazard decline. The 1-point delta tolerance (adjustable) distinguishes genuine change from rounding noise. The significance threshold used is |z| \(\ge\) 1.96, corresponding to a two-sided p < 0.05 under the standard normal approximation. The engine is in processing/synthesis/risk_trend_hotspot.py.

3. Mathematical Formulation

where \(x_j\) is the later-snapshot score, \(\bar{x}\) is the global mean, \(s\) is the global standard deviation, \(r\) is the distance band, \(\Delta_i\) is the per-unit delta (later − earlier), and \(\varepsilon\) is the delta tolerance (default 1.0). The labeling function \(f\) maps the (z-score sign, significance, trend) tuple to one of 9 classes.

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Categorised by trh_label: Rising hot spot = dark red (#b30000), Stable hot spot = red (#e34a33), Cooling hot spot = orange (#fc8d59), Rising cold spot = dark blue (#313695), Stable cold spot = blue (#4575b4), Cooling cold spot = light blue (#91bfdb), Hot no cluster = light red, Cold no cluster = light blue, Not significant = light grey (#cccccc). The Log prints a summary table of label counts for direct report inclusion.

8. Interpretation Guide

Rising hot spot: the strongest early-warning signal — the unit is in a statistically significant high-value cluster AND its score is increasing. These are the immediate-intervention priority units. Cooling hot spot: a clustered high-value unit with a declining score — evidence that an intervention or natural hazard cycle is reducing risk. Document these as success cases. Rising cold spot: a clustered low-value unit with an increasing score — the early stage of what could become a hot spot if the trend continues. Flag for monitoring. Cooling cold spot: clustered low value, still declining — possibly abandonment or disinvestment. Cross-reference with Social Vulnerability Index to check whether declining risk reflects genuine improvement or population displacement. Not significant: the spatial clustering evidence is weak at the 95% level — this unit's score is not spatially structured; its trend is an independent local phenomenon. Run with different distance bands (250 m, 500 m, 1000 m) to test the scale sensitivity of the cluster labels.

Academic References

Getis, A. & Ord, J.K. (1992). "The analysis of spatial association by use of distance statistics." Geographical Analysis, 24(3), 189–206. DOI: 10.1111/j.1538-4632.1992.tb00261.x

Kulldorff, M. (1997). "A spatial scan statistic." Communications in Statistics — Theory and Methods, 26(6), 1481–1496. DOI: 10.1080/03610929708831995

Diggle, P.J. (2014). Statistical Analysis of Spatial and Spatio-Temporal Point Patterns. 3rd ed., CRC Press. DOI: 10.1201/b15326

Ord, J.K. & Getis, A. (1995). "Local spatial autocorrelation statistics: distributional issues and an application." Geographical Analysis, 27(4), 286–306. DOI: 10.1111/j.1538-4632.1995.tb00912.x

Anselin, L. (1995). "Local indicators of spatial association — LISA." Geographical Analysis, 27(2), 93–115. DOI: 10.1111/j.1538-4632.1995.tb00338.x

Rey, S.J. & Anselin, L. (2010). "PySAL: a Python library of spatial analytical methods." In M.M. Fischer & A. Getis (eds.), Handbook of Applied Spatial Analysis, Springer, pp. 175–193. DOI: 10.1007/978-3-642-03647-7_11

Cressie, N. (1993). Statistics for Spatial Data. Revised ed., Wiley. DOI: 10.1002/9781119115151

IPCC. (2021). Climate Change 2021: The Physical Science Basis. Cambridge University Press.

Cutter, S.L. & Finch, C. (2008). "Temporal and spatial changes in social vulnerability to natural hazards." Proceedings of the National Academy of Sciences, 105(7), 2301–2306. DOI: 10.1073/pnas.0710375105

Benjamini, Y. & Hochberg, Y. (1995). "Controlling the false discovery rate." Journal of the Royal Statistical Society: Series B, 57(1), 289–300. DOI: 10.1111/j.2517-6161.1995.tb02031.x

10. Economics: Cost-Benefit, Lifecycle & Optimisation

Three algorithms that move the suite from "where is the risk?" to "what does the response cost, and in what order should we act?". Together they form a budget-allocation pipeline: score interventions → rank by benefit/cost → identify the Pareto frontier → compute lifecycle NPV.

Cost-Benefit Analyzer (planning prioritisation)

Processing ID: planx_urban_resilience:cost_benefit_analyzer

1. Overview

Ranks planning units by cost-effectiveness using a transparent two-input model: cost = unit_cost × area (or per-feature for points), benefit = score × reduction_factor × population_weight. The B/C ratio drives a 1-N priority rank. The Processing log prints the cumulative-benefit curve: "to capture 80% of benefit you need to fund 25% of units."

3. Mathematical Formulation

5. Parameters

6. Output Description

8. Interpretation Guide

The cumulative-benefit curve in the log is the budget-justification exhibit. Free-win features (cost = 0, benefit > 0) are ranked first — these are the no-regret actions. Feed cb_priority_rank == 1 features into Pareto-Optimal Selector to find the cost–benefit frontier.

Academic References

Boardman, A.E. et al. (2018). Cost-Benefit Analysis: Concepts and Practice. 5th ed., Cambridge University Press.

Pareto-Optimal Intervention Selector

Processing ID: planx_urban_resilience:pareto_optimal_selector

1. Overview

Identifies the Pareto frontier of a (cost, benefit) trade-off via non-dominated sorting (NSGA-II style). Each feature receives: pareto_rank (1 = first frontier), pareto_dominated (count of features that strictly dominate it), pareto_dominates (count it dominates). Picking everything with rank = 1 guarantees no objectively better alternative exists — no other feature is both cheaper AND more beneficial. The algorithm is O(N^2) in the number of features; for typical planning-unit layers of 100–2,000 features it completes in under a second.

2. Theoretical Background

Pareto optimality, named after the Italian economist Vilfredo Pareto (1848–1923), is the cornerstone of multi-objective optimisation. The non-dominated sorting algorithm follows the NSGA-II framework of Deb et al. (2002), applied deterministically to an existing feature set. The domination relation is strict: \(a\) dominates \(b\) iff \(a\) is no worse on both objectives AND strictly better on at least one. The frontier-peeling after dominance counting is equivalent to the recursive non-dominated sorting of Kung et al. (1975). The engine is in processing/synthesis/pareto_selector.py.

3. Mathematical Formulation

where \(c\) is cost (lower better), \(b\) is benefit (higher better), and \(D_i\) is the count of features that strictly dominate feature \(i\). Frontier rank \(R_i\) is computed by iteratively peeling the current Pareto frontier (features with no remaining dominator) from the set, assigning rank = 1, 2, 3, ... to successive peels.

5. Parameters

6. Output Description

8. Interpretation Guide

pareto_rank = 1: the budget-bounded best pick set — these features are optimal under any linear cost–benefit weighting scheme. pareto_rank > 3: strictly worse options; fund only if budget exhausts first two frontiers. pareto_dominated ≥ 100: this feature is dominated by many — poor choice regardless of framing. The Processing log prints the feature count per rank; typical distribution is ~5–15% in rank 1. Feed the Cost-Benefit Analyzer output (cb_cost, cb_benefit) into this algorithm to identify interventions on the Pareto frontier.

Academic References

Deb, K., Pratap, A., Agarwal, S. & Meyarivan, T. (2002). "A fast and elitist multiobjective genetic algorithm: NSGA-II." IEEE Transactions on Evolutionary Computation, 6(2), 182–197. DOI: 10.1109/4235.996017

Kung, H.T., Luccio, F. & Preparata, F.P. (1975). "On finding the maxima of a set of vectors." Journal of the ACM, 22(4), 469–476. DOI: 10.1145/321906.321910

Miettinen, K. (1999). Nonlinear Multiobjective Optimization. Springer. DOI: 10.1007/978-1-4615-5563-6

Boardman, A.E., Greenberg, D.H., Vining, A.R. & Weimer, D.L. (2018). Cost-Benefit Analysis: Concepts and Practice. 5th ed., Cambridge University Press.

Malczewski, J. & Rinner, C. (2015). Multicriteria Decision Analysis in Geographic Information Science. Springer. DOI: 10.1007/978-3-540-74757-4

Chankong, V. & Haimes, Y.Y. (1983). Multiobjective Decision Making: Theory and Methodology. North-Holland.

Coello Coello, C.A., Van Veldhuizen, D.A. & Lamont, G.B. (2007). Evolutionary Algorithms for Solving Multi-Objective Problems. 2nd ed., Springer.

Pareto, V. (1906). Manuale di Economia Politica. Societa Editrice Libraria, Milano.

Lifecycle Cost Calculator (25-year NPV)

Processing ID: planx_urban_resilience:lifecycle_cost_calculator

1. Overview

Per planning unit, computes discounted Net Present Value over a configurable horizon (default 25 years) including upfront capex, annual opex, periodic maintenance events, and end-of-life replacement. Outputs the six NPV components plus an equivalent flat annual cost. Optional area scaling multiplies per-m^2 values by polygon area. This is the "total cost of ownership" companion to the Cost-Benefit Analyzer: it answers "what does this intervention cost over its full life?" rather than "which intervention gives the best return per euro?".

2. Theoretical Background

Lifecycle cost analysis (LCCA) is the standard engineering-economics method for comparing long-term investment alternatives (Fuller & Petersen, 1996; ISO 15686-5:2017). The Net Present Value (NPV) framework discounts all future cash flows to their present-value equivalent using a discount rate that reflects the time value of money and, in public-sector applications, the social discount rate (typically 3–7% as recommended by the European Commission, 2014, and OMB Circular A-94). The annualisation formula converts the lump-sum NPV into an equivalent uniform annual cost via the capital recovery factor (also known as the annuity factor), enabling fair comparison between interventions with different lifespans. The default 25-year horizon and 4% discount rate follow the convention for urban infrastructure projects in temperate-climate OECD countries (Boardman et al., 2018). The 5-year maintenance interval default reflects typical green-infrastructure maintenance cycles (irrigation upgrades, canopy planting, drainage desilting). The engine is in processing/synthesis/lifecycle_cost.py.

3. Mathematical Formulation

where \(C\) is upfront capex, \(O\) is annual opex, \(m\) is maintenance cost every \(M\) years, \(q\) is replacement cost every \(R\) years, \(H\) is the analysis horizon, and \(r\) is the annual discount rate. All costs are multiplied by polygon area when AREA_SCALE is enabled for polygon input layers.

5. Parameters

6. Output Description

8. Interpretation Guide

The Processing log prints the sum of lc_total_npv across all features — the programme-level cost. The lc_annualised field is the most communicable number: "this intervention costs EUR X per year, flat, for 25 years." Use it to compare interventions with different horizons and maintenance profiles on a like-for-like basis. lc_maintenance_npv > lc_capex_npv: the intervention is maintenance-heavy — the lifecycle costs are dominated by recurring expenses, not upfront investment. This is common in green infrastructure (regular irrigation, pruning, replanting) and should be accounted for in municipal O&M budgets. DISCOUNT = 0%: use only for undiscounted break-even analysis; for public-sector economic appraisal, 3–5% is standard.

Academic References

Fuller, S.K. & Petersen, S.R. (1996). Life-Cycle Costing Manual for the Federal Energy Management Program. NIST Handbook 135. DOI: 10.6028/NIST.HB.135

European Commission. (2014). Guide to Cost-Benefit Analysis of Investment Projects. Directorate-General for Regional and Urban Policy.

Boardman, A.E., Greenberg, D.H., Vining, A.R. & Weimer, D.L. (2018). Cost-Benefit Analysis: Concepts and Practice. 5th ed., Cambridge University Press. DOI: 10.1017/9781108235594

ISO. (2017). ISO 15686-5:2017 — Buildings and constructed assets — Service life planning — Part 5: Life-cycle costing. International Organization for Standardization.

U.S. Office of Management and Budget. (1992). Circular A-94: Guidelines and Discount Rates for Benefit-Cost Analysis of Federal Programs. Washington, DC.

HM Treasury. (2020). The Green Book: Central Government Guidance on Appraisal and Evaluation. London. DOI: 10.1108/9781787562820-024

NIST. (2015). Community Resilience Planning Guide for Buildings and Infrastructure Systems. NIST Special Publication 1190. DOI: 10.6028/NIST.SP.1190

FEMA. (2018). Seismic Performance Assessment of Buildings, Volume 1 — Methodology (FEMA P-58-1), Second Edition. Washington, DC.

9. Spatial Statistics: Clusters, Outliers & Surfaces

Four algorithms for local spatial analysis. Hot-Spot Gi* (Getis-Ord) and LISA Local Moran's I identify statistically significant clusters and outliers in any 0–100 resilience score. Risk Trend Hot-Spot fuses temporal delta with spatial clustering. Vulnerability Surface IDW interpolates sparse point measurements into continuous polygon grids. All are pure Python — no compiled dependencies. Full documentation for each appears under Group 8 (Synthesis) where they are also registered in the Processing provider.

R. Reporting, Visualisation & QA

The Reporting group provides ten algorithms for output styling, comparison, export, and communication. They transform the numeric scores from the hazard and synthesis modules into studio-ready deliverables: HTML/Markdown reports, PDF atlas pages, styled QGIS layers, 3D GeoJSON exports, correlation matrices, and curated intervention checklists.

Resilience Time-Series Tracker

Processing ID: planx_urban_resilience:resilience_time_series_tracker

1. Overview

Joins two snapshots of a scored layer (e.g., 2020 baseline and 2025 update) on a stable unit ID field. Emits per-unit delta, percent change, trend (Improved / Stable / Worsened), and optional target gap. Geometry is taken from the later snapshot. This is the suite's primary longitudinal-analysis tool — it converts two static maps into a change map suitable for trend analysis, before/after intervention evaluation, and policy-target tracking.

2. Theoretical Background

Longitudinal spatial analysis of risk indicators has become standard practice in climate adaptation monitoring (Cutter & Finch, 2008; Preston et al., 2011). The paired-snapshot approach used here is a two-period panel design — the simplest longitudinal design that can detect direction of change but not acceleration or non-linear trajectories. The trend classification uses a ±1 point deadband around zero to suppress reporting of sub-meaningful fluctuations caused by rounding or data-update noise. The percent change metric normalises the raw delta by the baseline, enabling comparison across units with different baseline scores (a +10 delta from a baseline of 20 is a +50% change; the same +10 from a baseline of 80 is only +12.5%). The optional target gap field operationalises the "distance to policy target" concept from the Sendai Framework's monitoring system (UNDRR, 2019). The engine is in processing/reporting/time_series_tracker.py.

3. Mathematical Formulation

where \(s_i^{(t_0)}\) is the earlier-snapshot score, \(s_i^{(t_1)}\) is the later-snapshot score, and \(\tau\) is the policy target value (default 0 = not used).

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by ts_delta, diverging RdBu ramp (blue = improved, white = stable, red = worsened), 5–7 class equal-interval classification centred on zero. Alternatively, categorised by ts_trend: Improved = green, Stable = grey, Worsened = red. The delta map is the project's core before/after exhibit.

8. Interpretation Guide

ts_trend = No match: the unit ID in the later layer was not found in the earlier layer (new units, boundary changes, or ID scheme mismatch). Check ID field correspondence. ts_delta_pct > 50%: a dramatic change — verify whether this is a genuine risk change or a data collection methodology change between snapshots. ts_target_gap > 0 AND ts_trend = Worsened: the unit is moving away from the policy target — the most concerning trajectory. Feed ts_later_score and ts_delta into Risk Trend Hot-Spot for the fused temporal × spatial label. Feed the full output into Scenario Comparison for before/after delta mapping.

Academic References

Cutter, S.L. & Finch, C. (2008). "Temporal and spatial changes in social vulnerability to natural hazards." Proceedings of the National Academy of Sciences, 105(7), 2301–2306. DOI: 10.1073/pnas.0710375105

Preston, B.L., Yuen, E.J. & Westaway, R.M. (2011). "Putting vulnerability to climate change on the map: a review of approaches, benefits, and risks." Sustainability Science, 6(2), 177–202. DOI: 10.1007/s11625-011-0129-1

UNDRR. (2019). Global Assessment Report on Disaster Risk Reduction. United Nations Office for Disaster Risk Reduction, Geneva.

Füssel, H.M. (2007). "Vulnerability: a generally applicable conceptual framework for climate change research." Global Environmental Change, 17(2), 155–167. DOI: 10.1016/j.gloenvcha.2006.05.002

Adger, W.N. (2006). "Vulnerability." Global Environmental Change, 16(3), 268–281. DOI: 10.1016/j.gloenvcha.2006.02.006

IPCC. (2014). Climate Change 2014: Impacts, Adaptation, and Vulnerability. Part A: Global and Sectoral Aspects. Cambridge University Press.

Cutter, S.L., Boruff, B.J. & Shirley, W.L. (2003). "Social vulnerability to environmental hazards." Social Science Quarterly, 84(2), 242–261. DOI: 10.1111/1540-6237.8402002

Birkmann, J., Cardona, O.D., Carreno, M.L., Barbat, A.H., Pelling, M., Schneiderbauer, S., Kienberger, S., Keiler, M., Alexander, D., Zeil, P. & Welle, T. (2013). "Framing vulnerability, risk and societal responses: the MOVE framework." Natural Hazards, 67(2), 193–211. DOI: 10.1007/s11069-013-0558-5

Scenario Comparison / Delta Map

Processing ID: planx_urban_resilience:scenario_comparison_delta

1. Overview

Compares two 0–100 score fields on the same layer (typically baseline vs proposed after intervention, or two alternative planning scenarios). Outputs delta (scenario − baseline), absolute delta, percent change, change class (Improved / Stable / Worsened), and an action hint. The meaningful-change threshold (default 5 points) filters out noise-level fluctuations from genuine interventions. This is the suite's primary decision-support comparison tool: it quantifies the spatial impact of a proposed intervention and identifies units where the scenario produces a meaningful difference.

2. Theoretical Background

Scenario comparison is a core methodology in sustainability assessment and spatial planning (Swart et al., 2004; Xiang & Clarke, 2003). The delta-map approach — subtracting two spatial fields and mapping the residuals — follows the "comparative statics" tradition in spatial economics and the before/after control-impact (BACI) design in environmental impact assessment (Smith, 2014). The default 5-point threshold for meaningful change eliminates the "small change problem" identified by Openshaw & Taylor (1979): without a threshold, every unit shows some delta, most of which is noise, and the resulting map is uninformative. A 5-point delta on a 0–100 scale represents roughly one-half of a standard classification band, which is both statistically detectable and operationally meaningful. The engine is in processing/reporting/scenario_comparison.py.

3. Mathematical Formulation

where \(b_i^{(0)}\) is the baseline score, \(b_i^{(s)}\) is the scenario score, and \(\tau\) is the meaningful-change threshold (default 5.0). The action hint is derived from the change class: Improved → "Document and replicate", Worsened → "Review scenario drivers", Stable → "Monitor".

4. Input Data Requirements

5. Parameters

6. Output Description

7. Symbolic Representation

Graduated by delta, diverging RdBu ramp (blue = improved, white = stable, red = worsened), 5–7 class classification centred on zero. The delta map is the project's core before/after exhibit. For presentations, create a side-by-side layout: baseline map (left), scenario map (centre), delta map (right).

8. Interpretation Guide

change_cls = Improved with large negative delta (e.g., −30): the scenario/intervention substantially reduces risk — these are the success-story units to document and replicate. change_cls = Worsened with positive delta: the scenario increases risk relative to the baseline — review the scenario parameters; this may indicate a realistic future-worsening (e.g., climate projection) or a modelling error. change_cls = Stable: the intervention does not alter the risk profile enough to cross the threshold — either the intervention is too weak, the unit's baseline score is too far from the threshold zone, or both. Percent change vs absolute delta: use percent change for ranking (a +10 delta from a baseline of 20 = +50% is more dramatic than +10 from 80 = +12.5%); use absolute delta for spatial mapping (it preserves the interpretable 0–100 scale). Feed the output into Bivariate Choropleth Symbology with baseline and delta as axes to show "where was it high AND got worse".

Academic References

Swart, R.J., Raskin, P. & Robinson, J. (2004). "The problem of the future: sustainability science and scenario analysis." Global Environmental Change, 14(2), 137–146. DOI: 10.1016/j.gloenvcha.2003.10.002

Xiang, W.N. & Clarke, K.C. (2003). "The use of scenarios in land-use planning." Environment and Planning B, 30(6), 885–909. DOI: 10.1068/b2945

Smith, E.P. (2014). "BACI design." In A.H. El-Shaarawi & W.W. Piegorsch (eds.), Encyclopedia of Environmetrics, 2nd ed., Wiley. DOI: 10.1002/9780470057339.vab001.pub2

Openshaw, S. & Taylor, P.J. (1979). "A million or so correlation coefficients: three experiments on the modifiable areal unit problem." In N. Wrigley (ed.), Statistical Applications in the Spatial Sciences, Pion, pp. 127–144.

Rounsevell, M.D.A. & Metzger, M.J. (2010). "Developing qualitative scenario storylines for environmental change assessment." Wiley Interdisciplinary Reviews: Climate Change, 1(4), 606–619. DOI: 10.1002/wcc.63

Mahmoud, M., Liu, Y., Hartmann, H., Stewart, S., Wagener, T., Semmens, D., Stewart, R., Gupta, H., Dominguez, D., Dominguez, F. et al. (2009). "A formal framework for scenario development in support of environmental decision-making." Environmental Modelling & Software, 24(7), 798–808. DOI: 10.1016/j.envsoft.2008.11.010

van Vuuren, D.P., Edmonds, J., Kainuma, M., Riahi, K., Thomson, A., Hibbard, K., Hurtt, G.C., Kram, T., Krey, V., Lamarque, J.F. et al. (2011). "The representative concentration pathways: an overview." Climatic Change, 109, 5–31. DOI: 10.1007/s10584-011-0148-z

IPCC. (2021). Climate Change 2021: The Physical Science Basis. Cambridge University Press.

Scenario Planning Template

Processing ID: planx_urban_resilience:scenario_planning_template

1. Overview

Creates an editable baseline/proposed score worksheet from any scored layer. Computes a scenario score by applying an expected reduction percentage to the baseline, then adds intervention labels, scenario metadata, expected reduction, draft status, and notes fields. The output is a QGIS vector layer that can be edited directly in the attribute table or exported to CSV for spreadsheet-based planning. This is the suite's studio-drafting tool: planners sketch intervention scenarios directly in QGIS, edit the proposed scores per unit, and then compare baseline vs scenario via Scenario Comparison / Delta Map.

2. Theoretical Background

The template follows the participatory scenario planning methodology developed in land-use and climate adaptation studies (Patel et al., 2007; Kok et al., 2006). Rather than prescribing specific intervention magnitudes, the template empowers the planner to estimate expected reductions per planning unit based on local knowledge of costs, feasibility, and community context. The built-in intervention-type catalogue (green cooling, flood storage, shelter improvement, social support, air mitigation, drought retrofit, custom) maps to the six hazard families in the suite, ensuring each intervention is linked to a specific risk dimension. The expected reduction percentage is applied uniformly as a starting hypothesis; the planner then edits individual units to reflect heterogeneity. The engine is in processing/reporting/scenario_template.py.

3. Mathematical Formulation

where \(v_i\) is the existing baseline score value (if a base_score_field is provided; otherwise the default_base_score), and \(r\) is the expected reduction percentage (default 15%). The formula linearly scales: a 15% reduction on a baseline of 80 yields a scenario score of 68; on a baseline of 40 yields 34.

4. Input Data Requirements

5. Parameters

6. Output Description

8. Interpretation Guide

The template is a studio drafting tool, not an automated optimiser. The expected reduction percentage provides a uniform starting point. Planners should then: (1) filter by edit_status = 'draft' to see units needing review, (2) edit scen_score manually for units where the uniform reduction is unrealistic (e.g., units with existing green infrastructure may have a smaller marginal reduction), (3) update notes with site-specific justification, (4) change edit_status to "reviewed" when done. After editing, run the output through Scenario Comparison / Delta Map to visualise the spatial impact of the proposed intervention package. For multi-scenario studios, run the template multiple times with different intervention types and scenario names, then compare all proposed scenarios side-by-side.

Academic References

Patel, M., Kok, K. & Rothman, D.S. (2007). "Participatory scenario construction in land use analysis: an insight into the experiences created by an approach in southern India." Land Use Policy, 24(3), 546–561. DOI: 10.1016/j.landusepol.2006.01.002

Kok, K., Patel, M., Rothman, D.S. & Quaranta, G. (2006). "Multi-scale narratives from an IA perspective: Part II. Participatory local scenario development." Futures, 38(3), 285–311. DOI: 10.1016/j.futures.2005.07.006

Swart, R.J., Raskin, P. & Robinson, J. (2004). "The problem of the future: sustainability science and scenario analysis." Global Environmental Change, 14(2), 137–146. DOI: 10.1016/j.gloenvcha.2003.10.002

Boardman, A.E., Greenberg, D.H., Vining, A.R. & Weimer, D.L. (2018). Cost-Benefit Analysis: Concepts and Practice. 5th ed., Cambridge University Press. DOI: 10.1017/9781108235594

IPCC. (2014). Climate Change 2014: Impacts, Adaptation, and Vulnerability. Part A: Global and Sectoral Aspects. Cambridge University Press.

Xiang, W.N. & Clarke, K.C. (2003). "The use of scenarios in land-use planning." Environment and Planning B, 30(6), 885–909. DOI: 10.1068/b2945

NIST. (2015). Community Resilience Planning Guide for Buildings and Infrastructure Systems. NIST Special Publication 1190. DOI: 10.6028/NIST.SP.1190

UNISDR. (2015). Sendai Framework for Disaster Risk Reduction 2015–2030. United Nations, Geneva.

Resilience Score HTML Report

Processing ID: planx_urban_resilience:resilience_score_html_report

1. Overview

Generates a standalone HTML report from any scored polygon layer. Contents: score-distribution histogram (text-based), class breakdown table, top 10 units by score, and optional per-class statistics. The HTML file opens in any browser — no QGIS needed to view it.

Resilience Studio Brief (Markdown)

Processing ID: planx_urban_resilience:resilience_studio_brief

1. Overview

Generates a first-draft executive-summary Markdown document from a scored layer. Sections: executive summary, key metrics, class distribution, dominant drivers, limitations, and suggested next actions. The Markdown renders natively on GitHub/GitLab, in any Markdown editor, or can be pandoc-converted to PDF/DOCX.

Recommended Actions Report (Markdown)

Processing ID: planx_urban_resilience:recommended_actions_markdown

1. Overview

Turns a scored layer with optional class and dominant-hazard fields into a structured Markdown report: class distribution, top-N units table, and curated intervention checklists per hazard family (heat: cool roofs, green corridors, reflective pavements; flood: bioswales, detention basins, raised plinths; seismic: retrofit, soft-storey bracing; social: community centres, early-warning systems; air: green screens, traffic filtering; drought: drip irrigation, drought-tolerant species; emergency: satellite shelters, pre-positioned supplies). Each checklist item is a plain-language action with a rationale sentence.

Apply Resilience Symbology

Processing ID: planx_urban_resilience:apply_resilience_symbology

1. Overview

Applies pre-configured QGIS categorised or graduated renderers to the most common resilience output types: 0–100 risk scores (YlOrRd, 5-class), access classes (RdYlGn reversed), scenario change classes (diverging RdBu), and adaptation priority classes (YlOrRd). Optional QML export for reusable cartographic presets.

Bivariate Choropleth Symbology

Processing ID: planx_urban_resilience:bivariate_choropleth_symbology

1. Overview

Classifies polygon units into Low/Mid/High on two axes (risk and vulnerability) using tertile breaks, then applies a Stevens-style 3×3 bivariate palette via a QGIS categorised renderer. Adds bv_class, bv_risk_bin, and bv_vuln_bin fields so the symbology survives layer-style export. The 9-colour palette is the standard bivariate matrix: (R=risk axis, V=vulnerability axis; L/M/H = Low/Mid/High).

Resilience PDF Atlas

Processing ID: planx_urban_resilience:resilience_pdf_atlas

1. Overview

Generates a multi-page QgsLayout PDF atlas from a scored layer. Presets: A3 standard, A4 compact, A3 studio (300 dpi). Pages include a cover sheet, study-area overview map, and one map per risk class with automated legend, scale bar, and title block. The atlas is a QGIS print layout — open it in the Layout Manager to fine-tune before final export.

Multi-Hazard Correlation Matrix

Processing ID: planx_urban_resilience:correlation_matrix

1. Overview

Computes pairwise Pearson and Spearman correlations between N numeric score fields (2–12) on the same layer. Outputs a standalone HTML report with a colour-coded heatmap, top-10 correlations table, and strength interpretation, plus a long-format QGIS table sink for further analysis. Pure Python — no numpy/scipy dependency. Operational use: spot redundancy ("flood and seismic scores move together in this city — pick one for the composite") or surprise divergences ("heat is uncorrelated with everything — it captures a unique spatial dimension").

2. Theoretical Background

Correlation analysis between hazard scores serves as a diagnostic step before building a multi-hazard composite index. Highly correlated hazard fields (|r| > 0.80) contribute redundant spatial information: including both overweights that risk dimension and inflates the composite's sensitivity to shared measurement errors (OECD, 2008). The Pearson coefficient measures linear association; the Spearman rank coefficient measures monotonic association and is robust to outliers and non-normality (Spearman, 1904). Reporting both allows the analyst to distinguish between genuinely linear relationships and rank-consistent but non-linear ones (e.g., a threshold effect where flood and heat correlate only above a certain score). The engine implements both correlations in pure Python using the standard product-moment formulas, with ties in Spearman ranks handled by average-rank assignment. The engine is in processing/reporting/correlation_matrix.py.

3. Mathematical Formulation

where pairs with missing values in either field are excluded listwise from that pairwise correlation. The heatmap colour interpolation maps \(r \in [-1, 0]\) to blue tones and \(r \in [0, 1]\) to red tones, with grey for NULL pairs. Strength interpretation labels: |r| ≥ 0.7 = strong, ≥ 0.4 = moderate, ≥ 0.2 = weak, < 0.2 = negligible.

4. Input Data Requirements

5. Parameters

6. Output Description

8. Interpretation Guide

|r| > 0.80, both Pearson and Spearman: near-redundant — the two hazards carry essentially the same spatial information. Consider dropping one from the composite or using their mean. Pearson high, Spearman low: the relationship is driven by a few extreme values — check for outliers driving the linear correlation. r ≈ 0: the hazards are spatially independent — keeping both in the composite adds genuine information. r < -0.50: inverse relationship (e.g., flood-prone lowlands vs heat-prone ridgetops in the same city) — the composite must handle this divergence explicitly. n_pairs varying across the table: different fields have different missing-data patterns — fields with high missing rates (< 80% of total features) should be flagged as incomplete for composite construction.

Academic References

Spearman, C. (1904). "The proof and measurement of association between two things." The American Journal of Psychology, 15(1), 72–101. DOI: 10.2307/1412159

Pearson, K. (1895). "Note on regression and inheritance in the case of two parents." Proceedings of the Royal Society of London, 58, 240–242. DOI: 10.1098/rspl.1895.0041

OECD. (2008). Handbook on Constructing Composite Indicators: Methodology and User Guide. OECD Publishing. DOI: 10.1787/9789264043466-en

Nardo, M., Saisana, M., Saltelli, A., Tarantola, S., Hoffman, A. & Giovannini, E. (2005). Handbook on Constructing Composite Indicators. OECD Statistics Working Papers, 2005/03. DOI: 10.1787/533411815016

Kendall, M.G. (1938). "A new measure of rank correlation." Biometrika, 30(1–2), 81–93. DOI: 10.1093/biomet/30.1-2.81

Cutter, S.L., Boruff, B.J. & Shirley, W.L. (2003). "Social vulnerability to environmental hazards." Social Science Quarterly, 84(2), 242–261. DOI: 10.1111/1540-6237.8402002

IPCC. (2014). Climate Change 2014: Impacts, Adaptation, and Vulnerability. Part A. Cambridge University Press.

UNDRR. (2019). Global Assessment Report on Disaster Risk Reduction. United Nations Office for Disaster Risk Reduction, Geneva.

3D Risk Volume Export

Processing ID: planx_urban_resilience:risk_3d_volume_export

1. Overview

Converts a 0–100 scored polygon layer into a GeoJSON file in EPSG:4326 with extrusion_height (= score x scale_factor) and color_hex attributes per feature. Three colour ramp choices: Yellow-Red (sequential), Blue-Red (diverging), or Greys. An optional base-height field is additive — useful when polygons already carry building-height attributes and the risk extrusion should stack on top. The GeoJSON drops straight into PlanX 3D City Viewer, Three.js, deck.gl, or Cesium for interactive 3D exploration — the suite's most dramatic visual output, transforming a choropleth map into a city silhouette where the tallest, most saturated blocks are the worst hot spots.

2. Theoretical Background

3D visualisation of risk data builds on the cartographic extrusion metaphor formalised in geovisualisation research (MacEachren et al., 2004; Slocum et al., 2009). Extruding polygons by a risk score exploits the human visual system's sensitivity to height variation (Ware, 2012): equal risk differences are perceived as equal vertical displacement, making the 3D view a direct physicalisation of the risk surface. The CRS transformation to EPSG:4326 (WGS 84) ensures compatibility with all major web-mapping libraries (deck.gl, Cesium, Mapbox) which expect geographic coordinates. The colour-ramp encoding is redundant with height — providing two visual channels for the same variable — which improves interpretability for viewers who may not perceive height accurately (due to perspective, occlusion, or colour vision deficiency). The engine is in processing/reporting/risk_3d_export.py.

3. Mathematical Formulation

where \(s_i\) is the score (0–100), \(h_{\max}\) is the maximum extrusion height (default 100 m), \(b_i\) is the optional base height, and the colour functions are piecewise-linear interpolations through anchor colours. Polygons are reprojected from the source CRS to EPSG:4326 via QGIS's coordinate transform.

5. Parameters

6. Output Description

8. Interpretation Guide

The 3D view is most effective with max_height = 100 m and a study area of 2–5 km extent. For presentation: use Yellow-Red for single-hazard risk; use Blue-Red (diverging) for delta maps (blue = improved, red = worsened). The 3D view is a complement to, not a replacement for, the 2D choropleth — use both in a report side by side. The GeoJSON metadata block records the source score field, maximum height, colour ramp, and feature count for provenance tracking.

Academic References

MacEachren, A.M., Gahegan, M., Pike, W., Brewer, I., Cai, G., Lengerich, E. & Hardisty, F. (2004). "Geovisualization for knowledge construction and decision support." IEEE Computer Graphics and Applications, 24(1), 13–17. DOI: 10.1109/MCG.2004.1255801

Slocum, T.A., McMaster, R.B., Kessler, F.C. & Howard, H.H. (2009). Thematic Cartography and Geovisualization. 3rd ed., Pearson.

Ware, C. (2012). Information Visualization: Perception for Design. 3rd ed., Morgan Kaufmann. DOI: 10.1016/C2009-0-62432-6

Tufte, E.R. (1990). Envisioning Information. Graphics Press.

Brewer, C.A. (2005). Designing Better Maps: A Guide for GIS Users. ESRI Press.

Bertin, J. (1983). Semiology of Graphics: Diagrams, Networks, Maps. University of Wisconsin Press.

NIST. (2015). Community Resilience Planning Guide for Buildings and Infrastructure Systems. NIST Special Publication 1190. DOI: 10.6028/NIST.SP.1190

Dollner, J. & Walther, M. (2003). "Real-time expressive rendering of city models." Proceedings of the 7th International Conference on Information Visualization (IV'03), 245–250. DOI: 10.1109/IV.2003.1217985

Appendix A: Data Sources

The Urban Resilience suite is data-agnostic — every algorithm accepts generic vector and raster inputs. Below are the input types each module expects and common open-data sources for each.

Appendix B: Symbolization

The suite's default symbology recommendations follow a consistent visual grammar:

Appendix C: Glossary

Appendix D: Complete Bibliography

Anselin, L. (1995). "Local indicators of spatial association — LISA." Geographical Analysis, 27(2), 93–115.

Benjamini, Y. & Hochberg, Y. (1995). "Controlling the false discovery rate." Journal of the Royal Statistical Society: Series B, 57(1), 289–300.

Beven, K.J. & Kirkby, M.J. (1979). "A physically based, variable contributing area model of basin hydrology." Hydrological Sciences Journal, 24(1), 43–69.

Boardman, A.E. et al. (2018). Cost-Benefit Analysis: Concepts and Practice. 5th ed., Cambridge University Press.

Bowler, D.E. et al. (2010). "Urban greening to cool towns and cities: a systematic review." Landscape and Urban Planning, 97(3), 147–155.

Brandes, U. (2001). "A faster algorithm for betweenness centrality." Journal of Mathematical Sociology, 25(2), 163–177.

Briggs, D.J. et al. (1997). "Mapping urban air pollution using GIS: a regression-based approach." International Journal of Geographical Information Science, 11(7), 699–718.

Cardinal, J. et al. (2011). "A unified framework for rich routing problems." Computers & Operations Research, 38(5), 831–843.

Cervero, R. & Kockelman, K. (1997). "Travel demand and the 3Ds: density, diversity, and design." Transportation Research Part D, 2(3), 199–219.

Church, R.L. & ReVelle, C.S. (1974). "The maximal covering location problem." Papers of the Regional Science Association, 32, 101–118.

Cornuéjols, G., Fisher, M.L. & Nemhauser, G.L. (1977). "Location of bank accounts to optimize float." Management Science, 23(8), 789–810.

Cutter, S.L., Ash, K.D. & Emrich, C.T. (2014). "The geographies of community disaster resilience." Global Environmental Change, 29, 65–77.

Cutter, S.L., Boruff, B.J. & Shirley, W.L. (2003). "Social vulnerability to environmental hazards." Social Science Quarterly, 84(2), 242–261. DOI: 10.1111/1540-6237.8402002

Cutter, S.L. & Finch, C. (2008). "Temporal and spatial changes in social vulnerability to natural hazards." Proceedings of the National Academy of Sciences, 105(7), 2301–2306.

Daskin, M.S. (2013). Network and Discrete Location: Models, Algorithms, and Applications. 2nd ed., Wiley.

Dijkstra, E.W. (1959). "A note on two problems in connexion with graphs." Numerische Mathematik, 1, 269–271.

European Commission. (2014). Guide to Cost-Benefit Analysis of Investment Projects. Directorate-General for Regional and Urban Policy.

FEMA. (2003). HAZUS-MH MR4 Technical Manual. Federal Emergency Management Agency, Washington, DC.

FEMA. (2018). Seismic Performance Assessment of Buildings, Volume 1 — Methodology (FEMA P-58-1), Second Edition. Washington, DC.

Fisher, P.F. & Tate, N.J. (2006). "Causes and consequences of error in digital elevation models." Progress in Physical Geography, 30(4), 467–489.

Gao, J., Barzel, B. & Barabási, A.L. (2016). "Universal resilience patterns in complex networks." Nature, 530, 307–312.

Getis, A. & Ord, J.K. (1992). "The analysis of spatial association by use of distance statistics." Geographical Analysis, 24(3), 189–206.

Girvan, M. & Newman, M.E.J. (2002). "Community structure in social and biological networks." Proceedings of the National Academy of Sciences, 99(12), 7821–7826.

Goretti, A. & Sarli, V. (2006). "Road network and damaged buildings in urban areas: short and long-term interaction." Bulletin of Earthquake Engineering, 4(2), 159–175. DOI: 10.1007/s10518-006-9004-3

IPCC. (2014). Climate Change 2014: Impacts, Adaptation, and Vulnerability. Part A: Global and Sectoral Aspects. Cambridge University Press.

IPCC. (2021). Climate Change 2021: The Physical Science Basis. Contribution of Working Group I to the Sixth Assessment Report. Cambridge University Press.

Luo, W. & Wang, F. (2003). "Measures of spatial accessibility to health care in a GIS environment." Environment and Planning B, 30(6), 865–884.

MacArthur, R.H. & Wilson, E.O. (1967). The Theory of Island Biogeography. Princeton University Press.

McDonald, R.I. et al. (2008). "The implications of current and future urbanization for global protected areas and biodiversity conservation." Biological Conservation, 141(6), 1695–1703.

McKay, M.D., Beckman, R.J. & Conover, W.J. (1979). "A comparison of three methods for selecting values of input variables." Technometrics, 21(2), 239–245.

NIST. (2015). Community Resilience Planning Guide for Buildings and Infrastructure Systems. NIST Special Publication 1190.

Nowak, D.J., Crane, D.E. & Stevens, J.C. (2006). "Air pollution removal by urban trees and shrubs in the United States." Urban Forestry & Urban Greening, 4(3–4), 115–123.

Nowak, D.J. et al. (2008). "A ground-based method of assessing urban forest structure and ecosystem services." Arboriculture & Urban Forestry, 34(6), 347–358.

Oke, T.R. (1982). "The energetic basis of the urban heat island." Quarterly Journal of the Royal Meteorological Society, 108(455), 1–24.

Ord, J.K. & Getis, A. (1995). "Local spatial autocorrelation statistics: distributional issues and an application." Geographical Analysis, 27(4), 286–306.

Saltelli, A. et al. (2004). Sensitivity Analysis in Practice. Wiley.

Shepard, D. (1968). "A two-dimensional interpolation function for irregularly-spaced data." Proceedings of the 1968 ACM National Conference, 517–524.

Shi, L. et al. (2016). "Roadmap towards justice in urban climate adaptation research." Nature Climate Change, 6(2), 131–137. DOI: 10.1038/nclimate2841

Stewart, I.D. & Oke, T.R. (2012). "Local Climate Zones for urban temperature studies." Bulletin of the American Meteorological Society, 93(12), 1879–1900. DOI: 10.1175/BAMS-D-11-00019.1

Tehrany, M.S., Pradhan, B. & Jebur, M.N. (2014). "Flood susceptibility mapping using a novel ensemble weights-of-evidence and support vector machine models in GIS." Journal of Hydrology, 512, 332–343.

UNDRR. (2019). Global Assessment Report on Disaster Risk Reduction. United Nations Office for Disaster Risk Reduction, Geneva.

Yperman, I. (2007). The Link Transmission Model for Dynamic Network Loading. PhD thesis, KU Leuven.

PlanX Urban Resilience — Academic Reference Manual · v1.26.2 · 43 Algorithms
Yusuf Eminoğlu · August 2026 · GitHub