Skip to content

HazardMapper#

HazardMapper assigns each event's wind speed and flood depth from the hazard control points to the buildings, converts them to mph and inches and interpolates them onto the package's discrete hazard IDs. The result is one continuous, 1-based wind ID and flood ID per building and event (Wind_Tr, Flood_Tr), which the loss module later rounds onto lookup-table bins.

Inputs#

Inherited from ArchetypeAssigner: the archetype inventory, the hazard arrays and the wind and flood tables.

Field Default Notes
average_mode Nearest Nearest takes the closest control point (the verified run). Inverse_d4 averages the idw_neighbors closest points with weights distance ** -idw_power.
idw_neighbors 4 Neighbours used by Inverse_d4.
idw_power 4.0 Exponent of the inverse-distance weights.
wind_to_mph 2.23694 Factor from the hazard wind unit (m/s) to mph.
flood_to_inches 39.3701 Factor from the hazard flood unit (m) to inches.
clip_to_hazard_bounds True Drop buildings whose centroid lies outside the control-point bounding box.
hazard_id_dtype float32 Storage dtype of the hazard-ID arrays.

Control-point layers#

Each event layer is a point layer with columns such as cell_ID, x, y, Wind, Flood, geometry; Wind is in m/s and Flood in metres. Missing values and the nodata_value (-9999) are set to zero before averaging, as in the verified scripts. The neighbour match is built once from the control-point coordinates and reused for every event, which is why BaseExposure.load_hazard_events requires identical geometry across files.

Mapping modes#

For building j with the four nearest control points at distances d_i and intensities F_i, Inverse_d4 computes

F_j = sum_i F_i d_i^-4 / sum_i d_i^-4,

with zero distances clamped to a nanometre. Nearest takes F_j of the closest point. The inverse-distance mode replicates the scripts but was not used for the published figures.

Unit conversion and hazard IDs#

The intensity is multiplied by wind_to_mph or flood_to_inches and interpolated linearly onto the ID column of WindSpeed.json or FloodDepth.json using its physical-unit column as knots (np.interp). Values beyond the knots clamp to the first or last ID; missing values become ID 1.

Wind speed (mph) Wind ID
0 1
50, 55, ..., 140 2, 3, ..., 20
155, 170, 185, 200, 215 21, 22, 23, 24, 25
Flood depth (inches) Flood ID
0, 1, ..., 120 1, 2, ..., 121
130, 140, ..., 270 122, 123, ..., 136

For example 52.5 mph maps to ID 2.5 and 121 inches to ID 121.1.

Outputs And Returns#

Method Returns
calculate_clipped_inventory(inventory) Inventory reprojected to the hazard CRS, clipped to the control-point bounds, re-indexed from zero, with a 1-based building_ID column.
calculate_neighbor_match(building_xy, hazard_xy, k) Neighbour indices and distances, each (n_buildings, k).
calculate_event_intensity(values, neighbor_index, neighbor_distance, mode=None, power=None) One intensity per building for one event.
calculate_hazard_id(values, table, unit_factor) Continuous 1-based IDs in hazard_id_dtype.
calculate_hazard_ids(neighbor_index, neighbor_distance, hazard_wind, hazard_flood) wind_ids and flood_ids, each (n_buildings, n_events); column j is event j of event_names.
save_hazard_ids(output_dir=None) Writes Wind_Tr.npy, Flood_Tr.npy and Hurricane_name.npy (unicode, loadable without allow_pickle) and returns their paths.

Grid helpers#

Three module-level functions in cheersafe.exposure.hazard_mapping support the Eastern North Carolina figure notebook:

  • calculate_cell_index(x, y, origin_x, origin_y, cell_size, method) bins coordinates onto the 1 km control-point grid (nearest mirrors nearest-neighbour mapping; corner floors).
  • calculate_grid_mask(x, y, ...) returns the occupancy mask of the control points and the raster extent for imshow, raising if a point is off the grid.
  • calculate_probability_weighted_intensity(values, probabilities, conditional_on_positive=False) computes sum_h p_h V_h / sum_h p_h per point, or, conditional on inundation, sum over events with V_h > 0 in both numerator and denominator with NaN where a point is never affected.

Configuration Behavior#

Loading follows Config.AUTO_LOAD_DATASETS. With Config.AUTO_EXECUTE_METHODS=True, __post_init__ assigns clipped_inventory, neighbor_index, neighbor_distance, wind_ids and flood_ids after the archetype step.

Minimal Examples#

Automatic execution:

from cheersafe.exposure import HazardMapper

mapper = HazardMapper(average_mode="Nearest", seed=42)
print(mapper.wind_ids.shape, mapper.wind_ids.min(), mapper.wind_ids.max())

Manual control comparing the two modes on one event:

import numpy as np

from cheersafe.config import Config
from cheersafe.exposure import HazardMapper

Config.AUTO_LOAD_DATASETS = False
Config.AUTO_EXECUTE_METHODS = False

mapper = HazardMapper(seed=42)
mapper.load_hazard_tables()
mapper.load_component_combinations()
mapper.load_inventory()
mapper.load_hazard_events()
mapper.archetype_inventory = mapper.calculate_archetypes(mapper.inventory)
mapper.clipped_inventory = mapper.calculate_clipped_inventory(mapper.archetype_inventory)
centroids = mapper.clipped_inventory.geometry.centroid
building_xy = np.column_stack([centroids.x, centroids.y])

index, distance = mapper.calculate_neighbor_match(building_xy, mapper.hazard_points_xy, k=4)
nearest = mapper.calculate_event_intensity(mapper.hazard_wind[0], index, distance, mode="Nearest")
weighted = mapper.calculate_event_intensity(mapper.hazard_wind[0], index, distance, mode="Inverse_d4")
wind_ids = mapper.calculate_hazard_id(nearest, mapper.wind_speeds, mapper.wind_to_mph)