This vignette first provides an overview of Damage Functions in USA Federal Emergency Management Agency (FEMA)'s HAZUS software followed by some examples on how to obtain and plot the flood-specific Damage Functions from HAZUS using the hazus package.
The HAZUS software package contains models and data for estimating potential losses from natural disasters such as floods, earthquakes and hurricanes. Within HAZUS, Damage Functions, also known as Vulnerability Functions, are used to estimate financial losses to a building or a structure (and also its contents and inventory) for a given severity of the hazard. For instance, these DFs quantify the damage from hurricanes for a given wind speed, or the damage from flooding of a certain depth. Damage is typically specified as a percentage of the total value of the property. Several thousand DFs have been developed by HAZUS from claims data and engineering analyses and these serve as a benchmark in catastrophe modeling, both in academia and industry.
Some drawbacks of HAZUS DFs:
The goal of the hazus package is to address the above drawbacks. The hazus package comes with DFs and also appropriate documentation. Moreover, functionality is provided to analyze and visualize these DFs.
After installing the package, load the package along with reshape2 (for data extraction) and ggplot2 for analysis and graphics.
library(hazus)
library(reshape2)
library(ggplot2)
hazus comes with a number of datasets on flood-specific DFs and also the function extract_hazus_functions to extract and subsequently visualize these DFs.
data(haz_fl_dept) # depth-based DFs
data(haz_fl_velo) # velocity and depth-based DFs
data(haz_fl_agri) # agriculture DFs
data(haz_fl_bridge) # DFs for bridges
data(haz_fl_depr) # depreciation functions
data(haz_fl_occ) # occupancy description table
These datasets could also be obtained using extract_hazus_functions by setting long_format argument to FALSE and the appropriate func_typevalue. As mentioned in the drawbacks above, the raw functions from HAZUS are not readily suitable for visualization.
fl_dept <- extract_hazus_functions(long_format = FALSE)
dim(fl_dept)
#> [1] 1260 51
The default invocation of extract_hazus_functions fetches all the depth-based DFs in the “long” format.
fl_dept <- extract_hazus_functions()
dim(fl_dept)
#> [1] 35511 10
head(fl_dept)
#> Occupancy DmgFnId Source
#> 1 RES1 183 USACE - Wilmington
#> 2 RES1 184 USACE - Wilmington
#> 3 RES1 105 FIA
#> 4 RES1 106 FIA (MOD.)
#> 5 RES1 115 FIA
#> 6 RES1 185 USACE - Wilmington
#> Description Source_Table
#> 1 two story, Pile foundation, structure flBldgStructDmgFn
#> 2 two story, Structure flBldgStructDmgFn
#> 3 one floor, no basement, Structure, A-Zone flBldgStructDmgFn
#> 4 one floor, w/ basement, Structure, A-Zone flBldgStructDmgFn
#> 5 two floors, no basement, Structure, V-Zone flBldgStructDmgFn
#> 6 two story w/ 1/2 living area below, Structure flBldgStructDmgFn
#> Occupy_Class Cover_Class Comment damage depth
#> 1 RES Bldg 3 -4
#> 2 RES Bldg 0 -4
#> 3 RES Bldg 0 -4
#> 4 RES Bldg 7 -4
#> 5 RES Bldg 0 -4
#> 6 RES Bldg 0 -4
The occupancy description table provides information on occupancy classes and sub-classes.
head(haz_fl_occ)
#> Occupy_Class Occupancy Occ_Desc1 Occ_Desc2
#> 1 RES RES1 Residential Single Family Dwelling
#> 2 RES RES2 Residential Mobile Home
#> 3 RES RES3A Residential Multi Family Dwelling Duplex
#> 4 RES RES3B Residential Multi Family Dwelling 3-4 Units
#> 5 RES RES3C Residential Multi Family Dwelling 5-9 Units
#> 6 RES RES3D Residential Multi Family Dwelling 10-19 Units
#> SIC_code
#> 1
#> 2
#> 3
#> 4
#> 5
#> 6
levels(as.factor(haz_fl_occ$Occupancy))
#> [1] "AGR1" "COM1" "COM10" "COM2" "COM3" "COM4" "COM5" "COM6"
#> [9] "COM7" "COM8" "COM9" "EDU1" "EDU2" "GOV1" "GOV2" "IND1"
#> [17] "IND2" "IND3" "IND4" "IND5" "IND6" "REL1" "RES1" "RES2"
#> [25] "RES3A" "RES3B" "RES3C" "RES3D" "RES3E" "RES3F" "RES4" "RES5"
#> [33] "RES6"
table(haz_fl_occ$Occupy_Class)
#>
#> AGR COM EDU GOV IND REL RES
#> 1 10 2 2 6 1 11
Velocity-based DFs are only specified for 1 to 3 stories in the HAZUS Technical Manual.
fl_velo <- extract_hazus_functions(func_type = "velocity")
str(fl_velo)
#> 'data.frame': 468 obs. of 4 variables:
#> $ struc_type: Factor w/ 4 levels "Concrete","Masonry",..: 4 4 4 4 4 4 4 4 4 4 ...
#> $ num_story : Factor w/ 3 levels "1","2","3": 1 1 1 1 1 1 1 1 1 1 ...
#> $ vel : num 0 5.34 5.39 5.49 5.59 5.69 5.79 5.89 5.99 6.09 ...
#> $ dep : num 10 10 9.81 9.46 9.13 ...
Agriculture DFs are based on the calendar day of the year.
fl_agri <- extract_hazus_functions(func_type = "ag")
str(fl_agri)
#> 'data.frame': 36500 obs. of 5 variables:
#> $ Crop : chr "Alfalfa Hay" "Alfalfa Hay" "Alfalfa Hay" "Alfalfa Hay" ...
#> $ FunctionSource: chr "USACE" "USACE" "USACE" "USACE" ...
#> $ JulianDay : int 1 2 3 4 5 6 7 8 9 10 ...
#> $ loss_type : Factor w/ 5 levels "PctCropLoss",..: 1 1 1 1 1 1 1 1 1 1 ...
#> $ damage : int 0 0 0 0 0 0 0 0 0 0 ...
DFs for bridges are based on the return period of the flood.
fl_bridge <- extract_hazus_functions(func_type = "bridge")
str(fl_bridge)
#> 'data.frame': 328 obs. of 6 variables:
#> $ BridgeDmgFnId: num 1 2 3 4 5 6 7 8 1 2 ...
#> $ Occupancy : chr "ID_U" "ID_2" "ID_3" "ID_U" ...
#> $ Source : chr "HazusDflt" "HazusDflt" "HazusDflt" "HazusDflt" ...
#> $ Description : chr "Single Span" "Single Span" "Single Span" "Continuous Span" ...
#> $ ret_period : int 0 0 0 0 0 0 0 0 25 25 ...
#> $ damage : num 0 0 0 0 0 0 0 0 0.0125 0.005 ...
Depreciation by age of a structure is based on occupancy type.
fl_depr <- extract_hazus_functions(func_type = "deprec")
str(fl_depr)
#> 'data.frame': 3535 obs. of 3 variables:
#> $ Age : int 0 1 2 3 4 5 6 7 8 9 ...
#> $ Occupancy: Factor w/ 35 levels "RES1Good","RES1Average",..: 1 1 1 1 1 1 1 1 1 1 ...
#> $ deprec : int 0 0 1 1 2 3 4 5 5 6 ...
Following are some graphics using the data obtained from the hazus package.
Depth-based DFs for single-story building coverage.
gfx_data <- subset(fl_dept, grepl("one floor", Description) & Cover_Class == "Bldg")
# clean up description
gfx_data$Description <- paste(gfx_data$DmgFnId, gfx_data$Description)
gfx_line <- ggplot(data = gfx_data, aes(x = depth, y = damage))
gfx_line <- gfx_line + geom_line(aes(colour = Description))
gfx_line <- gfx_line + ylab("Damage (%)") + xlab("Flood Depth (ft)")
print(gfx_line)
Velocity-based DFs for four structure types by number of stories.
gfx_line <- ggplot(data = fl_velo, aes(x = vel, y = dep))
gfx_line <- gfx_line + geom_line(aes(colour = num_story))
gfx_line <- gfx_line + facet_wrap(~struc_type, scales = "fixed")
gfx_line <- gfx_line + ylab("Flood Depth (ft)") + xlab("Flood Velocity (ft/s)")
print(gfx_line)
Agriculture DFs for select crops.
gfx_data <- subset(fl_agri, loss_type == "PctCropLoss" & Crop %in%
c("Tomato", "Cotton", "Wheat"))
gfx_line <- ggplot(data = gfx_data, aes(x = JulianDay, y = damage))
gfx_line <- gfx_line + geom_line(aes(colour = Crop))
gfx_line <- gfx_line + ylab("Damage (fraction)") + xlab("Day of Year")
print(gfx_line)
DFs for bridges.
gfx_data <- fl_bridge
gfx_data$Description <- paste(gfx_data$Occupancy, gfx_data$Description)
gfx_line <- ggplot(data = gfx_data, aes(x = ret_period, y = damage))
gfx_line <- gfx_line + geom_line(aes(colour = Description))
gfx_line <- gfx_line + ylab("Damage (%)") + xlab("Flood Return Period (years)")
print(gfx_line)
Depreciation functions for select occupancy types.
gfx_data <- fl_depr[grepl("1", fl_depr$Occupancy), ]
gfx_line <- ggplot(data = gfx_data, aes(x = Age, y = deprec))
gfx_line <- gfx_line + geom_line(aes(colour = Occupancy))
gfx_line <- gfx_line + ylab("Depreciation (%)") + xlab("Age (years)")
print(gfx_line)
Currently the hazus package has only flood-specific DFs. Hurricane and earthquake DFs would be included in the future. Also, a number of utilities of potential use in flood risk modeling and other catastrophe modeling are available from HAZUS. Such utilities could also be included in future versions of the hazus package.