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

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

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

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
(e.g. tilt-up): Precast Concrete Walls

1

PC2a

PRESS Frame

45

RM1a

Single-Story Rigid-Wall Flexible Diaphragm
(e.g. tilt-up): Reinforced Masonry Walls

1

RM2a

Reinforced Masonry with Rigid Diaphragms

5

S4a

RC Shear Wall with Steel Frame

45

Building Occupancy Types

building.occupancy_id

Occupancy Type

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

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"

"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

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

hazard.sa

array

Non-Negative

Spectral acceleration at the fundamental period



hazard.pga

array

Non-Negative

Peak ground acceleration

intensities

error.id

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).