Skip to content

RegionalLossEstimator#

RegionalLossEstimator sums the building EAL within zones and totals the loss of every event over the region. Use it for zone maps and for region-level event losses.

Inputs#

Inherited from BuildingLossEstimator: the building table, the hazard-ID arrays, the tables and the probabilities.

Field Default Notes
zone_id_col i_lh740 Zone column of the inventory (inherited).
aggregation_col None Coarser zone system to aggregate to, e.g. i_lh503; None aggregates by zone_id_col itself.
zones_path None Zone layer holding both id columns; required only for a remap.

Zone Remapping#

calculate_zone_lookup(zones, fine_col, coarse_col) reads both id columns of the zone layer and maps every fine zone onto its coarse zone. It raises ValueError when a fine zone spans several coarse zones, so only nested systems (such as LEAPHI i_lh740 inside i_lh503) are accepted. calculate_aggregation_key applies that mapping to the inventory's zone column; unassigned buildings (-1) stay unassigned and appear as their own row in the results.

The published Eastern North Carolina EAL maps aggregate to the 503-zone LEAPHI system even though the paper caption reads "census tract"; use aggregation_col="i_lh503" to reproduce them.

Outputs And Returns#

Method Returns
calculate_zone_lookup(zones, fine_col, coarse_col) dict fine id to coarse id.
calculate_aggregation_key(building_table, zones, zone_id_col, aggregation_col) int64 unit per building, -1 when unassigned.
calculate_zone_eal(building_eal, aggregation_key) Table indexed by unit (ascending, -1 last) with eal_wind, eal_flood, eal_combined, n_buildings and value.
calculate_event_losses(building_table, wind_ids, flood_ids, probabilities, surface=None) Table indexed by event with probability, loss_wind, loss_flood, loss_combined (sums of loss_ratio * value over all buildings).
save_zone_eal(path=None), save_event_losses(path=None) Write zone_eal.csv and event_losses.csv.

The probability-weighted sum of the event losses equals the sum of the building EAL, which is a useful consistency check.

Configuration Behavior#

Loading follows Config.AUTO_LOAD_DATASETS (the zone layer is loaded after the base inputs). With Config.AUTO_EXECUTE_METHODS=True, __post_init__ assigns aggregation_key, zone_eal and event_losses once building_eal exists.

Minimal Examples#

Automatic aggregation to the 503-zone system:

from cheersafe.loss_estimation import RegionalLossEstimator

regional = RegionalLossEstimator(
    prob_ds_file_path="Outputs/ProbDS_wfd_dictMaxIter3000_aggregated.pkl",
    inventory_csv_path="Outputs/exposure/Inventory.csv",
    zones_path="Inputs/leaphi_zones_20230920.shp",
    zone_id_col="i_lh740",
    aggregation_col="i_lh503",
)
print(regional.zone_eal.sort_values("eal_combined", ascending=False).head())

Manual aggregation by the inventory's own zone column:

from cheersafe.config import Config
from cheersafe.loss_estimation import RegionalLossEstimator

Config.AUTO_LOAD_DATASETS = False
Config.AUTO_EXECUTE_METHODS = False

regional = RegionalLossEstimator(
    prob_ds_file_path="Outputs/ProbDS_wfd_dictMaxIter3000_aggregated.pkl",
    inventory_csv_path="Outputs/exposure/Inventory.csv",
)
regional.load_damage_library()
regional.load_hurricane_probabilities()
regional.load_exposure_inputs()
regional.wind_lookup, regional.flood_lookup = regional.calculate_marginal_lookups(
    regional.prob_damage_states, regional.damage_states[:, 1], 8, 192
)
probabilities = regional.hurricane_prob[:, 1]
regional.building_eal = regional.calculate_building_eal(
    regional.building_table, regional.wind_ids, regional.flood_ids, probabilities
)
regional.aggregation_key = regional.calculate_aggregation_key(regional.building_table, None, "i_lh740", None)
regional.zone_eal = regional.calculate_zone_eal(regional.building_eal, regional.aggregation_key)
regional.event_losses = regional.calculate_event_losses(
    regional.building_table, regional.wind_ids, regional.flood_ids, probabilities
)