Skip to content

Exposure#

Exposure completes the chain: it assigns a zone id to every clipped building and assembles the STARR-compatible export (Inventory.csv, Wind_Tr.npy, Flood_Tr.npy). Construct it when you want the whole workflow in one object, either to save the export or to hand it to LossEstimation in memory.

Inputs#

Inherited from HazardMapper, plus:

Field Default Notes
zone_id_col i_lh740 Zone-id column of the zone layer. None skips zone assignment and omits the column from the export.
drop_unassigned_zones False True removes buildings outside every zone from the export, reproducing the frozen source export's valid-zone filter.

Zone layer#

The zone layer is a polygon layer covering the whole zone system in one file (any CRS; it is reprojected on the fly). The Eastern North Carolina layer, leaphi_zones_20230920, carries the LEAPHI data dictionary:

Column Meaning
COUNTYFP00 Three-digit county FIPS code.
zone Coastal band: 1 (0-1 mile), 2 (1-2 miles), 3 (more than 2 miles from the coast).
i_lh503 Zone id in the 503-zone system.
i_lh1509 Zone id in the 1509-zone system.
i_lh708 Zone id in the 708-zone system.
i_lh740 Zone id in the 740-zone system.

calculate_zone_assignment joins building centroids to the polygons that contain them (within), keeps the first match when a centroid lies on a shared boundary and assigns -1 to buildings outside every zone.

Outputs And Returns#

Method Returns
calculate_zone_assignment(inventory, zones, zone_id_col) int64 zone id per building, -1 when unassigned or when zones is None.
calculate_starr_inventory(inventory, zone_ids) The STARR table described below.
calculate_starr_export() (starr_inventory, wind_ids, flood_ids, event_names) with drop_unassigned_zones applied consistently to the table and both arrays. save_starr_inputs and BuildingLossEstimator.load_from_exposure both consume it.
save_starr_inputs(output_dir=None) Writes the files below and returns their paths.

STARR inventory table#

Column Meaning
building_ID 1-based position in the clipped inventory (row b of the arrays is building_ID = b + 1).
t Always 0 (STARR time step).
YearBuilt, YearBuiltGroup Year built and its period label before1968, 1968to1997 or 1997to2010.
<zone_id_col> Zone id, -1 when unassigned (omitted when zone_id_col is None).
M, C Archetype and initial resistance configuration.
RC, RF, RTW, O, W, F Component states of C.
structure_value, contents_value, home_value Values; home_value = structure_value + contents_value.
fd_id_nsi The schema key column, when present.
is_vacant, H_TEN_syn, AGEP_syn, H_HINCP_syn Passthrough columns, when present.
x, y Centroid in the hazard CRS.
lon, lat Centroid in EPSG:4326.
building_key Stable key carried from the source inventory (last column, so positional readers of the legacy layout are unaffected).

Files written by save_starr_inputs#

File Contents
Inventory.csv The STARR inventory table, one row per exported building.
Wind_Tr.npy, Flood_Tr.npy Continuous hazard IDs, shape (n_buildings, n_events), float32; rows align with Inventory.csv.
Hurricane_name.npy Event names aligned with the array columns.
HazardInput_metadata.txt Run settings and array shapes.
archetype_inventory.parquet, clipped_inventory.parquet The intermediate GeoParquet layers.

STARR looks up wind-only and flood-only loss ratios during its own simulation with the resistance configuration current at that time, which changes when retrofits are applied. The export therefore holds hazard IDs and the initial C, not loss ratios; the lookup tables come from LookupTableBuilder.

Configuration Behavior#

Loading follows Config.AUTO_LOAD_DATASETS. With Config.AUTO_EXECUTE_METHODS=True, __post_init__ runs the whole chain and assigns zone_ids and starr_inventory; nothing is written until save_starr_inputs is called. update_outputs() reloads and reruns.

Minimal Examples#

Automatic execution and export:

from cheersafe.exposure import Exposure

exposure = Exposure(zones_path="Inputs/zones.gpkg", zone_id_col="i_lh740", seed=42)
paths = exposure.save_starr_inputs("Outputs/exposure")

In-memory hand-off to loss estimation (see the loss-estimation manual):

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

exposure = Exposure(zones_path="Inputs/zones.gpkg", seed=42)
estimator = LossEstimation(prob_ds_file_path="Inputs/damage_library.pkl", zones_path="Inputs/zones.gpkg")
estimator.load_from_exposure(exposure)
results = estimator.estimate_all_losses()