Skip to content

BaseExposure#

BaseExposure loads every input of the exposure workflow: the building inventory layer, the per-event hazard control-point layers, an optional zone layer and the package's discrete hazard and component tables. InventorySchema tells it which inventory columns and category values map onto the archetype attributes. Use BaseExposure directly only to inspect inputs; the calculations live in the subclasses.

Inputs#

Path fields left as None resolve under Config.INPUTS_PATH at load time.

Field Default Notes
inventory_path Inputs/Inventory.parquet GeoParquet, shapefile or GeoPackage with a CRS. Point or polygon geometry; centroids are used.
hazard_dir Inputs/Hazards One control-point layer per event; every file matching hazard_file_pattern.
hazard_file_pattern *.parquet Glob applied inside hazard_dir.
wind_col, flood_col Wind, Flood Hazard columns selected by name: wind in m/s, flood depth in m.
nodata_value -9999.0 Treated as zero hazard during mapping.
zones_path None Optional polygon layer; None skips zone assignment.
wind_speed_path Inputs/WindSpeed.json [25, 3]: id, mph, m/s.
flood_depth_path Inputs/FloodDepth.json [136, 3]: id, inches, m.
component_combination_path Inputs/ComponentCombination_All.json [192, 6]: component states per configuration C.
output_dir Outputs/exposure Resolved under Config.OUTPUTS_PATH.
schema InventorySchema() Column and category mapping described below.

Inventory column map#

InventorySchema lets any inventory be used without renaming columns. Every category value that is not listed maps to a missing value.

Role Column field (default) Value fields (default) Effect
Building material bldgtype_col (bldgtype) wood_frame_values (("W",)) Sets is_wood_frame; rows are dropped only when ArchetypeAssigner.drop_unmatched_occupancy is True.
Roof shape roof_col (roof_shape_1) gable_values (Cross Gable, Complex Gable, Gable), hip_values (Hip, Cross Hip) Required; unmapped rows are dropped.
Stories story_col (Story_AI) one_story_values ((1,)), two_story_values ((2,)) Required.
Garage garage_col (Garage) no_garage_values ((0,)), garage_values ((1,)) Required.
Occupancy occupancy_col (PRIM_OCC) single_family_values (("Single Family Dwelling",)) Sets is_single_family; same filter rule as building material.
Year built year_col (med_yr_blt) numeric Required.
Coast distance coast_distance_col (Coast_D (miles)) coast_distance_to_miles (1.0) multiplier Required; converted to miles.
Structure value structure_value_col (val_struct) numeric Required.
Contents value contents_value_col (val_cont) numeric Required.
Building key building_key_col (fd_id_nsi) Used as building_key when present; otherwise the row position is used.
Passthrough passthrough_cols (is_vacant, H_TEN_syn, AGEP_syn, H_HINCP_syn) Copied into the export when present.

The defaults are the arguments of the verified Eastern North Carolina call. The earlier Inventory-Loss Link documentation listed six required attributes and omitted roof shape; roof shape is required here because it defines the archetype.

Hazard control-point layers#

Each event file is a point layer with the same control points in the same order. load_hazard_events sorts the files by the integer embedded in their names (h1, h2, ..., h97, falling back to lexical order with a warning), stacks wind_col and flood_col into (n_events, n_points) arrays in their raw units and raises ValueError when a file's control points differ from the first one. The bounding box of the control points becomes hazard_bounds.

Outputs And Returns#

The loaders assign attributes; they return None.

Method Sets
load_hazard_tables() wind_speeds, flood_depths
load_component_combinations() component_combinations (int64, shape (192, 6))
load_inventory() inventory with a new building_key column (before any filtering)
load_hazard_events() hazard_files, event_names, hazard_points_xy, hazard_crs, hazard_bounds, hazard_wind, hazard_flood
load_zones() zones (or None)

Configuration Behavior#

With Config.AUTO_LOAD_DATASETS=True, __post_init__ runs the five loaders and sets datasets_loaded. update_outputs() clears the flag and reloads. BaseExposure has no calculation step, so Config.AUTO_EXECUTE_METHODS has no effect on it.

Minimal Examples#

Automatic loading:

from cheersafe.exposure import BaseExposure

base = BaseExposure(zones_path="Inputs/zones.gpkg")
print(base.event_names, base.hazard_wind.shape)

Manual loading with a custom schema:

from cheersafe.config import Config
from cheersafe.exposure import BaseExposure, InventorySchema

Config.AUTO_LOAD_DATASETS = False
schema = InventorySchema(
    roof_col="roof_shape",
    gable_values=("gable",),
    hip_values=("hip",),
    coast_distance_col="coast_km",
    coast_distance_to_miles=0.621371,
)
base = BaseExposure(inventory_path="my_inventory.gpkg", hazard_dir="my_hazards", schema=schema)
base.load_hazard_tables()
base.load_component_combinations()
base.load_inventory()
base.load_hazard_events()