You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 1122750
Browse filesBrowse the repository at this point in the historyBrowse files
- Mean and per-realization breakdown of recovery trajectories
98
98
- Gantt chart of impeding factors, repair work, number of workers, and recovery status of building per day for the realization with `p_gantt`-th percentile of functional recovery day.
99
99
100
-
## Example Inputs
101
-
Four example inputs are provided to help illustrate both the construction of the inputs file and the implementation. These files are located in the `examples/` directory and can be run through the assessment by setting the variable names accordingly above.
100
+
## Inputs
101
+
A brief description of the various input variables are provided below. A detailed schema of all expected input and output subfields is provided in [src/atc138/data/default_inputs.json](src/atc138/data/default_inputs.json).
102
102
103
-
##Definition of I/O
104
-
A brief description of the various input and output variables are provided below. A detailed schema of all expected input and output subfields is provided in [src/atc138/data/default_inputs.json](src/atc138/data/default_inputs.json).
103
+
### Example Inputs
104
+
Four example inputs are provided to help illustrate both the construction of the inputs file and the implementation. These files are located in the `examples/` directory and can be run through the assessment by setting the variable names accordingly above.
105
105
106
-
### Inputs
106
+
### Required Building Specific Data
107
+
Each file listed below contains data specific to the building performance model and simulated damage given for a specific level of shaking. Each file listed will need to be created for each unique assessment and saved in the root directory of the build script. Data are contained in either json or csv format.
108
+
-**building_model.json**: Basic properties of the building and performance model. Contains all variables within the _building_model_ structure defined in the inputs schema.
109
+
-**tenant_unit_list.csv**: Table that lists each tenant unit within the building; one row per tenant unit. This table requires the following attributes:
110
+
- id: [int or string] unique identifier for this tenant unit
111
+
- story: [int] building story where this tenant unit is located (ground floor is listed at 1)
112
+
- area: [number] total gross plan area of the tenant unit, in square feet
113
+
- perim_area: [number] total exterior perimeter area (elevation) of the tenant unit, is square feet
114
+
- occupancy_id: [int] foreign key to the _occupancy_id_ attribute of the tenant_function_requirements.csv table in the _data_ directory
115
+
-**comp_ds_list.csv**: Table that lists each component and damage state populated in the building performance model; one row per each component's damage state. This table requires the following attributes:
- ds_seq_id: [int] interger index of the sequential parent damage state (i.e., damage state 1, 2, 3, 4);
118
+
- ds_sub_id: [int] interger index for the mutually exlusive of simeltaneous sub damage state; use 1 to indicate a sequential damage state with no sub damage state.
119
+
-**damage_consequences.json**: Building-level and story-level simulated properties of building damage. Contains all variables within the _damage_consequences_ structure defined in the inputs schema.
120
+
-**simulated_damage.json**: Component-level simulated damage properties. Contains all variables within the _damage.tenant_units_ structure defined in the inputs schema. Each variable containing realization of component damage should be defined uniquely for each tenant unit (shown as "tu" below). Each tenant_unit cell should contain the following variables:
121
+
- tenant_unit{tu}.qnt_damaged: [array: simulations × damage states] The number of damaged components in each component damage state for each realization of the simulation.
122
+
- tenant_unit{tu}.worker_days: [array: simulations × damage states] The number of single worker days required to repair all damage to this damage state of this component at this story for each realization.
123
+
- tenant_unit{tu}.qnt_damaged_side_1: [array: simulations × damage states] The number of damaged components in each component damage state assocaited with side 1 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
124
+
- tenant_unit{tu}.qnt_damaged_side_2: [array: simulations × damage states] The number of damaged components in each component damage state assocaited with side 2 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
125
+
- tenant_unit{tu}.qnt_damaged_side_3: [array: simulations × damage states] The number of damaged components in each component damage state assocaited with side 3 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
126
+
- tenant_unit{tu}.qnt_damaged_side_4: [array: simulations × damage states] The number of damaged components in each component damage state associated with side 4 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
127
+
- tenant_unit{tu}.num_comps: [array: 1 × damage states] The total number of components associated with each damage state (should be uniform for damage state of the same component stack).
107
128
108
-
####Assessment Options
109
-
These options control various aspects of the functional recovery assessment and can be customized via `optional_inputs.json`:
129
+
###Additional Assessment Options
130
+
These options control various aspects of the functional recovery assessment and can be customized via `optional_inputs.json`. To customize assessment options, create an `optional_inputs.json` file in your input directory (can copy over from examples) with only the fields you want to override. Default analysis options are defined from [src/atc138/data/default_inputs.json](src/atc138/data/default_inputs.json)
110
131
111
132
-**impedance_options**: Python dictionary containing method inputs for assessing impeding factors (delays in starting repairs). Key fields include:
112
133
-`include_impedance`: Enable/disable different delay types (inspection, financing, permitting, engineering, contractor)
@@ -132,56 +153,19 @@ These options control various aspects of the functional recovery assessment and
132
153
-`habitability_requirements`: Utility requirements for habitability (electrical, water, HVAC)
133
154
-`water_pressure_max_story`: Maximum stories affected by water pressure loss
134
155
-`heat_utility`: Fuel type for heating ("gas" or "electric")
156
+
157
+
### Optional Building Specific Data
158
+
The file(s) listed below contain data that is optional for the assessment. If the files do not exist, the method will make simplifying assumptions to account for the missing data (as noted below). Save in the input directory of your analysis.
159
+
-**utility_downtime.json**: Regional utility simulated downtimes for gas, water, and electrical power networks. Should contain arrays for each utility type with downtime in days per realization. If missing, assumes zero downtime for all utilities.
135
160
136
-
#### Building and Damage Data
137
-
-**building_model**: Python dictionary containing general building information such as number of stories, building area, and component populations
138
-
-**damage**: Python dictionary containing simulated component damage, repair times, and component attributes for each damage state
139
-
-**damage_consequences**: Python dictionary containing simulated building consequences such as red tags and repair cost ratios
140
-
-**functionality['utilities']**: Python dictionary containing simulated regional utility downtimes for gas, water, and electrical networks (optional - defaults to zero downtime if missing)
141
-
-**tenant_units**: Python dictionary containing attributes and functional requirements for each tenant unit in the building
142
-
143
-
### Outputs
144
-
-**functionality['recovery']**: Python dictionary
145
-
Python dictionary containing the simulated tenant- and building-level functional recovery and reoccupancy outcomes
Python dictionary containing the simulated impeding factors delaying the start of system repair
152
-
153
-
## Overriding Default Inputs
161
+
### Overriding Default Inputs
154
162
155
163
The assessment uses a hierarchy of input sources, with later sources taking precedence over earlier ones:
156
164
157
165
1.**Built-in defaults** from [src/atc138/data/default_inputs.json](src/atc138/data/default_inputs.json)
158
166
2.**Custom static tables** (CSV files copied to input directory)
159
167
3.**optional_inputs.json** (highest priority for assessment options)
160
168
161
-
### Using optional_inputs.json
162
-
163
-
To customize assessment options, create an `optional_inputs.json` file in your input directory with only the fields you want to override. The file should follow this structure:
164
-
165
-
```json
166
-
{
167
-
"impedance_options": {
168
-
"include_impedance": {
169
-
"engineering": false
170
-
},
171
-
"default_lead_time": 90
172
-
},
173
-
"repair_time_options": {
174
-
"max_workers_building_max": 150
175
-
},
176
-
"functionality_options": {
177
-
"egress_threshold": 0.75,
178
-
"fire_watch": false
179
-
}
180
-
}
181
-
```
182
-
183
-
This example disables engineering delays, reduces default lead time to 90 days, increases max workforce to 150, raises egress threshold to 75%, and disables fire watch requirements.
184
-
185
169
### Customizing Static Tables
186
170
187
171
To override default component, system, or tenant attributes, copy the relevant CSV file from `src/atc138/data/` to your input directory and modify it:
@@ -195,84 +179,17 @@ To override default component, system, or tenant attributes, copy the relevant C
195
179
196
180
For example, to modify component repair times, copy `component_attributes.csv` to your input directory and edit the relevant rows.
197
181
198
-
## Input Validation & Common Errors
199
-
200
-
The input builder performs basic validation and will raise errors for common issues:
201
-
202
-
### Required Files Missing
203
-
**Error**: `FileNotFoundError` or similar when a required file is missing
**Solution**: Ensure all required files exist in the input directory
182
+
## Outputs
183
+
A brief description of the various output variables are provided below. A detailed schema of all expected input and output subfields is provided in [src/atc138/data/default_inputs.json](src/atc138/data/default_inputs.json).
206
184
207
-
### Invalid Occupancy IDs
208
-
**Error**: `ValueError: Could not find occupancy_id X in tenant_function_requirements`
209
-
**Cause**: `occupancy_id` in `tenant_unit_list.csv` doesn't match any ID in the tenant function requirements table
210
-
**Solution**: Check that all occupancy IDs in your tenant list match those in `tenant_function_requirements.csv` (or your custom version)
211
-
212
-
### Component ID Mismatches
213
-
**Error**: `ValueError: Could not find component attributes for component X`
214
-
**Cause**: Component ID in `comp_ds_list.csv` doesn't exist in component attributes table
215
-
**Solution**: Verify component IDs match between `comp_ds_list.csv` and `component_attributes.csv`
216
-
217
-
### CSV Format Issues
218
-
**Error**: Pandas parsing errors or unexpected column names
219
-
**Cause**: CSV files have incorrect headers, missing columns, or malformed data
220
-
**Solution**: Check column names match expected format (see file descriptions above)
221
-
222
-
### Damage State Mapping Issues
223
-
**Error**: Issues with damage state attribute matching
224
-
**Cause**: Damage state regex patterns in `damage_state_attribute_mapping.csv` don't match component damage states
225
-
**Solution**: Review damage state naming conventions and regex patterns
226
-
227
-
### Utility Downtime Format
228
-
**Note**: `utility_downtime.json` is optional - if missing, assumes zero utility downtime
229
-
**Format**: Should contain arrays for gas, water, and electrical downtime per realization
230
-
231
-
## Manually building the Inputs File
232
-
By default, the inputs file are built from a simpler set of building inputs, taking advantage of default assessment assumptions and component, system, and tenant attributes contained within the _data_ directory. If you would like to manually modify the data tables listed below for a specific model, simply copy the files to the input directory and modify them.
233
-
234
-
### Required Building Specific Data
235
-
Each file listed below contains data specific to the building performance model and simulated damage given for a specific level of shaking. Each file listed will need to be created for each unique assessment and saved in the root directory of the build script. Data are contained in either json or csv format.
236
-
-**building_model.json**: Basic properties of the building and performance model. Contains all variables within the _building_model_ structure defined in the inputs schema.
237
-
-**tenant_unit_list.csv**: Table that lists each tenant unit within the building; one row per tenant unit. This table requires the following attributes:
238
-
- id: [int or string] unique identifier for this tenant unit
239
-
- story: [int] building story where this tenant unit is located (ground floor is listed at 1)
240
-
- area: [number] total gross plan area of the tenant unit, in square feet
241
-
- perim_area: [number] total exterior perimeter area (elevation) of the tenant unit, is square feet
242
-
- occupancy_id: [int] foreign key to the _occupancy_id_ attribute of the tenant_function_requirements.csv table in the _data_ directory
243
-
-**comp_ds_list.csv**: Table that lists each component and damage state populated in the building performance model; one row per each component's damage state. This table requires the following attributes:
- ds_seq_id: [int] interger index of the sequential parent damage state (i.e., damage state 1, 2, 3, 4);
246
-
- ds_sub_id: [int] interger index for the mutually exlusive of simeltaneous sub damage state; use 1 to indicate a sequential damage state with no sub damage state.
247
-
-**damage_consequences.json**: Building-level and story-level simulated properties of building damage. Contains all variables within the _damage_consequences_ structure defined in the inputs schema.
248
-
-**simulated_damage.json**: Component-level simulated damage properties. Contains all variables within the _damage.tenant_units_ structure defined in the inputs schema. Each variable containing realization of component damage should be defined uniquely for each tenant unit (shown as "tu" below). Each tenant_unit cell should contain the following variables:
249
-
- tenant_unit{tu}.qnt_damaged: [array: simulations × damage states] The number of damaged components in each component damage state for each realization of the simulation.
250
-
- tenant_unit{tu}.worker_days: [array: simulations × damage states] The number of single worker days required to repair all damage to this damage state of this component at this story for each realization.
251
-
- tenant_unit{tu}.qnt_damaged_side_1: [array: simulations × damage states] The number of damaged components in each component damage state assocaited with side 1 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
252
-
- tenant_unit{tu}.qnt_damaged_side_2: [array: simulations × damage states] The number of damaged components in each component damage state assocaited with side 2 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
253
-
- tenant_unit{tu}.qnt_damaged_side_3: [array: simulations × damage states] The number of damaged components in each component damage state assocaited with side 3 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
254
-
- tenant_unit{tu}.qnt_damaged_side_4: [array: simulations × damage states] The number of damaged components in each component damage state associated with side 4 of the building; set to zero if not associated with a particular side. This is only for exterior cladding components.
255
-
- tenant_unit{tu}.num_comps: [array: 1 × damage states] The total number of components associated with each damage state (should be uniform for damage state of the same component stack).
256
-
257
-
### Optional Building Specific Data
258
-
The file(s) listed below contain data that is optional for the assessment. If the files do not exist, the method will make simplifying assumptions to account for the missing data (as noted below). Save in the input directory of your analysis.
259
-
-**utility_downtime.json**: Regional utility simulated downtimes for gas, water, and electrical power networks. Should contain arrays for each utility type with downtime in days per realization. If missing, assumes zero downtime for all utilities.
260
-
261
-
### Default Optional Inputs
262
-
Assessment options are controlled by `optional_inputs.json`. See the [Overriding Default Inputs](#overriding-default-inputs) section above for details on structure and usage.
263
-
264
-
### Static Data
265
-
The CSV tables listed below contain default component, damage state, system, and tenant function attributes. These are located in `src/atc138/data/` and can be overridden by copying files to your input directory (see [Customizing Static Tables](#customizing-static-tables) above).
266
-
-**component_attributes.csv**: Component properties (repair costs, crew sizes, system assignments)
267
-
-**damage_state_attribute_mapping.csv**: How damage states affect function and reoccupancy
268
-
-**systems.csv**: System definitions and functional requirements
0 commit comments