CHEERSafe Input Manual

This page describes the input files loaded by CHEERSafe at runtime. The runtime JSON and CSV files in Inputs/ are the source of truth. The temporary workbook Inputs/RawData_WithHeaders.xlsx was used here only to recover labels, units, and assumptions for the manual.

Runtime files are authoritative

CHEERSafe calculations load the JSON and CSV files directly. If a workbook value differs from a runtime file, use the runtime file value unless the input file itself is intentionally updated.

Known differences found while preparing this page:

• BuildingGeometry.json and BuildingGeometry_Old.json contain rounded geometry values relative to the workbook, such as roof pitch and roof dimensions.
• WindSpeed.json stores metric wind speeds rounded to one decimal place, while the workbook keeps more decimal precision.
• MeanResistanceCV.json currently stores 0.3 for all component and configuration entries, while the workbook's current resistance sheet shows component-specific CV values.
• CCRoofGCp.json stores roof zone coefficients [-0.9, -2.1, -2.1]; the workbook's current pressure-coefficient sheet lists roof zone 2 as -1.7.

Input Conventions

CHEERSafe expects the standard runtime input files under Config.INPUTS_PATH, which defaults to Inputs. Most input loaders call Utils.from_json, which converts JSON arrays to NumPy arrays. JSON objects, such as Hurricane_ProbWindFlood.json, are returned as dictionaries whose values are arrays after downstream use. The building-value file is a CSV read with pandas.

Many tables include an explicit ID, building type, component configuration, or damage-state number. These values are 1-based in the input files. Internally, Python code often subtracts 1 when indexing arrays, so do not renumber file IDs to zero-based values.

Array shapes in this manual use the following axis names:

Axis	Meaning
i	Spatial zone or inventory index. Runtime regional inputs use 1509 zones.
m	Building type. CHEERSafe includes 8 building types.
c	Component or resistance configuration. The full runtime set has 192 configurations.
h	Hurricane event index. The bundled hurricane input has 97 events.
f	Flood-depth index. The bundled flood-depth grid has 136 depths.
d	Damage-state index. Wind has 50 states; flood has 6 states.
b	Building index of an exposure export. Rows of Inventory.csv and of the hazard-ID arrays align.
z	Zone id of the exposure and regional-loss workflow, for example LEAPHI i_lh740 or i_lh503; -1 means unassigned.

Input File Overview

File	Runtime shape	Purpose	Loaded by	Usually edit?
BuildingGeometry.json	[28, 8]	Current building geometry table.	Inventory	Yes, for custom archetypes
BuildingGeometry_Old.json	[28, 8]	Historical geometry table used by the default inventory loader.	Inventory	Rarely
MeanResistanceValue.json	[10, 3]	Mean component resistance values.	Damage probability calculation	Yes, for vulnerability studies
MeanResistanceCV.json	[10, 3]	Coefficients of variation for component resistance.	Damage probability calculation	Yes, for vulnerability studies
ComponentCombination_All.json	[192, 6]	Compact list of all component and flood configuration combinations.	Damage probability and damage ratio calculation	Rarely
ComponentCombination_Hip.json	[24, 10]	Hip-roof component combination table.	Damage probability calculation	Rarely
ComponentCombination_Gable.json	[48, 10]	Gable-roof component combination table.	Damage probability calculation	Rarely
WindSpeed.json	[25, 3]	Wind-speed grid in mph and m/s.	Damage probability, analysis, loss estimation	Yes, to change hazard bins
FloodDepth.json	[136, 3]	Flood-depth grid in inches and meters.	Damage probability analysis and loss estimation	Yes, to change hazard bins
WindOrientation.json	[8, 2]	Wind direction grid in degrees.	Damage probability calculation	Rarely
CCRoofGCp.json	[3]	Roof component-and-cladding pressure coefficients.	Loading and failure checks	Rarely
CCWallGCp.json	[4]	Wall component-and-cladding pressure coefficients.	Loading and failure checks	Rarely
MWFRSCp.json	[8]	Main wind force resisting system pressure coefficients.	Loading and failure checks	Rarely
DamageState.json	[50, 2]	Wind damage-state index and damage ratio.	Damage probability, analysis, loss estimation	Yes, if redefining wind states
DamageState_Flood.json	[6, 2]	Flood damage-state index and lower damage-range percent.	Damage ratio calculation	Yes, if redefining flood states
ProbDS_Flood.json	[8, 4, 136, 6]	Flood damage-state probability curves by building type and flood configuration.	Damage probability and damage ratio calculation	Advanced only
ReplacementRatio.json	[8, 9]	Replacement-cost shares by building type and component.	Damage ratio calculation	Yes, for cost-model changes
Hurricane_ProbWindFlood.json	object	Hurricane wind, flood, flood-ratio, and probability arrays; Hurricane_Prob [97, 2] gives the annual event probabilities used for expected annual loss.	Loss estimation	Yes, for regional studies
X_imc.json	[1509, 8, 192]	Regional building inventory counts by zone, building type, and component configuration.	Legacy regional workflow; not read by the current package	Rarely
Building_imc_Component_ZTRAXPropValueSample.csv	931902 rows x 13 columns	Building-level value and component configuration sample.	Legacy regional workflow; not read by the current package	Rarely
Building inventory layer	one row per building	User inventory in GeoParquet, shapefile or GeoPackage form; see Exposure And Building-Level Loss Inputs.	Exposure	Yes, your own inventory
Hazard control-point layers	n_points rows per event	One point layer per hazard event with wind and flood columns.	Exposure	Yes, your own hazard set
Zone layer	polygons	Zone system used for zone ids and regional aggregation.	Exposure and regional loss estimation	Yes, your own zones
Damage library pickle	dict[(m, c) -> (25, 136, 50)]	Damage-state probabilities per archetype, configuration, wind ID and flood ID (the aggregated ProbDS_*_aggregated.pkl).	Loss estimation	Produced by the damage probability calculation

Building And Resistance Inputs

Building Geometry

BuildingGeometry.json and BuildingGeometry_Old.json share the same schema: 28 rows by 8 building-type columns. Each column is one archetype. Row 1 stores the building type index, and rows 2 through 28 store the attributes used to instantiate Building objects.

BuildingInventory currently defaults to BuildingGeometry_Old.json. Use BuildingGeometry.json explicitly when you want the newer geometry table.

Row	Building attribute	Unit or code	Meaning
1	BldgType	ID	Building type index, 1 through 8.
2	Story	1 or 2	Number of stories.
3	Material	1 wood, 2 URM	Wall/building material code.
4	WallFloorCon_FrontBack	count	Wall-floor connections on front and back walls.
5	WallFloorCon_Side	count	Wall-floor connections on side walls.
6	BldgLength	ft	Building length.
7	BldgWidth	ft	Building width.
8	MeanRoofHeight	ft	Mean roof height.
9	WallHeight	ft	Wall height.
10	OpeningFront	count	Front windows.
11	OpeningBack	count	Back windows.
12	OpeningSideR	count	Regular side windows.
13	OpeningSideH	count	High side windows.
14	OpeningLength	ft	Window length, vertical dimension.
15	OpeningWidth	ft	Window width, horizontal dimension.
16	DoorFront	count	Front doors.
17	DoorGarage	count	Garage doors.
18	DoorBack	count	Back doors.
19	RoofShape	1 hip, 2 gable	Roof-shape code.
20	RoofPitchDegree	degrees	Roof pitch angle.
21	RoofPitch_r	rise/run	Roof pitch as a ratio.
22	RoofHeight	ft	Roof height.
23	RoofWidth	ft	Roof width.
24	HipRidgeLength	ft	Hip ridge length.
25	HipRidgeAngle	degrees	Hip ridge angle.
26	TrussSpacing	ft	Roof truss spacing.
27	SheathingLength	ft	Sheathing panel length.
28	SheathingWidth	ft	Sheathing panel width.

Current and old geometry

The workbook labels BuildingGeometry_Old as the geometry from Jiazhen's dissertation. BuildingGeometry follows the same schema but changes the opening counts, especially the window counts. The runtime code still uses the old file by default unless a different buildings_file_name is passed.

Mean Resistance Values And CVs

MeanResistanceValue.json and MeanResistanceCV.json both use 10 component rows and 3 resistance-configuration columns. Empty workbook cells are stored as 0 in MeanResistanceValue.json. Runtime component combinations choose one of these configuration columns for each component family.

Row	Component	Short name	Unit for mean resistance	Configuration columns
1	Roof cover	RC	psf	1, 2
2	Roof sheathing	RS	psf	1, 2
3	Roof-to-wall connection, side	RWC	lbs	1, 2
4	Roof-to-wall connection, gable	RWC	lbs	1, 2
5	Opening, door	O	psf	1, 2, 3
6	Opening, garage door	O	psf	1, 2, 3
7	Opening, window	O	psf	1, 2, 3
8	Wall, shear	W	lb/linear ft	1, 2
9	Wall, uplift	W	lb/ft	1, 2
10	Wall, out-of-plane	W	lbs	1, 2

Runtime mean resistance values are:

Component	Config 1	Config 2	Config 3
Roof cover	50	70	0
Roof sheathing	100	225	0
RWC side	1400	2825	0
RWC gable	1400	2825	0
Door	75	150	113
Garage door	50	75	75
Window	55	110	82.5
Wall shear	1100	1100	0
Wall uplift	1000	1000	0
Wall out-of-plane	2000	3000	0

Resistance CV reconciliation

MeanResistanceCV.json currently contains 0.3 in every row and column. Treat that as the value used by CHEERSafe until the JSON file is changed. Do not infer the runtime CVs from the workbook's current resistance sheet.

Component Combinations

Component combinations define which resistance configuration applies to each component family.

File	Shape	Columns or axes	Notes
ComponentCombination_All.json	[192, 6]	RC, RS, RWC, O, W, F	Full compact set. The first five columns select wind resistance configurations; F selects the flood probability configuration.
ComponentCombination_Hip.json	[24, 10]	Expanded hip-roof combination rows	Used when processing hip-roof building types.
ComponentCombination_Gable.json	[48, 10]	Expanded gable-roof combination rows	Used when processing gable-roof building types.

The compact configuration IDs are 1-based. For example, a row beginning [1, 1, 2, 3, 1, 1] means roof cover config 1, roof sheathing config 1, roof-to-wall connection config 2, opening config 3, wall config 1, and flood config 1.

Hazard And Pressure Inputs

Wind, Flood, And Orientation Grids

WindSpeed.json, FloodDepth.json, and WindOrientation.json define the discrete hazard grid used in probability and loss calculations.

File	Columns	Runtime range
WindSpeed.json	ID, WindSpeed (mph), WindSpeed (m/s)	25 rows, from 0 mph to 215 mph. Metric speeds are rounded to one decimal place.
FloodDepth.json	ID, FloodDepth (inch), FloodDepth (meter)	136 rows, from 0 inches to 270 inches.
WindOrientation.json	ID, Angle (degrees)	8 rows: 0, 45, 90, 135, 180, 225, 270, and 315 degrees.

The ID column is part of the file format. It is not the same as a zero-based Python array index.

Wind Pressure Coefficients

Pressure coefficients are dimensionless and are loaded by the loading and failure-check classes.

File	Runtime values	Meaning
CCRoofGCp.json	[-0.9, -2.1, -2.1]	Roof component-and-cladding GCp values for zones 1, 2, and 3.
CCWallGCp.json	[1, -1.4, -1.1, -0.8]	Wall component-and-cladding GCp values for windward, side leading edge, side, and leeward walls.
MWFRSCp.json	[0.8, -0.3, -0.7, -0.25, -0.57, -0.9, -0.5, -0.3]	Main wind force resisting system coefficients for building surfaces 1 through 8.

Damage, Flood, And Loss Inputs

Damage States

DamageState.json defines wind damage states as pairs of damage-state index and damage ratio. The bundled file has 50 states. It starts at damage ratio 0, increments by 0.004 through the early states, and ends at damage state 50 with damage ratio 1.4.

DamageState_Flood.json defines flood damage-state thresholds as pairs of damage-state index and lower damage-range percent:

Flood damage state	Lower damage range (%)
1	0
2	1
3	11
4	21
5	31
6	41

Flood Damage-State Probabilities

ProbDS_Flood.json has shape [8, 4, 136, 6]. The curves are adopted from Taggart, M. (2007), Performance based design of woodframe structures for flooding, Colorado State University. Only the storey count distinguishes building types (types 1-4 share one surface, 5-8 another), and flood configuration 4 (house elevated 24 in.) is configuration 1 translated by 24 in. of depth.

Axis	Meaning
1	Building type m, values 1 through 8.
2	Flood configuration F, values 1 through 4 from ComponentCombination_All.json.
3	Flood-depth row from FloodDepth.json.
4	Flood damage state from DamageState_Flood.json.

Each [m, F, f, :] slice is a probability vector over the 6 flood damage states. Damage-ratio code converts the selected vector to a cumulative distribution before sampling.

Replacement Ratios

ReplacementRatio.json has shape [8, 9]. Rows are building types 1 through 8, and columns are replacement-cost shares by component.

Column	Component
1	Roof cover (RC)
2	Roof sheathing (RS)
3	Roof-to-wall connection (RWC)
4	Opening (O)
5	Wall (W)
6	Interior
7	Electrical
8	Mechanical
9	Plumbing

The workbook includes a Sum column for checking totals, but the runtime JSON stores only the 9 component-share columns. Current row totals are about 1.10 or 1.11 depending on building type.

Hurricane Hazard And Exposure Inputs

Hurricane Probability, Wind, Flood, And Flood Ratio

Hurricane_ProbWindFlood.json is a JSON object with four keys:

Key	Shape	Meaning
Hurricane_WindSpeed	[1509, 97]	Wind speed by zone and hurricane event.
Hurricane_FloodDepth	[1509, 97]	Flood depth by zone and hurricane event.
Hurricane_FloodRatio	[1509, 97]	Flood-exposed share or ratio by zone and hurricane event.
Hurricane_Prob	[97, 2]	Hurricane event probability table.

Loss estimators adjust wind and flood arrays by peril. For WIND, flood depth is set to zero; for FLOOD, wind speed is set to zero.

Regional Inventory

X_imc.json has shape [1509, 8, 192]. It stores regional exposure counts by zone i, building type m, and component configuration c. RegionalLossEstimator broadcasts this inventory against component losses and sums over i, m, and c to produce hurricane-level regional losses.

Building Values CSV

Building_imc_Component_ZTRAXPropValueSample.csv is the building-level exposure and value file used by BuildingLossEstimator. The bundled CSV has 931902 data rows and these columns:

Column	Meaning
i	Source zone or record group identifier.
m	Building type.
c	Component/resistance configuration.
RC	Roof cover configuration.
RS	Roof sheathing configuration.
RWC	Roof-to-wall connection configuration.
O	Opening configuration.
W	Wall configuration.
F	Flood configuration.
num_stories	Number of stories.
total_value	Total property value.
improvement_value	Structure or improvement value used for building loss.
ind_1509	Regional zone index used to look up hurricane wind and flood data.

For building-level loss estimates, m, c, ind_1509, and improvement_value are the key fields used directly in the loss loop. Keep component configuration fields consistent with ComponentCombination_All.json when preparing a custom CSV.

Exposure And Building-Level Loss Inputs

The exposure module (cheersafe.exposure) and the building-level loss workflow (cheersafe.loss_estimation) consume user-supplied geospatial layers in addition to the JSON tables above. Paths are explicit fields of the classes; fields left as None resolve under Config.INPUTS_PATH.

Building Inventory Layer

One row per building, GeoParquet (.parquet), shapefile or GeoPackage, with a coordinate reference system. Point or polygon geometry is accepted; centroids are used. Column names and category values are declared through InventorySchema; the defaults below are the Eastern North Carolina inventory.

Attribute	Default column	Default values	Required
Building material	bldgtype	W = wood frame	No (flag only, unless drop_unmatched_occupancy)
Roof shape	roof_shape_1	Cross Gable, Complex Gable, Gable = gable; Hip, Cross Hip = hip	Yes
Stories	Story_AI	1, 2	Yes
Garage	Garage	0 = none, 1 = attached	Yes
Occupancy	PRIM_OCC	Single Family Dwelling	No (flag only, unless drop_unmatched_occupancy)
Year built	med_yr_blt	integer year	Yes
Distance to coast	Coast_D (miles)	numeric, times coast_distance_to_miles (1.0)	Yes
Structure value	val_struct	numeric	Yes
Contents value	val_cont	numeric	Yes
Building key	fd_id_nsi	unique id, copied to building_key	No (row position otherwise)
Passthrough	is_vacant, H_TEN_syn, AGEP_syn, H_HINCP_syn	copied to the export when present	No

Rows missing any required attribute are dropped by ArchetypeAssigner; rows whose material or occupancy does not match are kept and flagged unless the filter is enabled. SyntheticExposureData.make_inventory produces a layer in exactly this schema for tests and examples.

Hazard Control-Point Layers

One point layer per hazard event in one folder (hazard_dir, pattern *.parquet by default), all sharing the same control points in the same order. Files are ordered by the integer embedded in their names (h1.parquet, ..., h97.parquet).

Column	Meaning
cell_ID	Control-point identifier (informational).
x, y	Coordinates in the layer CRS (informational; the geometry is used).
Wind (wind_col)	Maximum wind speed in m/s; converted with wind_to_mph = 2.23694.
Flood (flood_col)	Flood depth in m; converted with flood_to_inches = 39.3701.
geometry	Point geometry.

The nodata sentinel -9999 (nodata_value) and missing values are treated as zero hazard. The Eastern North Carolina set (Old97, Apivatanagul et al. 2011) has 97 events on a 1 km grid in EPSG:5070 with origin (1479654.52465404, 1345256.36347185), cell size 1000 m, control points at cell centres and cell_ID = ix * 350 + iy + 149103; its annual event probabilities are Hurricane_Prob in Hurricane_ProbWindFlood.json.

Zone Layers

A polygon layer covering the whole zone system in one file, in any CRS. The LEAPHI layer leaphi_zones_20230920 carries COUNTYFP00 (county FIPS), zone (coastal band 1-3) and the nested zone ids i_lh503, i_lh708, i_lh740, i_lh1509. Exposure.zone_id_col selects the id written to the export (i_lh740 by default); RegionalLossEstimator.aggregation_col remaps it to a coarser nested system such as i_lh503. Buildings outside every zone receive -1.

Damage Library Pickle

A Python pickle of dict[(m, c) -> np.ndarray] with 1-based archetype m and configuration c keys and float32 tensors of shape (n_wind_ids, n_flood_ids, n_damage_states) = (25, 136, 50). Each row is a probability distribution over the damage states of DamageState.json (loss ratios 0 to 1.4). LookupTableBuilder reports rows that do not sum to one and fills pairs absent from the library with NaN. The aggregated output of the damage probability calculation (Outputs/ProbDS_wfd_dictMaxIter{NUM_OF_ITERATIONS}_aggregated.pkl) is the default; DamageProbabilityProvider.prob_ds_file_path points at any other file.

Hurricane Event Probabilities

Hurricane_ProbWindFlood.json["Hurricane_Prob"] has shape [97, 2]: column 0 is the event id 1..97 in order and column 1 the annual probability p_h. The sum is 0.3235 per year and is not normalized. Column j of the hazard-ID arrays must be event j of this table; the loaders assert that the counts agree. BaseLossEstimation.hurricane_probabilities accepts an explicit vector for custom event sets.

STARR Export Artifacts

Exposure.save_starr_inputs writes, and BuildingLossEstimator.load_exposure_inputs reads:

File	Contents
Inventory.csv	building_ID, t, YearBuilt, YearBuiltGroup, <zone id>, M, C, RC, RF, RTW, O, W, F, structure_value, contents_value, home_value, [fd_id_nsi, passthrough columns], x, y, lon, lat, building_key.
Wind_Tr.npy, Flood_Tr.npy	Continuous 1-based hazard IDs, float32, shape (n_buildings, n_events), rows aligned with Inventory.csv.
Hurricane_name.npy	Event names aligned with the array columns (unicode).
HazardInput_metadata.txt	Run settings and array shapes.
archetype_inventory.parquet, clipped_inventory.parquet	Intermediate GeoParquet layers.