2. Determine scope
Second, consider which analyses you are interested in using the
package for. Determining the scope will inform the required spatial
resolution and extent of the input data, which is further documented in
vignette("prep-input-data").
Consult the flowchart and table to determine which functions you are
interested in using. Note that using fire_exp_validate()
has more requirements, see the details in the function
documentation.
Here are some common use case examples with suggested package functions and required input data.
Example: Compute exposure
The simplest use case of this package is computing the exposure metric. All of the other functions in this package require this as the first step. This can be computed for all scales of wildfire transmission.
Analysis functions:
fire_exp(): Compute exposure with default transmission distancesfire_exp_adjust(): Compute exposure with custom transmission distances
Visualization functions:
fire_exp_map_cont(): Visualize exposure mapped with a continuous scalefire_exp_map_class(): Visualize exposure mapped with a classified scalefire_exp_summary(): Visualize exposure classes in a summary table
Required input data:
- a Raster representing hazardous fuels in the area of interest
- if you are interested in more than one wildfire transmission distance, you will need one hazardous fuel raster for each transmission distance of interest
Optional input data:
- a raster representing the non-natural (e.g., the built environment) and non-burnable (e.g., open water, exposed rocks) landscape
Additional data for visualization:
- a polygon vector feature to mask the visualizations to an area of interest
Further suggested reading: Beverly et al. 2021, Beverly et al. 2010, FireSmart Canada 2018, Schmidt et al. 2024
Example workflow
This example code demonstrates how to use the package to compute
wildfire exposure at two different scales of wildfire transmission and
then export the results as a .tif file. For advice on preparing the
input data see vignette("prep-input-data").
# Load the fireexposuR library
library(fireexposuR)
# Load the terra library for reading/writing spatial data
library(terra)
# read raster of wildland fuels hazardous for long-range ember transmission
hazard_long <- rast("long_range_hazard.tif")
# read raster of wildland fuels hazardous for short-range ember transmission
hazard_short <- rast("short_range_hazard.tif")
# compute long-range ember exposure using the long-range hazard layer
exposure_long <- fire_exp(hazard_long, tdist = "l")
# compute short-range ember exposure using the short-range hazard layer
exposure_short <- fire_exp(hazard_short, tdist = "s")
# Export the results as a .tif file using terra
writeRaster(exposure_long, "exposure_long.tif")
writeRaster(exposure_short, "exposure_short.tif")Example: Assess directional exposure
Assessing the directional exposure vulnerability toward a value of interest is a landscape scale process. This assessment is used to identify potential pathways a wildfire could traverse toward a value in a systematic radial pattern.
Analysis functions:
fire_exp_dir(): Assess directional exposure
Visualization functions:
fire_exp_dir_plot(): Visualize the directional transects in a plotfire_exp_dir_map(): Visualize the directional transects in a mapfire_exp_dir_multi(): Visualize directional exposure trends for multiple values
Required input data:
- a Raster representing long-range exposure (e.g., from
fire_exp()) - point or simplified polygon vector feature of a value (or values) of interest
Further suggested reading: Beverly and Forbes 2023
Example workflow
This example code demonstrates how to use the package to assess directional vulnerability for a single point value and multiple point values. The example code also shows how to export the results as shapefiles.
# Load the fireexposuR library
library(fireexposuR)
# Load the terra library for reading/writing spatial data
library(terra)
# PLEASE NOTE: The following code is to demonstrate an example workflow. The
# referenced input data does not exist.
# read raster of wildland fuels hazardous for long-range ember transmission
hazard_long <- rast("long_range_hazard.tif")
# compute long-range ember exposure using the long-range hazard layer
exposure_long <- fire_exp(hazard_long, tdist = "l")
# read point feature vector of a single value location
point_value <- vect("point_value.shp")
# read point feature vector of value locations
multiple_values <- vect("multiple_values.shp")
# assess directional exposure for a single point
transects_point <- fire_exp_dir(exposure_long, point_value)
# export the transects for the point feature as a shapefile with terra
writeVector(transects_point, "transects_point.shp")
# loop through multiple values and export the results as shapefiles
for (i in seq_len(nrow(multiple_values))) {
dir_exp_point <- fire_exp_dir(exposure_long, multiple_values[i])
# set a file name based on the feature row number
file_name <- paste("transects_point_", i, ".shp", sep = "")
writeVector(dir_exp_point, file_name)
}Example: Conduct an exposure assessment for a local area
Assessing wildfire exposure for a local area can be conducted for
multiple scales of wildfire transmission. Some examples of where a
localized assessment would be useful are: a community, a neighbourhood,
or anywhere values are concentrated. For advice on preparing the input
data see vignette("prep-input-data").
Analysis functions:
fire_exp_extract(): Quickly appends the underlying exposure value as an attribute to a values layer
Visualization functions:
fire_exp_map_extract_vis(): Visualize classified exposure to values in a map or summary tablefire_exp_map_class(): Visualize exposure mapped with a classified scalefire_exp_map_summary(): Visualize exposure classes in a summary table
Required input data for analysis:
- a Raster representing exposure at the transmission distance of
interest (e.g., from
fire_exp()) - point or polygon features of the localized values (e.g., structures)
Additional data for visualization:
- The area of interest boundary (for visualizing exposure values within only the area of interest)
Further suggested reading: Beverly et al. 2010, FireSmart Canada 2018
Example workflow
This example code demonstrates how to use the package to compute
wildfire exposure at two different scales of wildfire transmission and
then visualize the results in R for a localized area of interest. For
advice on preparing the input data see
vignette("prep-input-data").
# Load the fireexposuR library
library(fireexposuR)
# Load the terra library for reading/writing spatial data
library(terra)
# PLEASE NOTE: The following code is to demonstrate an example workflow. The
# referenced input data does not exist.
# read raster of wildland fuels hazardous for long-range ember transmission
hazard_long <- rast("long_range_hazard.tif")
# read raster of wildland fuels hazardous for short-range ember transmission
hazard_short <- rast("short_range_hazard.tif")
# compute long-range ember exposure using the long-range hazard layer
exposure_long <- fire_exp(hazard_long, tdist = "l")
# compute short-range ember exposure using the short-range hazard layer
exposure_short <- fire_exp(hazard_short, tdist = "s")
# read polygon feature vector of an area of interest boundary
# (e.g., a built environment)
area_of_interest <- vect("area_of_interest.shp")
# read point feature vector of value locations
# (e.g., structures in a community)
multiple_values <- vect("multiple_values.shp")
# extract the underlying long-range ember exposure to values attributes
values_exposure_long <- fire_exp_extract(exposure_long, multiple_values)
# extract the underlying short-range ember exposure to values attributes
values_exposure_short <- fire_exp_extract(exposure_short, multiple_values)
# Visualize short-range ember exposure classes in the aoi with a summary table
fire_exp_summary(exposure_long, area_of_interest, classify = "local")
# Visualize long-range ember exposure classes in the aoi with a map
fire_exp_map_class(exposure_long, area_of_interest, classify = "local")
# Visualize long-range ember exposure classes to values in summary table
fire_exp_extract_vis(values_exposure_long, classify = "local")
# Visualize long-range ember exposure classes to values in map
fire_exp_extract_vis(values_exposure_long, classify = "local", map = TRUE)
# Repeat the visualizations for short-range ember exposure
fire_exp_summary(exposure_short, area_of_interest, classify = "local")
fire_exp_map_class(exposure_short, area_of_interest, classify = "local")
fire_exp_extract_vis(values_exposure_short, classify = "local")
fire_exp_extract_vis(values_exposure_short, classify = "local", map = TRUE)Advanced Example: Validate the exposure metric in a study area
This example demonstrates how to use the fireexposuR package to validate the wildfire exposure metric in an area of interest with the methods used by Beverly et al. 2021. The assessment samples and compares the distribution of classified exposure values across the study area as a whole and across areas that have burned.
Analysis function:
fire_exp_validate(): Validates the exposure metric using observed fire perimeters
Visualization function:
fire_exp_validate_plot(): generates a standardized plot to view the outputs fromfire_exp_validate()
Required input data:
- a Raster representing hazardous fuels in the area of interest for a time in the past
- a vector of polygons of areas that have been burned since the time of the hazardous fuel raster
Optional input data:
- a polygon vector feature to mask the visualizations to an area of interest
Further suggested reading: Beverly et al. 2021, Schmidt et al. 2024
Example workflow
This example code demonstrates how to use the package to validate wildfire exposure. Three different potential validation scenarios are presented.
In the first example, a validation is done to confirm if fire burns preferentially in areas of high exposure for the area of interest. This is recommended if you are applying wildfire exposure to a geographic area where land cover differs from where the metric has already been validated.
# Load the fireexposuR library
library(fireexposuR)
# Load the terra library for reading/writing spatial data
library(terra)
# PLEASE NOTE: The following code is to demonstrate an example workflow. The
# referenced input data does not exist.
# read long-range ember hazard raster
hazard <- rast("hazard.tif")
# read non-burnable landscape raster
no_burn <- rast("no_burn.tif")
# compute long-range ember exposure
exposure <- fire_exp(hazard, tdist = "l", no_burn = no_burn)
# read the fire perimeters with terra
fires <- vect("fires.shp")
# generate validation table, and then plot the results
output <- fire_exp_validate(exposure, fires)
fire_exp_validate_plot(output)In the second example, the exposure metric is validated for two
differing transmission distance definitions. This is highly recommended
if the function fire_exp_adjust() is used to set an
alternative transmission distance.
# Load the fireexposuR library
library(fireexposuR)
# Load the terra library for reading/writing spatial data
library(terra)
# PLEASE NOTE: The following code is to demonstrate an example workflow. The
# referenced input data does not exist.
# read long-range ember hazard raster
hazard <- rast("hazard.tif")
# read non-burnable landscape raster
no_burn <- rast("no_burn.tif")
# compute long-range ember exposure for default transmission distance
exposure_a <- fire_exp(hazard, tdist = "l", no_burn = no_burn)
# compute long-range ember exposure for a custom transmission distance
exposure_b <- fire_exp(hazard, tdist = 800, no_burn = no_burn)
# read the fire perimeters with terra
fires <- vect("fires.shp")
# validation tables for both options
output_a <- fire_exp_validate(exposure_a, fires)
output_b <- fire_exp_validate(exposure_b, fires)In the third example, the exposure metric is validated for two differing hazardous fuel rasters. The hazardous fuel rasters could differ in many ways. Some examples of why you may want to validate different hazard fuel rasters could include:
- Which land cover types are being defined as hazardous fuels
- How land cover types are being defined as hazardous fuels (e.g., binary (Beverly et al. 2021) or scaled (Schmidt et al. 2024))
- Land cover information coming from different sources (e.g., see Forbes and Beverly 2024)
# Load the fireexposuR library
library(fireexposuR)
# Load the terra library for reading/writing spatial data
library(terra)
# PLEASE NOTE: The following code is to demonstrate an example workflow. The
# referenced input data does not exist.
# read long-range ember hazard raster: option A
hazard_a <- rast("hazard_a.tif")
# read non-burnable landscape raster: option A
no_burn_a <- rast("no_burn_a.tif")
# read long-range ember hazard raster: option B
hazard_b <- rast("hazard_b.tif")
# read non-burnable landscape raster: option B
no_burn_b <- rast("no_burn_b.tif")
# compute long-range ember exposure for option A
exposure_a <- fire_exp(hazard_a, tdist = "l", no_burn = no_burn_a)
# compute long-range ember exposure for option A
exposure_b <- fire_exp(hazard_b, tdist = "l", no_burn = no_burn_b)
# read the fire perimeters with terra
fires <- vect("fires.shp")
# validation tables for both options
output_a <- fire_exp_validate(exposure_a, fires)
output_b <- fire_exp_validate(exposure_b, fires)