Skip to content

ArchetypeAssigner#

ArchetypeAssigner maps the normalized inventory attributes onto the structural archetype M (1-8) and draws a resistance configuration C (1-192) for every building. M is deterministic; C is sampled from the construction-period and coast-distance rules of Peng (2013), so it is seeded through cheersafe.tools.Sampling.

Inputs#

Inherited from BaseExposure: the inventory, the schema and ComponentCombination_All.json.

Field Default Notes
coast_threshold_miles 2.0 Buildings closer than this use the near-coast rule table.
year_breaks (1968, 1997) Year built < 1968 is period 0, < 1997 period 1, otherwise period 2.
drop_unmatched_occupancy False True drops buildings that are not wood-frame single-family residences. The default keeps them (flagged), as the verified run did.
seed None Seed of the configuration draw; None uses Config.RANDOM_SEED.

Archetype M#

calculate_archetype_m follows Table 3.1 of Peng (2013):

M Stories Roof Garage
1 1 hip yes
2 1 gable yes
3 1 hip no
4 1 gable no
5 2 or more hip yes
6 2 or more gable yes
7 2 or more hip no
8 2 or more gable no

Odd archetypes are hip roofs, even archetypes gable roofs, matching the convention of the damage-probability modules.

Resistance Configuration C#

C indexes the rows of ComponentCombination_All.json. Each row holds the state of six components:

Column Component States
RC Roof covering 2
RF Roof sheathing 2
RTW Roof-to-wall connection 2
O Openings 3
W Walls 2
F Flood mitigation 4

The 192 rows enumerate F slowest and W fastest, so C = 1 is every component in state 1, C = 3 differs only in openings state 2, C = 25 only in roof covering state 2, and the published modal legend [1, 3, 5, 7, 25, 49, 97, 145, 169, 175] decomposes as 3 = O2, 5 = O3, 7 = RTW2, 25 = RC2, 49 / 97 / 145 = F2 / F3 / F4, 169 = F4 + RC2 and 175 = F4 + RC2 + RTW2. C is a categorical identifier, not an ordinal resistance measure.

Rule tables#

The probability of each component state depends on the construction period and on whether the building is within coast_threshold_miles of the coast (Peng 2013, Tables 3.6 and 3.7). The constants COMPONENT_RULES_NEAR_COAST and COMPONENT_RULES_FAR_COAST in cheersafe.exposure.archetype hold these values; each cell lists the probabilities of states 1, 2, ... in order.

Near the coast (less than 2 miles):

Component before 1968 1968-1996 1997 and later
RC 1, 0 0.1, 0.9 0, 1
RF 1, 0 1, 0 0.5, 0.5
RTW 1, 0 0.5, 0.5 0.1, 0.9
O 1, 0, 0 0.8, 0.1, 0.1 0.5, 0.25, 0.25
W 1, 0 0.7, 0.3 0.1, 0.9
F 1, 0, 0, 0 0.2, 0.2, 0.2, 0.4 0, 0.1, 0.1, 0.8

Away from the coast (2 miles or more):

Component before 1968 1968-1996 1997 and later
RC 1, 0 0.9, 0.1 0.8, 0.2
RF 1, 0 1, 0 0.9, 0.1
RTW 1, 0 0.9, 0.1 0.8, 0.2
O 1, 0, 0 0.9, 0.05, 0.05 0.8, 0.1, 0.1
W 1, 0 1, 0 0.9, 0.1
F 1, 0, 0, 0 0.85, 0.05, 0.05, 0.05 0.85, 0.05, 0.05, 0.05

calculate_component_probabilities(year_group, near_coast) treats the six components as independent, multiplies the marginal probabilities of every configuration row and normalizes them. Buildings built before 1968 therefore always receive C = 1. calculate_component_configuration groups buildings by period and coast class, draws one uniform number per building from a single stream seeded with Sampling.derive_seed("exposure.component_configuration", seed=...), and inverts the cumulative distribution of the group. The same seed and row order reproduce the same configurations.

Outputs And Returns#

Method Returns
calculate_normalized_attributes(inventory) GeoDataFrame with building_key, the key column when present, is_wood_frame, roof_shape, n_story, has_garage, is_single_family, year_built, coast_distance_miles, structure_value, contents_value, present passthrough columns and geometry; rows missing a required attribute are dropped.
calculate_archetype_m(n_story, is_hip, has_garage) int64 archetype codes 1-8.
calculate_year_group(year_built) int64 period index 0, 1 or 2.
calculate_component_probabilities(year_group, near_coast) Probabilities over the 192 configurations, summing to one.
calculate_component_configuration(year_group, near_coast, seed=None) int64 configurations 1-192.
calculate_archetypes(inventory) The normalized frame plus M, year_group, near_coast, C, RC, RF, RTW, O, W, F.
save_archetype_inventory(path=None) Writes archetype_inventory to GeoParquet and returns the path.

The methods return their results; with Config.AUTO_EXECUTE_METHODS=True, __post_init__ assigns archetype_inventory = calculate_archetypes(inventory).

Configuration Behavior#

Loading follows Config.AUTO_LOAD_DATASETS; the archetype step follows Config.AUTO_EXECUTE_METHODS; Config.RANDOM_SEED seeds the draw when seed is None, so changing it changes C.

Minimal Examples#

Automatic execution:

from cheersafe.exposure import ArchetypeAssigner

assigner = ArchetypeAssigner(seed=42)
print(assigner.archetype_inventory[["building_key", "M", "C", "RC", "RF", "RTW", "O", "W", "F"]].head())

Manual control with the real filter enabled:

from cheersafe.config import Config
from cheersafe.exposure import ArchetypeAssigner

Config.AUTO_LOAD_DATASETS = False
Config.AUTO_EXECUTE_METHODS = False

assigner = ArchetypeAssigner(drop_unmatched_occupancy=True, coast_threshold_miles=2.0, seed=42)
assigner.load_hazard_tables()
assigner.load_component_combinations()
assigner.load_inventory()

near_coast_probabilities = assigner.calculate_component_probabilities(year_group=1, near_coast=True)
assigner.archetype_inventory = assigner.calculate_archetypes(assigner.inventory)
path = assigner.save_archetype_inventory("Outputs/exposure/archetype_inventory.parquet")