Example #1

Running FrEDI with Default Parameters

FrEDI is commonly used to project the annual, climate-driven physical and economic impacts associated with user-defined trajectories of U.S. temperature change (relative to a 1985-2005 baseline), population, and GDP.

This vignette provides a simple example of how to run and analyze data from FrEDI’s default scenario.

This example script:

Installs the FrEDI R package from GitHub
Sets FrEDI input and run parameters.
Runs FrEDI with inputs specified in Step 2
Shows example types of analyses using FrEDI output data.

For more information about FrEDI, see the About page and FrEDI Technical Documentation

Step 1. Install `FrEDI` R package

When installing for the first time, see Installing & Running FrEDI page.

Load package

require(FrEDI)

After successfully installing FrEDI, documentation for FrEDI functions can be accessed in the same way as for other R packages.

For an overview of FrEDI’s user-defined functions, type library(help="FrEDI") into an R console (this command will show documentation for FrEDI even if the package is not installed).

For documentation for a specific function, type help("*functionName*", package="FrEDI") into an R console, where *functionName* is the name of one of the functions in FrEDI (e.g., help("aggregate_impacts", package="FrEDI")). Alternatively, use the syntax ?FrEDI::*functionName* (e.g., ?FrEDI::run_fredi()).

If FrEDI has been installed, users can also search for function-specific documentation in RStudio through the Help window. Move the focus to the Help window using the keyboard shortcut Ctrl+3 or toggle the search field in Help using Ctrl+Alt+F1. Documentation for each function includes examples.

Step 2. Set `FrEDI` Runtime parameters

First, use this chunk to specify & format input projections. Either provide paths to specific files, or set to NULL to use default projections for each variable

Use this chunk to specify the input trajectories (temperature, population, GDP) and runtime parameters for FrEDI.

### To run FrEDI for more than one scenario, the code below can be
### adapted into a loop to format the inputs for each scenario. 

###***********************************************
### 1. Specify & Format Input Trajectories (temperature, population, U.S. GDP)

### Input Files
### * GDP
### - Description: csv file with time series of U.S. Gross Domestic Product (units: 2015$, values: >= 0) 
### - data must start in 2010 or earlier
### - Must have columns "year", "gdp_usd"
### - If NULL - use default GDP trajectory
gdpInputFile <- NULL

### * Population
### - Description: csv file with time series of annual U.S. population (values >= 0) 
### - Data must start in 2010 or earlier
### - Must have columns "year" and "pop"; other columns may be required, depending on the popArea argument flag
### - If NULL - use default population trajectory (from ICLUS)
popInputFile <- NULL

### * Temperature
### - Description: csv file with time series of temperature relative to 1986-2005 average 
### - (units: degC, values: >=0)
### - data must start in 2000 or earlier and can be global or CONUS
### - If global --> must convert to CONUS temperature using the import_inputs() helper function
### - Must have columns "year", "temp_C"
tempInputFile <- NULL

### * SLR
### - Description: csv file with time series of global mean sea level rise relative to 2000
### - (units: cm, values: >= 0 and <= 250)
### - data must start in 2000 or earlier
### - Must have columns "year", "slr_cm"
### - If NULL - slr is calculated from the input temperature trajectory
slrInputFile <- NULL 

### Input Trajectory Parameters
### * Population area flag
### - Description: Use this to specify the geographical scale of the population data
### - Options: "state","regional","national".
### - For more information, see `?import_inputs()` for more information
popAreaflag  <- "state"   

### * Temperature type flag
### - Description: Use this to specify whether the input temperature is global or CONUS
### - import_inputs() will convert to global to CONUS temperature
### - Options: global (input is global T), conus (input is CONUS T)
### - Default: defaults to "conus"
temptypeflag <- "global" 

### Use the import_inputs() helper function to format the input trajectories for use in FrEDI
inputs_list <- import_inputs(
  inputsList=list(
    temp = tempInputFile,
    slr  = slrInputFile,
    gdp  = gdpInputFile,
    pop  = popInputFile
  ),
  temptype = temptypeflag,
  popArea  = popAreaflag
) ### End import_inputs
inputs_list |> glimpse()

##  list()

If no input files are specified, run_fredi() will use default temperature, U.S. population, and GDP projections. In this case, run_fredi() will calculate annual projected sea level rise based on the default temperature change.

Default population scenarios are based on UN Median Population projection (United Nations, 2015) and EPA’s ICLUSv2 model (Bierwagen et al., 2010; EPA 2017), and GDP from the EPPA version 6 model (Chen et al., 2015). Default temperature projections are from the GCAM reference scenario. Current default projections of U.S. GDP, national population, and U.S. temperature in the year 2090 are 70 trillion (2015USD), 438 million, and 3.4°C respectively.

Next, set FrEDI runtime parameters

### Thru2300 Flag
### - Purpose: Specify whether to run FrEDI through 2100 (default) or extend to 2300
### - Default: FALSE (will run to 2100)
thru2300Flag <-  FALSE

### Sector list flag
### - Purpose: Specify the vector of sectors for which to calculate results
### - Default: Report output for all sectors
### - See FrEDI::get_sectorInfo() for list of all sectors
sectorListFlag <- NULL  

### Aggregation level flag
### - Purpose: Specify the desired level of results aggregation. For example,
###   to report national total results across all underlying climate-model 
###   damage functions, set the flag to c("national","modelaverage")
### - Options: at least one from c("national", "modelaverage", "impactyear",
###   "impacttype", "all"), or "none". 
### - Default: c("national", "modelaverage", "impactyear","impacttype")
aggLevelFlag <- c("national", "modelaverage", "impactyear")

### Maximum year flag
### - Purpose: Specify the last year of the analysis 
### - Default: 2100
maxYearFlag <- 2100

### Elasticity flag
### - Purpose: Specify the income elasticity used to adjust the Value of a
###   Statistical Life (VSL)
### Options: any numeric value
### Default: 1
elasticityFlag <- 1   

### Output list flag
### - Purpose: Specify whether to return input arguments in addition to results data frame
### - Options: TRUE/FALSE. 
### - Default: FALSE
outputListFlag <- FALSE

### All columns flag
### - Purpose: Specify whether to include physical and economic multipliers (used in testing)
### - Options: TRUE/FALSE. 
### - Default: FALSE
allColsFlag <- TRUE

### Silent flag
### - Purpose: Specify the level of messaging to the user
### - Options: TRUE/FALSE. 
### - Default: TRUE
silentFlag <- TRUE

Step 3. Run `FrEDI`

Run FrEDI using the main run_fredi() function

Default parameter options are used for any parameters that are not specified in run_fredi().

### Run FrEDI using inputs and parameters set in Step #2
output_df <- run_fredi(
  inputsList = inputs_list, 
  sectorList = sectorListFlag,
  # sectorList = "Asphalt Roads",
  aggLevels  = aggLevelFlag,
  elasticity = elasticityFlag,
  maxYear    = maxYearFlag,
  thru2300   = thru2300Flag,
  outputList = outputListFlag,
  allCols    = allColsFlag,
  silent     = silentFlag
) ### End run_fredi

## Checking scenarios...

## Calculating impacts...

##      Formatting initial results...

##      Calculating temperature-driven scaled impacts...

##      Calculating SLR-driven scaled impacts...

## Formatting results...

## Aggregating impacts...

## 
## Finished.

# output_df |> glimpse()
output_df |> pull(model) |> unique()

##  [1] "Average"       "CCSM4"         "CanESM2"       "GCM Ensemble" 
##  [5] "GFDL-CM3"      "GISS-E2-R"     "HadGEM2-ES"    "MIROC5"       
##  [9] "MRI-CGCM3"     "Interpolation"

### Filter to specific year
c_years     <-  c(2100)

### Filter to specific values:
### - Filter to primary sectors
### - Filter to average models/SLR scenario interpolations
### - Filter to specified years
df_primary <- output_df |>
  filter(sectorprimary == 1, includeaggregate >= 1) |>
  filter(model %in% c("Average", "Interpolation"))|>
  filter(year %in% c_years)

### Aggregate across impact types for each sector, calculate billions and round values to nearest dollar
### - Convert to billions of dollars
### - Round values to nearest dollar
df_sumTypes <- df_primary |> 
  aggregate_impacts(
    aggLevels = c("impacttype"), 
    columns   = c("annual_impacts")
  )

### Option: write output
### Write Full Dataframe to CSV (or feather)
# write.csv(output_df, './output/example_output.csv')

### First five lines of output dataframe
# output_df[1:5,]

Step 4. Analyze `FrEDI`

The following chunks provide three examples options for how to analyze the raw output dataframe from FrEDI::run_fredi()

Disclaimer: These results only provide an illustrative example and should NOT be used for further analysis.

Example 1

Extract national average of economic damages (in billions of dollars in 2015$) for all FrEDI sectors for a specified year

The output of this chunk includes a snapshot of a subset of the resulting dataframe. * Note: Use the sectorprimary == 1 and includeaggregate >= 1 flags to filter the FrEDI dataframe for impacts from only the default impact sectors and variants. For recommendations on aggregating impacts across sectors, see the FrEDI Technical Documentation (Chapter 2) and FrEDI::run_fredi() documentation.

### Specify groups
groups1     <- c("sector", "region", "year")
sumCol1     <- c("annual_impacts")
select1     <- groups1 |> c(sumCol1)

### Filter to specific values:
### - Filter for national aggregate results averaged across all GCMs
### - Filter to specified years
### Select specific columns
df_filter1  <- df_sumTypes |> 
  filter(region == "National Total") |>
  select(all_of(select1)) |>
  rename("billions_2015$" = annual_impacts) |>
  mutate(`billions_2015$` = `billions_2015$` / 1e9) |>
  mutate_at(c("billions_2015$"), round, 2)

### Display first 10 sectors
df_filter1[1:10,] |> 
  kable(caption = "Example *Subset* of 2100 Annual National Sectoral Climate-Driven Impacts") |>
  kable_styling(font_size = 12, full_width = F)

Example *Subset* of 2100 Annual National Sectoral Climate-Driven Impacts
sector	region	year	billions_2015$
ATS Temperature-Related Mortality	National Total	2100	2766.90
CIL Agriculture	National Total	2100	8.85
CIL Crime	National Total	2100	1.69
Climate-Driven Changes in Air Quality	National Total	2100	291.18
Coastal Properties	National Total	2100	14.39
Electricity Demand and Supply	National Total	2100	18.95
Electricity Transmission and Distribution	National Total	2100	14.57
Inland Flooding	National Total	2100	1.28
Labor	National Total	2100	55.51
Marine Fisheries	National Total	2100	-0.03

Example 2

Extract national average of physical damages for all FrEDI sectors that include physical impacts, for a specified year:

The 0utput of this chunk includes a snapshot of a subset of the resulting dataframe.
Note: Use the sectorprimary == 1 and includeaggregate >= 1 flags to filter the FrEDI dataframe for impacts from only the default impact sectors and variants. For recommendations on aggregating impacts across sectors, see the FrEDI Technical Documentation (Chapter 2) and FrEDI::run_fredi() documentation.

### Specify groups
groups2     <- c("sector", "impactType", "physicalmeasure", "physical_impacts", "region", "year")
sumCol2     <- c("physical_impacts")
select2     <- groups2  |> c(sumCol2)

### Filter to specific values:
### - Filter for national aggregate results averaged across all GCMs
### - Filter to specified years
### Select specific columns
df_filter2 <- df_primary |>
  filter(region == "National Total") |>
  filter(!(is.na(physicalmeasure))) |>
  mutate_at(c(sumCol2), round, 0) |>
  select(all_of(select2))

### Display first 10 rows
df_filter2[c(1, 6:9, 14),] |> 
  kable(caption = "Example *Subset* of 2100 Annual National Sectoral Climate-Driven Physical Impacts") |>
  kable_styling(font_size = 12, full_width = F)

Example *Subset* of 2100 Annual National Sectoral Climate-Driven Physical Impacts
sector	impactType	physicalmeasure	physical_impacts	region	year
ATS Temperature-Related Mortality	N/A	Premature Mortality	83858	National Total	2100
CIL Crime	Property	Crimes	3264	National Total	2100
CIL Crime	Violent	Crimes	5713	National Total	2100
Climate-Driven Changes in Air Quality	Ozone	Premature Mortality	2108	National Total	2100
Climate-Driven Changes in Air Quality	PM2.5	Premature Mortality	6717	National Total	2100
Labor	N/A	Lost Work Hours	659458039	National Total	2100

Example 3

Extract state economic impacts for FrEDI sectors for a specified year:

The output of this chunk includes a snapshot of a subset of the resulting dataframe.
Note: Use the sectorprimary == 1 and includeaggregate >= 1 flags to filter the FrEDI dataframe for impacts from only the default impact sectors and variants. For recommendations on aggregating impacts across sectors, see the FrEDI Technical Documentation (Chapter 2) and FrEDI::run_fredi() documentation.

### Specify groups
groups3     <- c("sector", "state", "year")
joinCols3   <- c("state", "year")
sumCol3     <- c("annual_impacts")
select3     <- groups3  |> c(sumCol3)

### Filter to specific values:
### - Filter for national aggregate results averaged across all GCMs
### - Filter to specified years
### Select specific columns
df_filter3 <- df_sumTypes |>
  filter(!(region == "National Total")) |>
  group_by_at(c(groups3)) |>
  summarize_at(c(sumCol3), sum, na.rm=T) |> ungroup() |> 
  ###  SEE RECOMMENDATIONS FOR AGGREGATION in FrEDI TECHNICAL DOCUMENTATION ##
  (function(df0){
    df1 <- df0 |> 
      filter(sector == "Suicide") |> 
      select(-c("sector")) |>
      rename(impacts_suicide=annual_impacts)
    df0 <- df0 |> left_join(df1, by=joinCols3)
    df0 <- df0 |> mutate(impacts_suicide = case_when(impacts_suicide |> is.na() ~ 0, .default=impacts_suicide))
    df0 <- df0 |> mutate(annual_impacts = case_when(
      sector == "ATS Temperature-Related Mortality" ~ annual_impacts - impacts_suicide,
      .default = annual_impacts
    ))
    df0 <- df0 |> select(-c("impacts_suicide"))
    return(df0)
  })() |>
  group_by_at(c(joinCols3)) |>
  summarize_at(c(sumCol3), sum, na.rm=T) |> ungroup() |> 
  rename("billions_2015$" = annual_impacts) |>
  mutate(`billions_2015$` = `billions_2015$` / 1e9) |>
  mutate_at(c("billions_2015$"), round, 2); df_filter3 |> glimpse()

## Rows: 49
## Columns: 3
## $ state            <chr> "Alabama", "Arizona", "Arkansas", "California", "Colo…
## $ year             <dbl> 2100, 2100, 2100, 2100, 2100, 2100, 2100, 2100, 2100,…
## $ `billions_2015$` <dbl> 64.43, 90.11, 36.59, 405.53, 70.17, 28.85, 9.32, 6.80…

### Display first 10 rows
df_filter3[1:10,] |> 
  kable(caption = "Example 2100 Annual Climate-Driven Damages, by State") |>
  kable_styling(font_size = 12, full_width = F)

Example 2100 Annual Climate-Driven Damages, by State
state	year	billions_2015$
Alabama	2100	64.43
Arizona	2100	90.11
Arkansas	2100	36.59
California	2100	405.53
Colorado	2100	70.17
Connecticut	2100	28.85
Delaware	2100	9.32
District of Columbia	2100	6.80
Florida	2100	218.86
Georgia	2100	160.06

Please contact the FrEDI developers with additional questions.

November 2024

Running FrEDI with Default Parameters

Step 1. Install FrEDI R package

Step 2. Set FrEDI Runtime parameters

Step 3. Run FrEDI