Skip to content

LossEstimation#

LossEstimation is the end-to-end orchestrator of the chain. Construct it with the damage library, the exposure export and, optionally, a zone layer; with the automatic flags on, every result is an attribute after construction. estimate_all_losses() recomputes every result from the current inputs and returns them without changing the object.

Inputs#

All fields of the chain, in particular:

Field Notes
prob_ds_file_path or damage_provider The damage library.
hurricane_prob_path or hurricane_probabilities Annual event probabilities.
inventory_csv_path, wind_ids_path, flood_ids_path The exposure export, or use load_from_exposure(exposure).
zones_path, zone_id_col, aggregation_col Zone aggregation.
index_mode, combine_mode, value_basis Numerics (floor, additive, structure_value by default).
output_dir Defaults to <Config.OUTPUTS_PATH>/loss_estimation.

Outputs And Returns#

estimate_all_losses() returns a dictionary with:

Key Value
wind_lookup, flood_lookup The marginal tables (existing ones, or built from the library).
building_eal Expected annual loss per building.
zone_eal EAL sums per aggregation unit.
event_losses Regional loss per event with its probability.

save_all_outputs(output_dir=None) writes L_mcw_wd.npy, L_mcf_fld.npy, STARR_lookup_metadata.txt, building_eal.csv, zone_eal.csv and event_losses.csv and returns their paths.

Configuration Behavior#

Identical to the chain: loading follows Config.AUTO_LOAD_DATASETS, results follow Config.AUTO_EXECUTE_METHODS, and update_outputs() reloads and reruns everything.

Minimal Examples#

From a saved exposure export:

from cheersafe.loss_estimation import LossEstimation

estimator = LossEstimation(
    prob_ds_file_path="Outputs/ProbDS_wfd_dictMaxIter3000_aggregated.pkl",
    inventory_csv_path="Outputs/exposure/Inventory.csv",
    wind_ids_path="Outputs/exposure/Wind_Tr.npy",
    flood_ids_path="Outputs/exposure/Flood_Tr.npy",
)
results = estimator.estimate_all_losses()
paths = estimator.save_all_outputs()

From an in-memory Exposure object with a custom event set:

import numpy as np

from cheersafe.config import Config
from cheersafe.exposure import Exposure
from cheersafe.loss_estimation import LossEstimation

exposure = Exposure(zones_path="Inputs/zones.gpkg", seed=42)

Config.AUTO_LOAD_DATASETS = False
Config.AUTO_EXECUTE_METHODS = False
estimator = LossEstimation(
    prob_ds_file_path="Inputs/damage_library.pkl",
    hurricane_probabilities=np.array([0.1, 0.2, 0.02]),   # one entry per hazard event
    zones_path="Inputs/zones.gpkg",
    aggregation_col="i_lh503",
)
estimator.load_damage_library()
estimator.load_hurricane_probabilities()
estimator.load_zones()
estimator.load_from_exposure(exposure)
results = estimator.estimate_all_losses()