Skip to content

LookupTableBuilder#

LookupTableBuilder turns the damage library into the two expected loss-ratio tables that STARR and the building loss estimator use, and optionally into the full wind-flood surface. Use it when you need L_mcw_wd / L_mcf_fld as files, or when you want to inspect expected loss ratios by archetype and configuration.

Inputs#

Inherited from BaseLossEstimation: the damage library (through the provider), DamageState.json, WindSpeed.json, FloodDepth.json and the event probabilities.

Field Default Notes
n_building_types 8 Size of the m axis of the tables.
n_component_configurations 192 Size of the c axis.
lookup_dtype float32 Storage dtype; float32 matches the frozen source tables.
normalization_tolerance 1e-3 Probability rows farther than this from summing to one are counted and reported once.

Definition#

With P[m, c] the (n_wind, n_flood, n_states) tensor of the library and DR the damage-state ratios,

  • L_w[m-1, c-1, w] = sum_d P[m, c][w, 0, d] DR_d (wind only; flood held at ID 1, the zero-hazard bin),
  • L_f[m-1, c-1, f] = sum_d P[m, c][0, f, d] DR_d (flood only; wind held at ID 1),
  • E[m-1, c-1, w, f] = sum_d P[m, c][w, f, d] DR_d (the joint surface).

The tables have shapes (8, 192, 25) and (8, 192, 136); the surface has shape (8, 192, 25, 136) (about 21 MB for the full library). Index meaning: L_mcw_wd[m-1, c-1, w-1] is the wind-only expected loss ratio for archetype m, configuration c and wind ID w. Pairs (m, c) absent from the library are NaN, not zero, so a partial library surfaces in the results instead of silently producing zero loss. Rows are summed on a contiguous float64 copy in the order of the verified scripts, and the resulting tables are byte-identical to the frozen Eastern North Carolina export.

Outputs And Returns#

Method Returns
calculate_marginal_lookups(prob_damage_states, damage_ratios, n_building_types, n_component_configurations) (wind_lookup, flood_lookup); one warning reports missing pairs and one reports unnormalized rows.
calculate_expected_ratio_surface(prob_damage_states, damage_ratios, n_building_types, n_component_configurations) The joint surface.
save_lookup_tables(output_dir=None) Writes L_mcw_wd.npy, L_mcf_fld.npy and STARR_lookup_metadata.txt; returns their paths.
load_lookup_tables(wind_path, flood_path) Sets wind_lookup and flood_lookup from saved files, for users with frozen tables and no library.

Configuration Behavior#

Loading follows Config.AUTO_LOAD_DATASETS. With Config.AUTO_EXECUTE_METHODS=True, __post_init__ assigns wind_lookup and flood_lookup when the library is non-empty; an empty library logs a warning and leaves the tables unset so load_lookup_tables can supply them.

Minimal Examples#

Automatic build and export:

from cheersafe.loss_estimation import LookupTableBuilder

builder = LookupTableBuilder(prob_ds_file_path="Outputs/ProbDS_wfd_dictMaxIter3000_aggregated.pkl")
paths = builder.save_lookup_tables("Outputs/loss_estimation")

Manual build and joint surface:

from cheersafe.config import Config
from cheersafe.loss_estimation import LookupTableBuilder

Config.AUTO_LOAD_DATASETS = False
Config.AUTO_EXECUTE_METHODS = False

builder = LookupTableBuilder(prob_ds_file_path="Outputs/ProbDS_wfd_dictMaxIter3000_aggregated.pkl")
builder.load_damage_library()
builder.load_hurricane_probabilities()
ratios = builder.damage_states[:, 1]
builder.wind_lookup, builder.flood_lookup = builder.calculate_marginal_lookups(
    builder.prob_damage_states, ratios, 8, 192
)
surface = builder.calculate_expected_ratio_surface(builder.prob_damage_states, ratios, 8, 192)