Import custom scenarios for temperature, global mean sea level rise (GMSL), population, and GDP from user-specified file names

This function enables users to import data on custom scenarios for use with run_fredi(). Users specify path names to CSV files containing temperature, global mean sea level rise (GMSL), gross domestic product (GDP), and state population scenarios. import_inputs() reads in and format any specified files as data frames and returns a list of data frames for imported scenarios.

Usage

import_inputs(
  tempfile = NULL,
  slrfile = NULL,
  gdpfile = NULL,
  popfile = NULL,
  temptype = "conus",
  popArea = "state"
)

Arguments

tempfile=NULL

A character string indicating the location of a CSV file containing a custom temperature scenario. The first column in the CSV should be named "year" and contain years associated with the temperature estimates; the second column (named "temp_C") should contain values for temperatures (i.e., degrees of warming relative to a baseline year of 1995), in degrees Celsius. The temperature scenario must start in 2000 or earlier and end at or after the maximum model run year (e.g., as specified by the maxYear argument to run_fredi()).

slrfile=NULL

A character string indicating the location of a CSV file containing a custom sea level rise scenario. The first column in the CSV should be named "year" and contain years associated with the sea level rise estimates; second column should be named "slr_cm" and contain values for global mean sea level rise (GMSL), in centimeters, above a baseline year of 2000. The SLR scenario must start in 2000 or earlier and end at or after the maximum model run year (e.g., as specified by the maxYear argument to run_fredi()).

gdpfile=NULL

A character string indicating the location of a CSV file containing a custom scenario for U.S. gross domestic product (GDP). The first column in the CSV should be named "year" and contains years associated with the GDP estimates; the second column (named "gdp_usd") should contain values for U.S. GDP in 2015 U.S. dollars (2015$ USD). The GDP scenario must start in 2010 or earlier and end at or after the maximum model run year (e.g., as specified by the maxYear argument to run_fredi()). Values for GDP in column "gdp_usd" must be greater than or equal to zero.

popfile=NULL

A character string indicating the location of a CSV file containing a custom population scenario for states and NCA regions. The first column should be named "year" and contain years in the interval 2010 to 2300. The second column should be called "pop" and contain population values. Whether a third column is required depends on the geographical scale of the data, as specified by the popArea argument (for more information, see the popArea argument, below.

• If popArea = "state", the third column should be called "state" and contain the name of the state associated with each population estimate in a given year. If popArea = "regional", the third column should be called "region" and contain the NCA Region label associated with each population estimate in a given year. If popArea = "national", only the year and pop columns are required.

• If popArea = "state", the file must contain estimates for all CONUS states -- i.e., all states except Alaska and Hawaii must be present in the input file (estimates for Alaska and Hawaii are optional). If popArea = "regional", the file must contain estimates for all seven NCA regions.

• The population scenario must start in 2010 or earlier and end at or after the maximum model run year (e.g., as specified by the maxYear argument to run_fredi()). Values for population in column "pop" must be greater than or equal to zero.

temptype="conus"

A character string indicating whether the temperature values in the temperature input file (as specified by tempfile) represent temperature changes, in degrees Celsius, at the global level (temptype = "global") or for the contiguous U.S. (CONUS) only (temptype = "conus", default).

popArea="state"

A character string indicating the geographical scale of population inputs (as specified by popfile). Specify one of: "state", for state-level population (default); "conus", for the contiguous U.S. (CONUS) only (i.e., national totals, but excluding Alaska and Hawaii); or "national", for national totals (CONUS population, including Alaska and Hawaii).

Value

import_inputs() returns a list of named elements containing data frames with custom scenarios for temperature, GMSL, GDP, and regional population, respectively:

List Index	Description
tempInput	Data frame containing a custom temperature scenario imported from the CSV file specified by tempfile, with missing values removed. tempInput has two columns with names "year" and "temp_C", containing the year and CONUS temperatures in degrees Celsius, respectively.
slrInput	Data frame containing a custom GMSL scenario imported from the CSV file specified by slrfile, with missing values removed. slrInput has two columns with names "year", and "slr_cm", containing the year and global mean sea level rise (GMSL) in centimeters, respectively.
gdpInput	Data frame containing a custom GDP scenario imported from the CSV file specified by gdpfile, with missing values removed. gdpInput has two columns with names "year", and "gdp_usd", containing the year and the national GDP, respectively.
popInput	Data frame containing a custom temperature scenario imported from the CSV file specified by popfile, with missing values removed. popInput has three columns with names "year", "region", "state", "postal", and "state_pop", containing the year, the NCA region name, and the state, the postal code abbreviation (e.g., postal = "ME" for state = "Maine"), and the state population, respectively.

Details

This function enables users to import data on custom scenarios for use with temperature binning. Users specify path names to CSV files containing temperature, global mean sea level rise (GMSL), population, and gross domestic product (GDP) scenarios (tempfile, slrfile, gdpfile, and popfile, respectively). import_inputs() reads in and formats any specified files as data frames and returns a list of data frames for imported scenarios.

The CSV files should contain estimates aligned with the requirements of the run_fredi() or ``

• Temperature Scenario. The file specified by tempfile must have two columns -- "year" and "temp_C" -- respectively containing the years associated with the temperature estimates and the temperatures (i.e., degrees of warming) in degrees Celsius relative to a baseline year of 1995 (i.e., the central year of a 1986-2005 reference period).

  • If values in "temp_C" have global rather than CONUS-specific temperatures, users should specify temptype = "global" when running import_inputs(), and import_inputs() will convert the temperatures to CONUS using convertTemps (with argument from = "global").

  • Temperature inputs to run_fredi() must have at least one non-missing value in 2000 or earlier and at least one non-missing value in or after the final analysis year (as specified by the run_fredi() maxYear argument).

• SLR Scenario. The file specified by slrfile must have two columns -- "year" and "slr_cm" -- respectively containing the years associated with the GMSL estimates and GMSL estimates, in centimeters, above a 2000 baseline year.

  • GMSL heights must be greater than or equal to zero.

  • The SLR scenario must have at least one non-missing value in 2000 or earlier and at least one non-missing value in or after the final analysis year (as specified by the run_fredi() maxYear argument).

• GDP Scenario. The file specified by gdpfile must have two columns -- "year" and "gdp_usd" -- respectively containing the years associated with the GDP estimates and the estimates for U.S. GDP, in 2015$.

  • GDP values must be greater than or equal to zero.

  • The GDP scenario must have at least one non-missing value in 2010 or earlier and at least one non-missing value in or after the final analysis year (as specified by the run_fredi() maxYear argument).

• Population Scenario. The file specified by popfile population must have at least two columns -- "year" and "pop" -- respectively containing the years associated with the population estimates and the population estimates. requires state-level population values. Whether a third column is required depends on the geographical scale of the data, as specified by the popArea argument.

  • If popArea = "state", the third column should be called "state" and contain the name of the state associated with each population estimate in a given year. If popArea = "regional", the third column should be called "region" and contain the NCA Region label associated with each population estimate in a given year. If popArea = "national", only the year and pop columns are required.

  • If popArea = "state", the file must contain estimates for all CONUS states -- i.e., all states except Alaska and Hawaii must be present in the input file (estimates for Alaska and Hawaii are optional). If popArea = "regional", the file must contain estimates for all seven NCA regions.

  • The population scenario must start in 2010 or earlier and end at or after the maximum model run year (e.g., as specified by the maxYear argument to run_fredi()).

  • Population values must be greater than or equal to zero.

  • Population estimates must have at least one non-missing value in 2010 or earlier and at least one non-missing value in or after the final analysis year (as specified by the run_fredi() maxYear argument).

run_fredi() requires a population scenario at the state level. If the population scenario is supplied to import_inputs() at a geographical scale above the state level (i.e., if popArea = "national", popArea = "area", or popArea = "regional"), import_inputs() will calculate state-level estimates from the provided data:

• If popArea = "national", import_inputs() will use historical U.S. Census data for the period 2010--2023 to allocate total national population to CONUS and non-CONUS regions (i.e., Alaska and Hawaii); U.S. Census values from 2023 are applied in allocations for years after 2023. import_inputs() then uses ICLUS data and projections for the period 2010--2100 to allocate CONUS population to specific NCA regions; ICLUS values from 2100 are applied in allocations for years after 2100.

• If popArea = "national" or popArea = "regional", import_inputs() uses ICLUS data and projections for the period 2010--2100 to allocate population for each NCA region to the associated states; ICLUS values from 2100 are applied in allocations for years after 2100.

import_inputs() outputs a list of data frame objects that can be passed to the main FREDI function run_fredi() using the inputList argument. For example, specify run_fredi(inputsList = x) to generate impacts for a custom scenario x (where x is a list of data frames such as that output from import_inputs()) (see run_fredi()).

All inputs to import_inputs() are optional. If the user does not specify a file path for tempfile, slrfile, gdpfile, or popfile (or if there is are any errors reading in inputs from a file path), import_inputs() outputs a list with a NULL value for the associated list element. After reading in data from the specified CSV files, import_inputs() performs basic checks and will also return a NULL value for a particular list element if any of the checks fail.

When using import_inputs() with run_fredi(), run_fredi() defaults back to the default scenarios for any elements of the inputs list that are NULL or missing. In other words, running run_fredi(inputsList = list()) returns the same outputs as running run_fredi() (see run_fredi()).

References

Environmental Protection Agency (EPA). 2021. Technical Documentation on The Framework for Evaluating Damages and Impacts (FrEDI). Technical Report EPA 430-R-21-004, EPA, Washington, DC. Available at https://epa.gov/cira/FrEDI/.

United Nations. 2015. World population prospects: The 2015 revision. New York: United Nations, Department of Economic and Social Affairs, Population Division.

U.S. Census Bureau. 2021. State Population Totals and Components of Change: 2010--2019. Available at https://www.census.gov/data/tables/time-series/demo/popest/2010s-state-total.html.

U.S. Census Bureau. 2023. State Population Totals and Components of Change: 2020--2023. Available at https://www.census.gov/data/tables/time-series/demo/popest/2020s-state-total.html.

U.S. Census Bureau. 2023. 2023 National Population Projections Tables: Main Series. Available at https://www.census.gov/data/tables/2023/demo/popproj/2023-summary-tables.html.

Examples

### Path to example scenarios
scenariosPath <- system.file(package="FrEDI") |> file.path("extdata","scenarios")

### View example scenario names
scenariosPath |> list.files()
#> [1] "GCAM_scenario.csv"          "State ICLUS Population.csv"
#> [3] "slr_from_GCAM.csv"         

### SLR Scenario File Name
slrInputFile  <- scenariosPath |> file.path("slr_from_gcam.csv")

### Population Scenario File Name
popInputFile  <- scenariosPath |> file.path("State ICLUS Population.csv")

### Import inputs
example_inputsList <- import_inputs(slrfile=slrInputFile, popfile=popInputFile, popArea="state")
#> 
#> In import_inputs():
#> 	Loading data...
#> 	User specified slrfile...
#> 		Importing data from C:/Program Files/R/R-4.4.0/library/FrEDI/extdata/scenarios/slr_from_gcam.csv...
#> 		Data loaded.
#> 	User specified popfile...
#> 		Importing data from C:/Program Files/R/R-4.4.0/library/FrEDI/extdata/scenarios/State ICLUS Population.csv...
#> 		Data loaded.
#> 
#> 	Checking input values...
#> 
#> 		Checking input values for slr inputs...
#> 		Values passed.
#> 
#> 		Checking input values for pop inputs...
#> 			Column "pop" not found in popfile data!
#> 			Looking for columns with matches to the string "pop"...1 match found!
#> 			Using column "state_pop", and renaming to "state_pop"...
#> 		Values passed.
#> 
#> Finished.

### Use imports with FREDI:
df_x <- run_fredi(inputsList=example_inputsList)
#> Checking input values...
#> 	No temperature scenario provided...using default temperature scenario...
#> 	Creating SLR scenario from user inputs...
#> 	No GDP scenario provided...Using default GDP scenario...
#> 	Creating population scenario from user inputs...
#> Updating scalars...
#> Calculating impacts...
#> Formatting results...
#> 
#> Finished.