# SP3-Batch Documentation (for release)

SP3-Batch inputs and outputs are done in a CSV file format, to make it quick and efficient to run full FEMA P-58/SP3 risk analyses for large numbers of buildings all at once. The SP3-Batch input files must conform to a set of specific guidelines so the inputs can be evaluated correctly; this page documents those inputs. This page also documents the outputs provided by SP3-Batch and the structure of those output files.

A sample of input and output files are available here:

Sample input file:

Sample output file:

# Input File Layout

Input files must**:**

Have a name with alphanumeric characters [0-9a-zA-Z] and can contain the "-" and "_" characters.

Be a CSV file with the

**.csv**suffix.Conform to RFC4180 Standards with Unix end-of-line characters.

Specify column headings in first line (see example below). Files with missing or invalid header lines will not process.

Only contain rows with all required columns and correct value types.

Provided below are the required column names and the expected value types. Please note that most column names have the format **<namespace>.<variable>**, this is by design and must be implemented. Also note that the values must conform to the value types specified.

### Required Minimum Input Values:

Column Name | Value Type | Constraints | Description |
---|---|---|---|

id | string | Must be unique in context to the particular batch* | Input set identifier |

site.lat | number | Latitude coordinate value | Latitude of the site to be analyzed |

site.lng | number | Longitude coordinate value | Longitude of the site to be analyzed |

building.year_of_construction | integer | Positive value only | Year date at which the building was constructed |

building.num_stories | integer | Positive value only | Total number of stories above grade of the building being analyzed |

building.building_type_id | string | Limited to the Building Structural Types table below | The structural system of the building being analyzed |

* We encourage using the UUID v4 standard for this purpose.

### Optional Input Values (when not input, the SP3 Engine will default these values for you):

Column Name | Value Type | Constraints | Description |
---|---|---|---|

building.occupancy_id | integer | Limited to the Building Occupancy Types table below | The occupancy of the building being analyzed |

site.vs30 | number | Non-Negative | Shear wave velocity of the soil at the site being analyzed in m/s |

building.irregularities.plan | integer | 0-2 (inclusive) | Torsional irregularity; 0 being no irregularity, 1 being a moderate irregularity, and 2 being an extreme irregularity |

building.irregularities.vertical | integer | 0-2 (inclusive) | Weak/soft story at the base of the building; 0 being no irregularity, 1 being a moderate irregularity, and 2 being an extreme irregularity |

building.total_area_ft | number | Non-Negative | Gross area of the entire building being analyzed in square feet |

building.building_height_ft | number | Non-Negative | Total height of the building above grade in feet |

building.building_value | number | Non-Negative | Total value of the building in US dollars |

building.construction_quality | number | Value of 1 to 4 | Ratio quantifying the quality of construction; 1 (poor), 2 (fair), 3 (good, default), 4 (excellent) |

building.retrofit_str_year | integer | Non-Negative | Year of structural retrofit if applicable |

building.retrofit_str_level | number | Value ranging from 0 to 1.0 | Ratio quantifying the extent of the structure retrofit; 1.0 being comprehensive and 0.0 being no effect |

building.retrofit_ns_year | integer | Non-Negative | Year of nonstructural retrofit if applicable |

building.retrofit_ns_level | number | Value ranging from 0 to 1.0 | Ratio quantifying the extent of the nonstructural retrofit; 1.0 being comprehensive and 0.0 being no effect |

hazard.return_periods | array | Array of positive values (eg. [72,475]), limit 5 | Return periods in years of the seismic hazard level to be analyzed |

### Building Structural Types (USA)

building.building_type_id | Building Type (Structural System) | Max Number of Stories |
---|---|---|

W1a | Single Family Dwelling Wood Light Frame | 6 |

W2a | General Wood Light Frame | 6 |

W2b | Wood Light Frame over Podium: RC Walls | 8 |

W2c | Wood Light Frame over Podium: RC Frame | 8 |

S1a | Steel Moment Frame (Perimeter) | 45 |

S1b | Steel Moment Frame (Space) | 45 |

S1c | Steel Moment Frame Perimeter SidePlate Connection | 45 |

S1d | Steel Moment Frame Perimeter Simpson Strong-Tie Yield-Link Connection for SMF | 45 |

S2a | Steel Braced Frame (Concentric) | 45 |

S2b | Steel Braced Frame (Eccentric) | 45 |

S2c | Steel Buckling-Restrained Braced Frame: Generic FEMA P-58 | 45 |

S2d | Steel Buckling-Restrained Braced Frame: CoreBrace without Back-up Frame | 45 |

S2e | Steel Buckling-Restrained Braced Frame: CoreBrace with Back-up Frame | 45 |

S3a | Steel Light Frame | 6 |

S3b | Steel Light Frame over Podium: RC Walls | 8 |

S3c | Steel Light Frame over Podium: RC Frame | 8 |

C1a | RC Moment Frame (Perimeter) | 45 |

C1b | RC Moment Frame (Space) | 45 |

C2a | RC Cantilever Shear Wall | 45 |

C2b | RC Coupled Shear Wall | 45 |

C2c | RC Shear Wall with RC Frame | 45 |

PC1a | Single-Story Rigid-Wall Flexible Diaphragm | 1 |

PC2a | PRESS Frame | 45 |

RM1a | Single-Story Rigid-Wall Flexible Diaphragm | 1 |

RM2a | Reinforced Masonry with Rigid Diaphragms | 5 |

S4a | RC Shear Wall with Steel Frame | 45 |

### Building Occupancy Types

building.occupancy_id | Occupancy Type |
---|---|

1 | Commercial Office |

2 | Education [k-12]: Elementary Schools |

3 | Education [k-12]: Middle Schools |

4 | Education [k-12]: High Schools |

5 | Healthcare |

6 | Hospitality |

7 | Multi-Unit Residential |

8 | Research |

9 | Retail |

10 | Warehouse |

11 | Single-Unit Residential |

### Example Header Line

id,site.lat,site.lng,building.year_of_construction,building.num_stories,building.building_type_id |
---|

### Example Value Line*

"6d046874-89c6-11e7-bb31-be2e44b06b34",34.05,-118.25,2017,10,"C1a" |
---|

*Matches the example header line

# Output File Layout

### Output File Fields:

Column Name | Value Type | Constraints | Description | Array Dimensions |
---|---|---|---|---|

id | string | Must be unique in context to the particular batch | The input set identifier from the input file | - |

loss.total.mean | array | Non-Negative | Mean loss (including collapse and demolition from excessive residual drift) | intensities |

loss.total.fractiles | array | Non-Negative | 10%, 20%, ..., 90% fractiles on the mean loss (including collapse and demolition from excessive residual drift) | 9 x intensities |

loss.total.no_col.mean | array | Non-Negative | Mean loss excluding collapse cases | intensities |

loss.total.no_col.med | array | Non-Negative | Median loss excluding collapse cases | intensities |

loss.total.no_rd.mean | array | Non-Negative | Mean loss excluding residual drift demolitions | intensities |

loss.total.no_rd.med | array | Non-Negative | Median loss excluding residual drift demolitions | intensities |

loss.total.no_col_no_rd.mean | array | Non-Negative | Mean loss excluding collapse and residual drift demolition cases | intensities |

loss.total.no_col_no_rd.med | array | Non-Negative | Median loss excluding collapse and residual drift demolition cases | intensities |

loss.breakdown.collapse.mean | array | Non-Negative | Collapse contribution to mean loss | intensities |

loss.breakdown.collapse.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of collapse contribution to mean loss | 9 x intensities |

loss.breakdown.residual_drift.mean | array | Non-Negative | Residual drift contribution to mean loss | intensities |

loss.breakdown.residual_drift.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of residual drift contribution to mean loss | 9 x intensities |

loss.breakdown.structural_components.mean | array | Non-Negative | Structural component contribution to mean loss | intensities |

loss.breakdown.structural_components.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of structural component contribution to mean loss | 9 x intensities |

loss.breakdown.partition_walls.mean | array | Non-Negative | Partition wall contribution to mean loss | intensities |

loss.breakdown.partition_walls.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of partition wall contribution to mean loss | 9 x intensities |

loss.breakdown.exterior_cladding.mean | array | Non-Negative | Exterior cladding contribution to mean loss | intensities |

loss.breakdown.exterior_cladding.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of exterior cladding contribution to mean loss | 9 x intensities |

loss.breakdown.interior_finishes.mean | array | Non-Negative | Interior finish components contribution to mean loss | intensities |

loss.breakdown.interior_finishes.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of interior finish components contribution to mean loss | 9 x intensities |

loss.breakdown.plumbing_and_hvac.mean | array | Non-Negative | Plumbing and HVAC components contribution to mean loss | intensities |

loss.breakdown.plumbing_and_hvac.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of plumbing and HVAC components contribution to mean loss | 9 x intensities |

loss.breakdown.other_nonstructural.mean | array | Non-Negative | "Other non-structural" components contribution to mean loss | intensities |

loss.breakdown.other_nonstructural.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of "Other non-structural" components contribution to mean loss | 9 x intensities |

time.p58.serial.mean | array | Non-Negative | P58 serial repair time estimate | intensities |

time.p58.serial.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of FEMA P58 serial repair time estimate | 9 x intensities |

time.p58.parallel.mean | array | Non-Negative | P58 parallel repair time estimate | intensities |

time.p58.parallel.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of FEMA P58 parallel repair time estimate | 9 x intensities |

casualties.total.injury.mean | array | Non-Negative | Mean number of injuries | intensities |

casualties.total.injury.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of the number of injuries | 9 x intensities |

casualties.total.fatality.mean | array | Non-Negative | Mean number of fatalities | intensities |

casualties.total.fatality.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of the number of fatalities | 9 x intensities |

casualties.collapse.injury.mean | array | Non-Negative | Mean number of injuries from collapse | intensities |

casualties.collapse.injury.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of the number of injuries from collapse | 9 x intensities |

casualties.collapse.fatality.mean | array | Non-Negative | Mean number of fatalities from collapse | intensities |

casualties.collapse.fatality.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of the number of fatalities from collapse | 9 x intensities |

casualties.falling_hazard.injury.mean | array | Non-Negative | Mean number of injuries from falling hazards | intensities |

casualties.falling_hazard.injury.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of the number of injuries from falling hazards | 9 x intensities |

casualties.falling_hazard.fatality.mean | array | Non-Negative | Mean number of fatalities from falling hazards | intensities |

casualties.falling_hazard.fatality.fractiles | array | Non-Negative | 10%, 20%, ... 90% fractiles of the number of fatalities from falling hazards | 9 x intensities |

casualties.population.mean | number | Non-Negative | Mean building population | - |

casualties.population.max | number | Non-Negative | Max building population | - |

capacity.collapse.prob_per_intensity | array | Non-Negative | Probability of collapse | intensities |

capacity.residual.prob_per_intensity | array | Non-Negative | Probability of demolition due to excessive residual drift | intensities |

hazard.num_ims | number | Greater than 1 | Number of intensity levels run | intensities |

array | Non-Negative | Spectral acceleration at the fundamental period | ||

hazard.pga | array | Non-Negative | Peak ground acceleration | intensities |

string | - | Error ID number | - | |

error.msg | string | - | Error message | - |

*intensities = hazard.num_ims

# How to Submit Input Files and Receive Output Files

The SP3-Batch process is automated for ease-of-use. The process is simple - submit your input file to support@hbrisk.com (and typically copy other SP3 team members you are working with), then your analysis will be added to the queue, a confirmation e-mail will be send once your analysis has started, and then another email will be sent notifying that the outputs are available (with links to download the output files).