From 3c7db74488029a258f9c82931b1e4d4f518c8957 Mon Sep 17 00:00:00 2001 From: Karen Noiva Date: Mon, 25 Nov 2024 14:37:00 -0500 Subject: [PATCH] Updated documentation - Updated .Rd files for functions using `roxygen2::roxygenise()` - Edited examples for `run_fredi_sv()` --- R/run_fredi_sv.R | 40 +++++------ man/FrEDI-package.Rd | 1 + man/defaultResults.Rd | 42 ------------ man/gcamScenarios.Rd | 39 +++++++---- man/gdpDefault.Rd | 52 +++++++++++++++ man/import_inputs.Rd | 91 ++++++++++++++++--------- man/popDefault.Rd | 35 ++++++++++ man/popScenario.Rd | 35 ---------- man/run_fredi.Rd | 69 ++++++++++--------- man/run_fredi_methane.Rd | 140 +++++++++++++++++++++++++++++++++++++++ man/run_fredi_sv.Rd | 53 +++++++-------- 11 files changed, 392 insertions(+), 205 deletions(-) delete mode 100644 man/defaultResults.Rd create mode 100644 man/gdpDefault.Rd create mode 100644 man/popDefault.Rd delete mode 100644 man/popScenario.Rd create mode 100644 man/run_fredi_methane.Rd diff --git a/R/run_fredi_sv.R b/R/run_fredi_sv.R index 4b5268a..17ffdce 100644 --- a/R/run_fredi_sv.R +++ b/R/run_fredi_sv.R @@ -49,7 +49,7 @@ #' #' @examples #' ### Run SV Module with defaults without specifying sector -#' df_sv <- run_fredi_sv() +#' # df_sv <- run_fredi_sv() #' #' ### Return a character vector with the names of all of the sectors in the FrEDI SV Module: #' get_sv_sectorInfo() @@ -67,16 +67,16 @@ #' data(gcamScenarios) #' #' ### Load population scenario -#' data(popDefault) +#' data(popScenario) #' #' ### Run SV Module for "Extreme Temperature" with custom population and temperature scenarios -#' df_sv <- run_fredi_sv(sector = "Extreme Temperature", inputsList = list(pop=popDefault, temp=gcamScenarios) +#' df_sv <- run_fredi_sv(sector = "Extreme Temperature", inputsList=list(pop=popScenario, temp=gcamScenarios) #' #' ### Run SV Module for "Coastal Properties" with custom population and SLR scenarios -#' df_sv <- run_fredi_sv(sector = "Coastal Properties", inputsList = list(pop=popDefault, slr=gcamScenarios) +#' df_sv <- run_fredi_sv(sector = "Coastal Properties", inputsList=list(pop=popScenario, slr=gcamScenarios) #' #' ### Run SV Module for "Coastal Properties" with custom population and temperature scenarios -#' df_sv <- run_fredi_sv(sector = "Coastal Properties", inputsList = list(pop=popDefault, temp=gcamScenarios) +#' df_sv <- run_fredi_sv(sector = "Coastal Properties", inputsList=list(pop=popScenario, temp=gcamScenarios) #' #' #' @@ -106,10 +106,10 @@ run_fredi_sv <- function( .testing = FALSE ){ ###### Set up the environment ###### - pkgPath <- NULL - pkgPath <- (pkgPath |> is.null()) |> ifelse(system.file(package="FrEDI"), pkgPath); - rDataType <- "rds" - impactsPath <- pkgPath |> file.path("extdata", "sv", "impactLists") + pkgPath <- NULL + pkgPath <- (pkgPath |> is.null()) |> ifelse(system.file(package="FrEDI"), pkgPath); + rDataType <- "rds" + impactsPath <- pkgPath |> file.path("extdata", "sv", "impactLists") ###### ** Load Data Objects ###### ### Get FrEDI data objects @@ -128,20 +128,20 @@ run_fredi_sv <- function( ### Group types c_svGroupTypes <- svDataList$c_svGroupTypes - minYear <- minYear0 - maxYear <- maxYear0 - yearsBy5 <- minYear |> seq(maxYear, by=5) + minYear <- minYear0 + maxYear <- maxYear0 + yearsBy5 <- minYear |> seq(maxYear, by=5) ### Testing - save <- .testing |> ifelse(FALSE, save) + save <- .testing |> ifelse(FALSE, save) ### Level of messaging (default is to message the user) - silent <- (silent |> is.null()) |> ifelse(T, silent) - msgUser <- !silent - msg0 <- "" - msg1 <- msg0 |> paste0("\t") - msg2 <- msg1 |> paste0("\t") - msg3 <- msg2 |> paste0("\t") + silent <- (silent |> is.null()) |> ifelse(T, silent) + msgUser <- !silent + msg0 <- "" + msg1 <- msg0 |> paste0("\t") + msg2 <- msg1 |> paste0("\t") + msg3 <- msg2 |> paste0("\t") ###### ** State Columns ###### byState <- TRUE @@ -239,7 +239,7 @@ run_fredi_sv <- function( idCols0 <- list(valCols0=valCols0, df0=inputDefs[inNames0]) |> pmap(function(valCols0, df0){ df0 |> names() |> get_matches(y=valCols0, matches=F) }) |> set_names(inNames0) - valCols0 |> print(); idCols0 |> print() + # valCols0 |> print(); idCols0 |> print() ###### ** Valid Inputs & Input Info ###### ### Figure out which inputs are not null, and filter to that list diff --git a/man/FrEDI-package.Rd b/man/FrEDI-package.Rd index b115ab6..ff77ddb 100644 --- a/man/FrEDI-package.Rd +++ b/man/FrEDI-package.Rd @@ -100,6 +100,7 @@ Useful links: Authors: \itemize{ \item Erin McDuffie \email{mcduffie.erin.e@epa.gov} (\href{https://orcid.org/0000-0002-6845-6077}{ORCID}) (emcduffie) [contributor] + \item Marcus Sarofim \email{mcduffie.erin.e@epa.gov} (\href{https://orcid.org/0000-0001-7753-1676}{ORCID}) (emcduffie) [contributor] \item Karen Noiva (\href{https://orcid.org/0000-0002-4412-5302}{ORCID}) (knoiva-indecon) [contributor] } diff --git a/man/defaultResults.Rd b/man/defaultResults.Rd deleted file mode 100644 index 3f01983..0000000 --- a/man/defaultResults.Rd +++ /dev/null @@ -1,42 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/data.R -\docType{data} -\name{defaultResults} -\alias{defaultResults} -\title{Default outputs of \code{\link[=run_fredi]{run_fredi()}} -A dataframe containing the default outputs of \code{\link[=run_fredi]{run_fredi()}}} -\format{ -A data frame with 1,501,500 rows and 20 columns: -\describe{ -\item{sector}{Name of the associated sector.} -\item{variant}{Name of the associated variant or adaptation (values are sector-specific).} -\item{impactYear}{Name of the impact year ("2010", "2090", "N/A", or "Interpolation").} -\item{impactType}{Name of the impact type ("all" or sector-specific values).} -\item{region}{Name of the associated region ("Midwest", "Northeast", "Northern Plains", "Northwest", "Southeast", "Southern Plains", "Southwest", or "National Total").} -\item{state}{Name of the associated state (or District of Columbia): "Alabama", "Arizona", "Arkansas", "California", "Colorado", "Connecticut", "Delaware", "District of Columbia", "Florida", "Georgia", "Idaho", "Illinois", "Indiana", "Iowa", "Kansas", "Kentucky", "Louisiana", "Maine", "Maryland", "Massachusetts", "Michigan", "Minnesota", "Mississippi", "Missouri", "Montana", "Nebraska", "Nevada", "New Hampshire", "New Jersey", "New Mexico", "New York", "North Carolina", "North Dakota", "Ohio", "Oklahoma", "Oregon", "Pennsylvania", "Rhode Island", "South Carolina", "South Dakota", "Tennessee", "Texas", "Utah", "Vermont", "Virginia", "Washington", "West Virginia", "Wisconsin", "Wyoming". For the "National Total" region, \code{state = "All"}. For sectors with only has region-level data, \code{state = "N/A"}.} -\item{postal}{Postal code abbreviation of the associated state (e.g., \code{postal="AL"} for \code{state="Alabama"}). The postal code abbreviation for the District of Columbia is \code{"DC"}. For the "National Total" region, \code{postal = "US"}. For sectors with only has region-level data, \code{postal = "N/A"}.} -\item{model_type}{Type of model used to calculate impacts --- either "GCM" (for "Global Climate Model") or "SLR" for ("Sea Level Rise")} -\item{model}{Name of the GCM ("Average", "CanESM2", "CCSM4", "GCM Ensemble", "GFDL-CM3", "GISS-E2-R", "HadGEM2-ES", "MIROC5", "MRI-CGCM3") or SLR model ("Interpolation")} -\item{sectorprimary}{A \code{0} or \code{1} value indicating whether the sector is a primary CIRA sector (and whether it should be included when summing across sectors). \code{sectorprimary=1} if a primary sector and \code{sectorprimary=0} if not.} -\item{includeaggregate}{A \code{0} or \code{1} value indicating whether the variant is the primary variant for the sector (and whether it should be included when summing across sectors). \code{includeaggregate=1} if the variant is a primary variant and \code{includeaggregate=0} if not).} -\item{driverType}{Associated driver type ("Temperature" or "GMSL (SLR)").} -\item{driverUnit}{Unit for the associated driver type ("degrees Celsius" for temperature and "cm" for sea level rise).} -\item{driverValue}{Value for the associated driver type (in "degrees Celsius" for temperature and in "cm" for sea level rise).} -\item{gdp_usd}{National gross domestic product (GDP) for associated year in 2015 USD (U.S. dollars).} -\item{national_pop}{National population for associated year.} -\item{gdp_per_cap}{National GDP per capita for associated year in 2015 USD (U.S. dollars) per capita.} -\item{state_pop}{Population for the associated state (for state-level data) or region (for region-only data).} -\item{annual_impacts}{Annual impacts for associated sector, variant, impact type, impact year, region, state, model type, model, and year.} -} -} -\source{ -\url{https://epa.gov/cira/FrEDI/} -} -\usage{ -defaultResults -} -\description{ -Default outputs of \code{\link[=run_fredi]{run_fredi()}} -A dataframe containing the default outputs of \code{\link[=run_fredi]{run_fredi()}} -} -\keyword{datasets} diff --git a/man/gcamScenarios.Rd b/man/gcamScenarios.Rd index da08cf3..608abee 100644 --- a/man/gcamScenarios.Rd +++ b/man/gcamScenarios.Rd @@ -5,12 +5,14 @@ \alias{gcamScenarios} \title{Six driver scenarios that can be passed as inputs to \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}}} \format{ -A data frame with 546 rows and 4 columns: +A data frame with 606 rows and 6 columns: \describe{ -\item{year}{Year} -\item{temp_C}{Global temperature (in degrees Celsius) for the associated year and scenario} -\item{slr_cm}{Global Mean Sea Level Rise (in centimeters) for the associated year and scenario} -\item{scenario}{Associated scenario identifier} +\item{year }{Year} +\item{temp_C_global}{Global temperatures, in degrees Celsius, for the associated year and scenario} +\item{temp_C_conus }{Temperatures for the contiguous U.S. (CONUS), in degrees Celsius, for the associated year and scenario (converted from global temperatures using \link{convertTemps(from="global")})} +\item{slr_cm }{Global Mean Sea Level Rise (GMSL or SLR), in centimeters, for the associated year and scenario (calculated from global temperatures using \code{\link[=temps2slr]{temps2slr()}})} +\item{scenario }{Associated scenario identifier (e.g., \code{"ECS_3.0_REF"})} +\item{model }{A string (\code{"Hector_GCAM_v5.3"}) identifying the model (\strong{Hector}, with \strong{GCAM v5.3}) used in generating the global temperatures associated with each scenario} } } \source{ @@ -20,21 +22,32 @@ A data frame with 546 rows and 4 columns: gcamScenarios } \description{ -A dataframe containing six driver scenarios that can be passed as inputs to \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}}. This data frame has four columns -- \code{year}, \code{temp_C}, \code{slr_cm}, and \code{scenario} -- respectively containing: +\code{gcamScenarios} is a data frame object containing six driver scenarios that can be passed as inputs to \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}}. This data frame has five columns -- \code{year}, \code{temp_C_global}, \code{temp_C_conus}, \code{slr_cm}, \code{scenario}, and \code{model}: } \details{ \describe{ -\item{year}{The Common Era (CE) year associated with the observation.} -\item{temp_C}{Global temperature (i.e., degrees of warming above the baseline year of 1995) in degrees Celsius, for the associated year and scenario.} -\item{slr_cm}{Global Mean Sea Level Rise (i.e., SLR) in centimeters for the associated year and scenario.} -\item{scenario}{Associated scenario identifier.} +\item{year }{The Common Era (CE) year associated with the observation.} +\item{temp_C_global}{Global temperature (i.e., degrees of warming above the baseline year of 1995), in degrees Celsius, for the associated year and scenario.} +\item{temp_C_conus }{Temperatures (i.e., degrees of warming above the baseline year of 1995) for the contiguous U.S. (CONUS), in degrees Celsius, for the associated year and scenario (calculated from global temperatures using \link{convertTemps(from="global")}).} +\item{slr_cm }{Global Mean Sea Level Rise (GMSL or SLR), in centimeters, for the associated year and scenario (calculated from global temperatures using \code{\link[=temps2slr]{temps2slr()}}).} +\item{scenario }{Associated scenario identifier (e.g., \code{"ECS_3.0_REF"}).} +\item{model }{A string (\code{"Hector_GCAM_v5.3"}) identifying the model (\strong{Hector}, with \strong{GCAM v5.3}) used in generating the global temperatures associated with each scenario.} } -The scenarios in this dataframe were created using \href{https://jgcri.github.io/hector/}{Hector}, an open-source, reduced-form global carbon-cycle climate model (Hartin et al., 2015) to model temperatures associated with emissions scenarios from the Global Change Analysis Model v5.3 (GCAM). The Global Change Analysis Model v5.3 (\href{https://gcims.pnnl.gov/modeling/gcam-global-change-analysis-model}{GCAM}) is an open source model that represents the linkages between energy, water, land, climate and economic systems (Calvin et al., 2019). Scenario identifiers in the \code{scenario} column of \code{\link[=gcamScenarios]{gcamScenarios()}} have the string \code{"Hector_GCAM_v5.3_ECS_"} as a prefix, followed by the average warming temperature and the suffix \code{"_REF"} (e.g., \code{"Hector_GCAM_v5.3_ECS_3.0_REF"} for the default scenario for \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}}. +The scenarios in this data frame were created using \strong{Hector} with \strong{GCAM v5.3}: +\itemize{ +\item \href{https://jgcri.github.io/hector/}{\strong{Hector}} is an open-source, reduced-form global carbon-cycle climate model (Hartin et al., 2015) used to model temperatures associated with emissions scenarios from the Global Change Analysis Model v5.3 (GCAM). +\item \href{https://gcims.pnnl.gov/modeling/gcam-global-change-analysis-model}{\strong{GCAM v5.3}} -- i.e., the Global Change Analysis Model v5.3 -- is an open source model that represents the linkages between energy, water, land, climate and economic systems (Calvin et al., 2019). +} -These six temperature scenarios represent global temperatures; however, \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}} require temperature scenarios for the contiguous U.S. (CONUS). Therefore, to use the \code{gcamScenarios} with \code{\link[=run_fredi]{run_fredi()}} or \code{\link[=run_fredi_sv]{run_fredi_sv()}}, users must first convert temperatures in the \code{temp_C} column to CONUS temperatures via the \link{convertTemps} function -- with argument \code{from = "global"} (e.g., \code{gcamScenarios |> mutate(temp_C = temp_C |> FrEDI::convertTemps(from = "global"))}). +Scenario identifiers in the \code{scenario} column of \code{\link[=gcamScenarios]{gcamScenarios()}} have the string \code{"ECS_3.0_REF_"} as a prefix, followed by a suffix indicating an emissions intensity associated with the scenario (e.g., \code{"20"}) -- for instance, the default scenario for \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}} is \code{"ECS_3.0_REF"}. Other scenarios include \code{"ECS_3.0_REF_20"}, \code{"ECS_3.0_REF_30"}, \code{"ECS_3.0_REF_50"}, \code{"ECS_3.0_REF_70"}, and \code{"ECS_3.0_REF_90"}. -The GCAM scenarios can be passed directly to the SV module via the \code{driverInput} argument (e.g., \code{run_fredi_sv(driverInput = gcamScenarios)}), since \code{\link[=run_fredi_sv]{run_fredi_sv()}} is designed to run multiple scenarios. In contrast, \code{\link[=run_fredi]{run_fredi()}} is intended to be run with a single scenario; \code{gcamScenarios} should be subset to a specific scenario before passing the temperature scenario to \code{\link[=run_fredi]{run_fredi()}} (e.g., \code{run_fredi(list(tempInput=gcamScenarios |> dplyr::filter(scenario=="Hector_GCAM_v5.3_ECS_3.0_REF")))} to use the default scenario). +Users can use the scenarios in \code{gcamScenarios} as inputs to FrEDI or the FrEDI SV Module: +\itemize{ +\item Users can filter the \code{gcamScenarios} data frame to any of these six scenarios, which can then be passed directly to the \code{\link[=run_fredi]{run_fredi()}} function via a named element (\code{temp} and/or \code{slr}) in a list passed to the \code{inputsList} argument -- e.g., \code{run_fredi(inputsList=list(temp=gcamScenarios |> filter(scenario=="ECS_3.0_REF")))} will run using the default temperature scenario. +\item Any or all of the GCAM scenarios can be passed directly to the FrEDI SV module via the \code{\link[=run_fredi_sv]{run_fredi_sv()}} function via a named list element (\code{temp} and/or \code{slr}) in a list passed to the \code{inputsList} argument -- e.g., \code{run_fredi_sv(inputsList=list(temp=gcamScenarios))} will run the SV module for all the GCAM scenarios provided in \code{gcamScenarios}. +\item \code{gcamScenarios} can also be combined with other provided scenarios (\code{gdpDefault}, \code{popDefault}) in function calls (e.g., \code{run_fredi(inputsList=list(temp=gcamScenarios |> filter(scenario=="ECS_3.0_REF"), gdp=gdpDefault, pop=popDefault))}) or user-provided data frames. For more information, see documentation for \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=FrEDI:run_fredi_sv]{FrEDI:run_fredi_sv()}}, \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}, and \code{\link[=import_inputs]{import_inputs()}}. +} Calvin, K., Patel, P., Clarke, L., et al. 2019. GCAM v5.1: representing the linkages between energy, water, land, climate, and economic systems, Geosci. Model Dev., 12:677–698. https://doi.org/10.5194/gmd-12-677-2019. diff --git a/man/gdpDefault.Rd b/man/gdpDefault.Rd new file mode 100644 index 0000000..197fe28 --- /dev/null +++ b/man/gdpDefault.Rd @@ -0,0 +1,52 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data.R +\docType{data} +\name{gdpDefault} +\alias{gdpDefault} +\title{Scenario with values for U.S. Gross Domestic Product (GDP), which can be passed as an input to \code{\link[=run_fredi]{run_fredi()}} or \code{\link[=run_fredi_methane]{run_fredi_methane()}}.} +\format{ +A data frame with 91 rows and 2 columns: +\describe{ +\item{year }{Year} +\item{gdp_usd}{U.S. Gross Domestic Product for the contiguous U.S.} +} + +An object of class \code{tbl_df} (inherits from \code{tbl}, \code{data.frame}) with 291 rows and 2 columns. +} +\source{ +\url{https://epa.gov/cira/FrEDI/} + +\url{https://epa.gov/cira/FrEDI/} +} +\usage{ +gdpDefault + +gdpDefault +} +\description{ +\code{gdpDefault} is a data frame object containing values for U.S. GDP for the contiguous U.S. (CONUS) for the period from 2010 to 2100. Values are from the \strong{MIT Economic Projection and Policy Analysis Version 6} (\strong{EPPA v6}) model (Chen et al, 2015; EPA 2017). + +\code{ch4Default} is a data frame object that contains projections with changes in annual US methane concentrations, at the national level, for the period from 2020 to 2100. Values for changes in annual US methane concentrations are provided in parts per billion by volume (ppbv) relative to a 1995-2006 baseline era. This scenario represents the SSP245 mean emissions pathway from RCMIP5, with methane concentrations produced using the FaIR model. For more information on the SSP245 mean emissions pathway and the FaIR model, see Nichols et al. (2020) and Leach, et al. (2021), respectively. +} +\details{ +To use \code{gdpDefault} as an input to FrEDI and/or the FrEDI Methane module, pass the data frame via the named element \code{gdp} in a list passed to the \code{inputsList} argument in function calls to \code{\link[=run_fredi]{run_fredi()}} and/or \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}, respectively, e.g.: \code{run_fredi(inputsList=list(gdp=gdpDefault))}. \code{gdpDefault} can also be combined with other provided scenarios (\code{gcamScenarios}, \code{popDefault}) in function calls (e.g., \code{run_fredi(inputsList=list(gdp=gdpDefault, pop=popDefault))}) or user-provided data frames. For more information, see documentation for \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}, and \code{\link[=import_inputs]{import_inputs()}}. + +Chen, Y.-H. H., S. Paltsev, J. M. Reilly, J. F. Morris, and M. H. Babiker. 2015. The MIT EPPA6 Model: conomic Growth, Energy Use, and Food Consumption. MIT Joint Program on the Science and Policy of Global Change, No. 278. + +EPA. 2017. Multi-Model Framework for Quantitative Sectoral Impacts Analysis: A technical report for the Fourth National Climate Assessment. U.S. Environmental Protection Agency, EPA 430-R-17-001. + +To use \code{ch4Default} as an input to the FrEDI Methane module, pass the data frame via the named element \code{ch4} in a list passed to the \code{inputsList} argument in function calls to \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}, e.g.: \code{run_fredi_methane(inputsList=list(ch4=ch4Default))}. \code{ch4Default} can also be combined with other provided scenarios (\code{gdpDefault}, \code{popDefault}) in function calls (e.g., \code{run_fredi(inputsList=list(gdp=gdpDefault, pop=popDefault))}) or user-provided data frames. For more information, see documentation for \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}, and \code{\link[=import_inputs]{import_inputs()}}. + +Leach, N. J., Jenkins, S., Nicholls, Z., Smith, C. J., Lynch, J., Cain, M., Walsh, T., Wu, B., Tsutsui, J., and Allen, M. R. 2021. FaIRv2.0.0: a generalized impulse response model for climate uncertainty and future scenario exploration, Geosci. Model Dev., 14, 3007--3036, https://doi.org/10.5194/gmd-14-3007-2021. + +Nicholls, Z. R. J., Meinshausen, M., Lewis, J., Gieseke, R., Dommenget, D., Dorheim, K., Fan, C.-S., Fuglestvedt, J. S., Gasser, T., Goluke, U., Goodwin, P., Hartin, C., Hope, A. P., Kriegler, E., Leach, N., Marchegiani, D., McBride, L. A., Quilcaille, Y., Rogelj, J., Xie, Z. (2020). Reduced Complexity Model Intercomparison Project Phase 1: introduction and evaluation of global-mean temperature response. Geoscientific Model Development. 13. 5175-5190. 10.5194/gmd-13-5175-2020. + +Environmental Protection Agency (EPA). Forthcoming. Technical Documentation on The Framework for Evaluating Damages and Impacts (FrEDI). Technical Report, EPA, Washington, DC. Available at \url{https://epa.gov/cira/FrEDI/}. + +@format A data frame with 81 rows and 2 columns: +\describe{ +\item{year }{Year} +\item{CH4_ppbv}{Change in U.S. methane concentrations, in parts per billion by volume (ppbv), relative to a 1995-2006 baseline era.} +} +} +\keyword{datasets} diff --git a/man/import_inputs.Rd b/man/import_inputs.Rd index d625ff3..ebacb1f 100644 --- a/man/import_inputs.Rd +++ b/man/import_inputs.Rd @@ -5,26 +5,32 @@ \title{Import custom scenarios for temperature, global mean sea level rise (GMSL), population, and GDP from user-specified file names} \usage{ import_inputs( - tempfile = NULL, - slrfile = NULL, - gdpfile = NULL, - popfile = NULL, + inputsList = list(gdp = NULL, pop = NULL, temp = NULL, slr = NULL, ch4 = NULL, nox = + NULL, o3 = NULL), temptype = "conus", - popArea = "state" + popArea = "state", + module = "fredi" ) } \arguments{ -\item{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 \code{"year"} and contain years associated with the temperature estimates; the second column (named \code{"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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}).} - -\item{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 \code{"year"} and contain years associated with the sea level rise estimates; second column should be named "\verb{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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}).} - -\item{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 \code{"year"} and contains years associated with the GDP estimates; the second column (named \code{"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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}). Values for GDP in column \code{"gdp_usd"} must be greater than or equal to zero.} - -\item{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 \code{"year"} and contain years in the interval 2010 to 2300. The second column should be called \code{"pop"} and contain population values. Whether a third column is required depends on the geographical scale of the data, as specified by the \code{popArea} argument (for more information, see the \code{popArea} argument, below. +\item{inputsList=list(gdp=NULL, pop=NULL, temp=NULL, slr=NULL, ch4=NULL, nox=NULL)}{A named list containing file paths to CSV files containing scenarios: +\itemize{ +\item \strong{gdp} A character string indicating the location of a CSV file containing a custom scenario for U.S. gross domestic product (GDP), for use with \code{\link[=run_fredi]{run_fredi()}} or \code{\link[=run_fredi_methane]{run_fredi_methane()}}. The first column in the CSV should be named \code{"year"} and contains years associated with the GDP estimates; the second column (named \code{"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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}} or \code{\link[=run_fredi_methane]{run_fredi_methane()}}). Values for GDP in column \code{"gdp_usd"} must be greater than or equal to zero. +\item \strong{pop} A character string indicating the location of a CSV file containing a custom population scenario for states and NCA regions, for use with \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=run_fredi_sv]{run_fredi_sv()}}, or \code{\link[=run_fredi_methane]{run_fredi_methane()}}. The first column should be named \code{"year"} and contain years in the interval 2010 to 2300. The second column should be called \code{"pop"} and contain population values. Whether a third column is required depends on the geographical scale of the data, as specified by the \code{popArea} argument (for more information, see the \code{popArea} argument, below. \itemize{ \item If \code{popArea = "state"}, the third column should be called \code{"state"} and contain the name of the state associated with each population estimate in a given year. If \code{popArea = "regional"}, the third column should be called \code{"region"} and contain the NCA Region label associated with each population estimate in a given year. If \code{popArea = "national"}, only the \code{year} and \code{pop} columns are required. \item If \code{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 \code{popArea = "regional"}, the file must contain estimates for all seven NCA regions. -\item 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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}). Values for population in column \code{"pop"} must be greater than or equal to zero. +\item 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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}} or \code{\link[=run_fredi_methane]{run_fredi_methane()}}). Values for population in column \code{"pop"} must be greater than or equal to zero. +} +\item \strong{temp} A character string indicating the location of a CSV file containing a custom temperature scenario, for use with \code{run_fredi()} or \code{run_fredi_sv()}. The first column in the CSV should be named \code{"year"} and contain years associated with the temperature estimates; the second column (named \code{"temp_C"}) should contain values for temperatures (i.e., degrees of warming relative to a baseline era of 1986-2005), 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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}). +\item \strong{slr} A character string indicating the location of a CSV file containing a custom sea level rise scenario, for use with \code{run_fredi()} or \code{run_fredi_sv()}. The first column in the CSV should be named \code{"year"} and contain years associated with the sea level rise estimates; the second column should be named "\verb{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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}). +\item \strong{o3} A character string indicating the location of a CSV file containing a custom scenario for changes in U.S. state-level ozone concentrations (relative to a 1986-2005 baseline era). The input ozone scenario requires changes in annual state-level ozone concentrations, by GCM model, in parts per trillion by volume (pptv) relative to a 1986-2005 baseline era. In other words, the input ozone scenario requires ozone concentrations specific to the state, GCM model, and year of the analysis. +\itemize{ +\item The \code{o3} input requires a data frame object with six columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"model"}, \code{"year"}, and \code{"O3_pptv"} containing the region name (\code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"} for CONUS states, or \code{"Alaska"} and \code{"Hawaii"} for Alaska and Hawaii, respectively), the state name, the two-character postal code abbreviation for the state, the GCM model name (\code{"CanESM2"}, \code{"GFDL-CM3"}, \code{"GISS-E2-R"}, \code{"HadGEM2-ES"}, and/or \code{"MIROC5"}), the year, and the change in ozone concentration (in pptv) relative to a 1986-2005 baseline era. +\item Ozone inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by the \code{maxYear} argument). +} +\item \strong{ch4} A character string indicating the location of a CSV file containing a custom scenario for changes in U.S. methane concentrations (relative to a 1986-2005 baseline era), at the national level, for use with \code{run_fredi_methane()}. The first column in the CSV should be named \code{"year"} and contain years associated with the national methane estimates; the second column should be named "\verb{CH4_ppbv"} and contain values for methane. The methane scenario must start in 2020 or earlier and end at or after the maximum model run year (e.g., as specified by the \code{maxYear} argument to \code{\link[=run_fredi_methane]{run_fredi_methane()}}). +\item \strong{nox} A character string indicating the location of a CSV file containing a custom scenario for U.S. NOx emission values, at the national level. The first column in the CSV should be named \code{"year"} and contain years associated with the national NOx estimates; the second column should be named "\verb{Mt"} and contain values for NOx emissions, in megatons per year (Mt). The NOx scenario must start in 2020 or earlier and end at or after the maximum model run year (e.g., as specified by the \code{maxYear} argument to \code{\link[=run_fredi_methane]{run_fredi_methane()}}). }} \item{temptype="conus"}{A character string indicating whether the temperature values in the temperature input file (as specified by \code{tempfile}) represent temperature changes, in degrees Celsius, at the global level (\code{temptype = "global"}) or for the contiguous U.S. (CONUS) only (\code{temptype = "conus"}, default).} @@ -36,46 +42,67 @@ import_inputs( \tabular{ll}{ \strong{List Index} \tab \strong{Description} \cr -\code{tempInput} \tab Data frame containing a custom temperature scenario imported from the CSV file specified by \code{tempfile}, with missing values removed. \code{tempInput} has two columns with names \code{"year"} and \code{"temp_C"}, containing the year and CONUS temperatures in degrees Celsius, respectively. \cr -\code{slrInput} \tab Data frame containing a custom GMSL scenario imported from the CSV file specified by \code{slrfile}, with missing values removed. \code{slrInput} has two columns with names \code{"year"}, and \code{"slr_cm"}, containing the year and global mean sea level rise (GMSL) in centimeters, respectively. \cr -\code{gdpInput} \tab Data frame containing a custom GDP scenario imported from the CSV file specified by \code{gdpfile}, with missing values removed. \code{gdpInput} has two columns with names \code{"year"}, and \code{"gdp_usd"}, containing the year and the national GDP, respectively. \cr -\code{popInput} \tab Data frame containing a custom temperature scenario imported from the CSV file specified by \code{popfile}, with missing values removed. \code{popInput} has three columns with names \code{"year"}, \code{"region"}, \code{"state"}, \code{"postal"}, and \code{"state_pop"}, containing the year, the NCA region name, and the state, the postal code abbreviation (e.g., \code{postal = "ME"} for \code{state = "Maine"}), and the state population, respectively. \cr +\code{gdp} \tab Data frame containing a custom GDP scenario imported from the CSV file specified by \code{inputsList$gdp}, with missing values removed. \code{gdp} has two columns with names \code{"year"}, and \code{"gdp_usd"}, containing the year and the national GDP, respectively. \cr +\code{pop} \tab Data frame containing a custom temperature scenario imported from the CSV file specified by \code{inputsList$pop}, with missing values removed. \code{popInput} has three columns with names \code{"year"}, \code{"region"}, \code{"state"}, \code{"postal"}, and \code{"pop"}, containing the year, the NCA region name, and the state, the postal code abbreviation (e.g., \code{postal = "ME"} for \code{state = "Maine"}), and the state population, respectively. \cr +\code{temp} \tab Data frame containing a custom temperature scenario imported from the CSV file specified by \code{inputsList$temp}, with missing values removed. \code{temp} has two columns with names \code{"year"} and \code{"temp_C"}, containing the year and CONUS temperatures in degrees Celsius, respectively. \cr +\code{slr} \tab Data frame containing a custom GMSL scenario imported from the CSV file specified by \code{inputsList$slr}, with missing values removed. \code{slr} has two columns with names \code{"year"}, and \code{"slr_cm"}, containing the year and global mean sea level rise (GMSL) in centimeters, respectively. \cr +\code{o3} \tab Data frame containing a custom scenario with changes in ozone concentrations imported from the CSV file specified by \code{inputsList$temp}, with missing values removed. \code{o3} has six columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"model"}, \code{"year"}, and \code{"O3_pptv"} containing the region name (\code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"} for CONUS states, or \code{"Alaska"} and \code{"Hawaii"} for Alaska and Hawaii, respectively), the state name, the two-character postal code abbreviation for the state, the GCM model name (\code{"CanESM2"}, \code{"GFDL-CM3"}, \code{"GISS-E2-R"}, \code{"HadGEM2-ES"}, and/or \code{"MIROC5"}), the year, and the change in ozone concentration (in pptv) relative to a 1986-2005 baseline era. \cr +\code{ch4} \tab Data frame containing a custom scenario with changes in methane concentrations imported from the CSV file specified by \code{inputsList$slr}, with missing values removed. \code{ch4} has two columns with names \code{"year"}, and \code{"CH4_ppbv"}, containing the year and Change in U.S. methane concentrations, in parts per billion by volume (ppbv) relative to a 1995-2006 baseline era, respectively. \cr +\code{nox} \tab Data frame containing a custom NOx emissions scenario imported from the CSV file specified by \code{inputsList$nox}, with missing values removed. \code{nox} has two columns with names \code{"year"} and \code{"NOx_Mt"}, containing the year and U.S. national-level NOx emissions (in Mt), respectively. \cr } } \description{ This function enables users to import data on custom scenarios for use with \code{\link[=run_fredi]{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. \code{\link[=import_inputs]{import_inputs()}} reads in and format any specified files as data frames and returns a list of data frames for imported scenarios. } \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 (\code{tempfile}, \code{slrfile}, \code{gdpfile}, and \code{popfile}, respectively). \code{\link[=import_inputs]{import_inputs()}} reads in and formats any specified files as data frames and returns a list of data frames for imported scenarios. +This function enables users to import data on custom scenarios for use with temperature binning. Users provide a named list specifying path names to CSV files containing scenarios for gross domestic product (GDP) (for use with \code{\link[=run_fredi]{run_fredi()}} or \code{\link[=run_fredi_methane]{run_fredi_methane()}}); population (for use with \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=run_fredi_sv]{run_fredi_sv()}}, or \code{\link[=run_fredi_methane]{run_fredi_methane()}}); temperature and/or global mean sea level rise (GMSL) (for use with \code{\link[=run_fredi]{run_fredi()}} or \code{\link[=run_fredi_sv]{run_fredi_sv()}}); or methane or NOx (for use with \code{\link[=run_fredi_methane]{run_fredi_methane()}}). \code{\link[=import_inputs]{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 \code{run_fredi()} or `` \itemize{ -\item \strong{Temperature Scenario.} The file specified by \code{tempfile} must have two columns -- \code{"year"} and \code{"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). +\item \strong{GDP Scenario.} The file specified by \code{inputsList$gdp} must have two columns -- \code{"year"} and \code{"gdp_usd"} -- respectively containing the years associated with the GDP estimates and the estimates for U.S. GDP, in 2015$. +\itemize{ +\item GDP values must be greater than or equal to zero. +\item 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 \code{\link[=run_fredi]{run_fredi()}} \code{maxYear} argument). +} +\item \strong{Population Scenario.} The file specified by \code{inputsList$pop} population must have at least two columns -- \code{"year"} and \code{"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 \code{popArea} argument. +\itemize{ +\item If \code{popArea = "state"}, the third column should be called \code{"state"} and contain the name of the state associated with each population estimate in a given year. If \code{popArea = "regional"}, the third column should be called \code{"region"} and contain the NCA Region label associated with each population estimate in a given year (one of \code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"} for CONUS states, or \code{"Alaska"} and \code{"Hawaii"} for Alaska and Hawaii, respectively). If \code{popArea = "national"}, only the \code{year} and \code{pop} columns are required. +\item If \code{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 \code{popArea = "regional"}, the file must contain estimates for all seven NCA regions. +\item 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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}). +\item Population values must be greater than or equal to zero. +\item 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 \code{\link[=run_fredi]{run_fredi()}} \code{maxYear} argument). +} +\item \strong{Temperature Scenario.} The file specified by \code{inputsList$temp} must have two columns -- \code{"year"} and \code{"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). \itemize{ \item If values in \code{"temp_C"} have global rather than CONUS-specific temperatures, users should specify \code{temptype = "global"} when running \code{import_inputs()}, and \code{import_inputs()} will convert the temperatures to CONUS using \link{convertTemps} (with argument \code{from = "global"}). \item Temperature inputs to \code{\link[=run_fredi]{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 \code{\link[=run_fredi]{run_fredi()}} \code{maxYear} argument). } -\item \strong{SLR Scenario.} The file specified by \code{slrfile} must have two columns -- \code{"year"} and \code{"slr_cm"} -- respectively containing the years associated with the GMSL estimates and GMSL estimates, in centimeters, above a 2000 baseline year. +\item \strong{SLR Scenario.} The file specified by \code{inputsList$slr} must have two columns -- \code{"year"} and \code{"slr_cm"} -- respectively containing the years associated with the GMSL estimates and GMSL estimates, in centimeters, above a 2000 baseline year. \itemize{ \item GMSL heights must be greater than or equal to zero. \item 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 \code{\link[=run_fredi]{run_fredi()}} \code{maxYear} argument). } -\item \strong{GDP Scenario.} The file specified by \code{gdpfile} must have two columns -- \code{"year"} and \code{"gdp_usd"} -- respectively containing the years associated with the GDP estimates and the estimates for U.S. GDP, in 2015$. +\item \strong{Ozone Scenario.} The input ozone scenario requires changes in annual state-level ozone concentrations, by GCM model, in parts per trillion by volume (pptv) relative to a 1986-2005 baseline era. In other words, the input ozone scenario requires ozone concentrations specific to the state, GCM model, and year of the analysis. \itemize{ -\item GDP values must be greater than or equal to zero. -\item 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 \code{\link[=run_fredi]{run_fredi()}} \code{maxYear} argument). +\item \code{o3} requires a data frame object with six columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"model"}, \code{"year"}, and \code{"O3_pptv"} containing the region name (\code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"} for CONUS states, or \code{"Alaska"} and \code{"Hawaii"} for Alaska and Hawaii, respectively), the state name, the two-character postal code abbreviation for the state, the GCM model name (\code{"CanESM2"}, \code{"GFDL-CM3"}, \code{"GISS-E2-R"}, \code{"HadGEM2-ES"}, and/or \code{"MIROC5"}), the year, and the change in ozone concentration (in pptv) relative to a 1986-2005 baseline era. +\item Ozone inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). +\item If inputs are specified for ozone \emph{and} methane or NOx (i.e., \code{!is.null(inputsList$o3) & (!is.null(inputsList$ch4) | !is.null(inputsList$nox))}), \code{run_fredi_methane()} will use the ozone scenario in preference of the methane and NOx scenario. } -\item \strong{Population Scenario.} The file specified by \code{popfile} population must have at least two columns -- \code{"year"} and \code{"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 \code{popArea} argument. +\item \strong{Methane Scenario.} The input methane scenario requires changes in annual methane concentrations, at the national level, in parts per billion by volume (ppbv) relative to a 1986-2005 baseline era. \itemize{ -\item If \code{popArea = "state"}, the third column should be called \code{"state"} and contain the name of the state associated with each population estimate in a given year. If \code{popArea = "regional"}, the third column should be called \code{"region"} and contain the NCA Region label associated with each population estimate in a given year. If \code{popArea = "national"}, only the \code{year} and \code{pop} columns are required. -\item If \code{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 \code{popArea = "regional"}, the file must contain estimates for all seven NCA regions. -\item 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 \code{maxYear} argument to \code{\link[=run_fredi]{run_fredi()}}). -\item Population values must be greater than or equal to zero. -\item 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 \code{\link[=run_fredi]{run_fredi()}} \code{maxYear} argument). +\item \code{ch4} requires a data frame object with two columns with names \code{"year"} and \code{"CH4_ppbv"} containing the year and the change in methane concentration (in ppbv) relative to a 1986-2005 baseline era. +\item Methane inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). +\item \code{run_fredi_methane()} will override a user-supplied methane scenario with a user-supplied ozone scenario; in other words, \code{run_fredi_methane()} will use the ozone scenario in preference of the methane and NOx scenario. +} +\item \strong{NOx Scenario.} The input NOx scenario requires annual NOx emissions in the US, at the national level, in Megatons (MT) relative to a 1986-2005 baseline. +\itemize{ +\item \code{nox} requires a data frame object with two columns with names \code{"year"} and \code{"NOx_Mt"} containing the year and the change in NOx concentration (in Mt) relative to a 1986-2005 baseline era. +\item NOx inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). +\item \code{run_fredi_methane()} will override a user-supplied methane scenario with a user-supplied ozone scenario; in other words, \code{run_fredi_methane()} will use the ozone scenario in preference of the methane and NOx scenario. } } -\code{\link[=run_fredi]{run_fredi()}} requires a population scenario at the state level. If the population scenario is supplied to \code{\link[=import_inputs]{import_inputs()}} at a geographical scale above the state level (i.e., if \code{popArea = "national"}, \code{popArea = "area"}, or \code{popArea = "regional"}), \code{\link[=import_inputs]{import_inputs()}} will calculate state-level estimates from the provided data: +\code{\link[=run_fredi]{run_fredi()}}, \code{\link[=run_fredi_sv]{run_fredi_sv()}}, and \code{\link[=run_fredi_methane]{run_fredi_methane()}} each require a population scenario at the state level. If the population scenario is supplied to \code{\link[=import_inputs]{import_inputs()}} at a geographical scale above the state level (i.e., if \code{popArea = "national"}, \code{popArea = "area"}, or \code{popArea = "regional"}), \code{\link[=import_inputs]{import_inputs()}} will calculate state-level estimates from the provided data: \itemize{ \item If \code{popArea = "national"}, \code{\link[=import_inputs]{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. \code{\link[=import_inputs]{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. \item If \code{popArea = "national"} or \code{popArea = "regional"}, \code{\link[=import_inputs]{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. @@ -83,7 +110,7 @@ The CSV files should contain estimates aligned with the requirements of the \cod \code{\link[=import_inputs]{import_inputs()}} outputs a list of data frame objects that can be passed to the main FREDI function \code{\link[=run_fredi]{run_fredi()}} using the \code{inputList} argument. For example, specify \code{run_fredi(inputsList = x)} to generate impacts for a custom scenario \code{x} (where \code{x} is a list of data frames such as that output from \code{\link[=import_inputs]{import_inputs()}}) (see \code{\link[=run_fredi]{run_fredi()}}). -All inputs to \code{\link[=import_inputs]{import_inputs()}} are optional. If the user does not specify a file path for \code{tempfile}, \code{slrfile}, \code{gdpfile}, or \code{popfile} (or if there is are any errors reading in inputs from a file path), \code{\link[=import_inputs]{import_inputs()}} outputs a list with a \code{NULL} value for the associated list element. After reading in data from the specified CSV files, \code{\link[=import_inputs]{import_inputs()}} performs basic checks and will also return a \code{NULL} value for a particular list element if any of the checks fail. +All inputs to \code{\link[=import_inputs]{import_inputs()}} are optional. If the user does not specify particular named elements (or if there is are any errors reading in inputs from a file path), \code{\link[=import_inputs]{import_inputs()}} outputs a list with a \code{NULL} value for the associated list element. After reading in data from the specified CSV files, \code{\link[=import_inputs]{import_inputs()}} performs basic checks and will also return a \code{NULL} value for a particular list element if any of the checks fail. When using \code{\link[=import_inputs]{import_inputs()}} with \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=run_fredi]{run_fredi()}} defaults back to the default scenarios for any elements of the inputs list that are \code{NULL} or missing. In other words, running \code{run_fredi(inputsList = list())} returns the same outputs as running \code{\link[=run_fredi]{run_fredi()}} (see \code{\link[=run_fredi]{run_fredi()}}). } @@ -101,7 +128,7 @@ slrInputFile <- scenariosPath |> file.path("slr_from_gcam.csv") popInputFile <- scenariosPath |> file.path("State ICLUS Population.csv") ### Import inputs -example_inputsList <- import_inputs(slrfile=slrInputFile, popfile=popInputFile, popArea="state") +example_inputsList <- import_inputs(inputsList=list(slr=slrInputFile, pop=popInputFile), popArea="state") ### Use imports with FREDI: df_x <- run_fredi(inputsList=example_inputsList) diff --git a/man/popDefault.Rd b/man/popDefault.Rd new file mode 100644 index 0000000..21e8b69 --- /dev/null +++ b/man/popDefault.Rd @@ -0,0 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data.R +\docType{data} +\name{popDefault} +\alias{popDefault} +\title{U.S. state population scenario, which can be passed as an input to \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=run_fredi_sv]{run_fredi_sv()}}, and/or \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}.} +\format{ +A data frame with 4,459 rows and 5 columns: +\describe{ +\item{region}{Region of the U.S.: one of \code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"} for CONUS states, or \code{"Alaska"} and \code{"Hawaii"} for Alaska and Hawaii, respectively.} +\item{state }{U.S. states or the District of Columbia} +\item{postal}{Two-letter postal code abbreviation associated with the state (e.g., \code{"AL"} for Alabama)} +\item{year }{Year} +\item{pop }{State population for associated region and year} +} +} +\source{ +\url{https://epa.gov/cira/FrEDI/} +} +\usage{ +popDefault +} +\description{ +\code{popDefault} is a data frame object that contains population projections for 50 U.S. states and the District of Columbia for the period from 2010 to 2100. Values for the 48 states and the District of Columbia comprising the contiguous U.S. (CONUS) are from the \strong{Integrated Climate and Land Use Scenarios Version 2} (\strong{ICLUSv2}) model (Bierwagen et al, 2010; EPA 2017) under the Median variant projection of United Nations (United Nations, 2015). Values for Alaska and Hawaii are from the U.S. Census Bureau. +} +\details{ +To use \code{popDefault} as an input to FrEDI, the FrEDI SV module, and/or the FrEDI Methane module, pass the data frame via the named element \code{pop} in a list passed to the \code{inputsList} argument in function calls to \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=run_fredi_sv]{run_fredi_sv()}}, and/or \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}, respectively, e.g.: \code{run_fredi(inputsList=list(pop=popDefault))}. \code{popDefault} can also be combined with other provided scenarios (\code{gcamScenarios}, \code{gdpDefault}) in function calls (e.g., \code{run_fredi(inputsList=list(gdp=gdpDefault, pop=popDefault))}) or user-provided data frames. For more information, see documentation for \code{\link[=run_fredi]{run_fredi()}}, \code{\link[=FrEDI:run_fredi_sv]{FrEDI:run_fredi_sv()}}, \code{\link[=FrEDI:run_fredi_methane]{FrEDI:run_fredi_methane()}}, and \code{\link[=import_inputs]{import_inputs()}}. + +Bierwagen, B., D. M. Theobald, C. R. Pyke, A. Choate, P. Groth, J. V. Thomas, and P. Morefield. 2010. “National housing and impervious surface scenarios for integrated climate impact assessments.” Proc. Natl. Acad. Sci. 107 (49): 20887–20892. https://doi.org/10.1073/pnas.1002096107. + +EPA. 2017. Multi-Model Framework for Quantitative Sectoral Impacts Analysis: A technical report for the Fourth National Climate Assessment. U.S. Environmental Protection Agency, EPA 430-R-17-001. + +United Nations. 2015. World population prospects: The 2015 revision. New York: United Nations, Department of Economic and Social Affairs, Population Division. +} +\keyword{datasets} diff --git a/man/popScenario.Rd b/man/popScenario.Rd deleted file mode 100644 index 888affa..0000000 --- a/man/popScenario.Rd +++ /dev/null @@ -1,35 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/data.R -\docType{data} -\name{popScenario} -\alias{popScenario} -\title{Population scenario to use as an input to \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}}} -\format{ -A data frame with 14,259 rows and 5 columns: -\describe{ -\item{year}{Year} -\item{region}{Region of U.S. ("Midwest", "Northeast", "Northern Plains", "Northwest", "Southeast", "Southern Plains", and "Southwest")} -\item{state}{One of 48 contiguous U.S. states or the District of Columbia} -\item{postal}{Postal code abbreviation associated with the state} -\item{state_pop}{State population for associated region and year} -} -} -\source{ -\url{https://epa.gov/cira/FrEDI/} -} -\usage{ -popScenario -} -\description{ -A dataframe containing a population scenario to be passed as an input to \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=run_fredi_sv]{run_fredi_sv()}}. -} -\details{ -This dataframe contains population projections at the state level from the Integrated Climate and Land Use Scenarios version 2 (ICLUSv2) model (Bierwagen et al, 2010; EPA 2017) under the Median variant projection of United Nations (2015). - -Bierwagen, B., D. M. Theobald, C. R. Pyke, A. Choate, P. Groth, J. V. Thomas, and P. Morefield. 2010. “National housing and impervious surface scenarios for integrated climate impact assessments.” Proc. Natl. Acad. Sci. 107 (49): 20887–20892. https://doi.org/10.1073/pnas.1002096107. - -EPA. 2017. Multi-Model Framework for Quantitative Sectoral Impacts Analysis: A technical report for the Fourth National Climate Assessment. U.S. Environmental Protection Agency, EPA 430-R-17-001. - -United Nations. 2015. World population prospects: The 2015 revision. New York: United Nations, Department of Economic and Social Affairs, Population Division. -} -\keyword{datasets} diff --git a/man/run_fredi.Rd b/man/run_fredi.Rd index 941a50c..9d9a9a0 100644 --- a/man/run_fredi.Rd +++ b/man/run_fredi.Rd @@ -5,7 +5,7 @@ \title{Project annual average climate change impacts throughout the 21st century for available sectors} \usage{ run_fredi( - inputsList = list(tempInput = NULL, slrInput = NULL, gdpInput = NULL, popInput = NULL), + inputsList = list(temp = NULL, slr = NULL, gdp = NULL, pop = NULL), sectorList = NULL, aggLevels = c("national", "modelaverage", "impactyear", "impacttype"), elasticity = 1, @@ -17,7 +17,7 @@ run_fredi( ) } \arguments{ -\item{inputsList=NULL}{A list of named elements named elements (\code{names(inputsList) = c("tempInput", "slrInput", "gdpInput", "popInput")}), each containing data frames of custom temperature, global mean sea level rise (GMSL), gross domestic product (GDP), and/or state-level population trajectories, respectively, over a continuous period in the range 2010 to 2300. Temperature and sea level rise inputs should start in 2000 or earlier. Values for population and GDP scenarios can start in 2010 or earlier. Values for each scenario type must be within reasonable ranges. For more information, see \code{\link[=import_inputs]{import_inputs()}}.} +\item{inputsList=list(gdp=NULL, pop=NULL, temp=NULL, slr=NULL)}{A list with named elements (\code{gdp}, \code{pop}, \code{temp}, and/or \code{slr}), each containing data frames of custom scenarios for gross domestic product (GDP), state-level population, temperature, and/or global mean sea level rise (GMSL) trajectories, respectively, over a continuous period. Temperature and sea level rise inputs should start in 2000 or earlier. Values for population and GDP scenarios can start in 2010 or earlier. Values for each scenario type must be within reasonable ranges. For more information, see \code{\link[=import_inputs]{import_inputs()}}.} \item{sectorList=NULL}{A character vector indicating a selection of sectors for which to calculate results (see \code{\link[=get_sectorInfo]{get_sectorInfo()}}). If \code{NULL}, all sectors are included (i.e., \code{sectorList = get_sectorInfo()}).} @@ -54,41 +54,41 @@ As of FrEDI Version 4.1.0, \code{\link[=run_fredi]{run_fredi()}} calculates impa \details{ This function allows users to project annual average climate change impacts through 2300 (2010-2300) for available sectors. \code{\link[=run_fredi]{run_fredi()}} is the main function in the \link{FrEDI} R package, described elsewhere (See \url{https://epa.gov/cira/FrEDI} for more information). -Users can specify an optional list of custom scenarios with \code{inputsList} (for more information on the format of inputs, see \code{\link[=import_inputs]{import_inputs()}}). The function \code{\link[=import_inputs]{import_inputs()}} can be used to importing custom scenarios from CSV files. \code{\link[=import_inputs]{import_inputs()}} returns a list with elements \code{tempInput}, \code{slrInput}, \code{gdpInput}, and \code{popInput}, with each containing a data frame with a custom scenario for temperature, GMSL, GDP, and state-level population, respectively. If a user imports scenarios using \code{\link[=import_inputs]{import_inputs()}}, they can pass the outputs of \code{\link[=import_inputs]{import_inputs()}} directly to the \code{\link[=run_fredi]{run_fredi()}} argument \code{inputsList}. Note that the documentation for \code{\link[=import_inputs]{import_inputs()}} can also provide additional guidance and specification on the formats for each scenario type. +Users can specify an optional list of custom scenarios with \code{inputsList} (for more information on the format of inputs, see \code{\link[=import_inputs]{import_inputs()}}). The function \code{\link[=import_inputs]{import_inputs()}} can be used to importing custom scenarios from CSV files. \code{\link[=import_inputs]{import_inputs()}} returns a list with named elements \code{gdp}, \code{pop}, \code{temp}, and \code{slr}, with each containing a data frame with a custom scenario for GDP, state-level population, temperature, and/or GMSL respectively. If a user imports scenarios using \code{\link[=import_inputs]{import_inputs()}}, they can pass the outputs of \code{\link[=import_inputs]{import_inputs()}} directly to the \code{\link[=run_fredi]{run_fredi()}} argument \code{inputsList}. Note that the documentation for \code{\link[=import_inputs]{import_inputs()}} can also provide additional guidance and specification on the formats for each scenario type. -If \code{inputsList = NULL}, \code{\link[=run_fredi]{run_fredi()}} uses defaults for temperature, SLR, GDP, and population. Otherwise, \code{\link[=run_fredi]{run_fredi()}} looks for a list object passed to the argument \code{inputsList}. Within that list, \code{\link[=run_fredi]{run_fredi()}} looks for list elements \code{tempInput}, \code{slrInput}, \code{gdpInput}, and \code{popInput} containing data frames with custom scenarios for temperature, GMSL, GDP, and state population, respectively. \code{\link[=run_fredi]{run_fredi()}} will default back to the default scenarios for any list elements that empty or \code{NULL} (in other words, running \code{run_fredi(inputsList = list())} returns the same outputs as running \code{\link[=run_fredi]{run_fredi()}}). +Otherwise, \code{\link[=run_fredi]{run_fredi()}} looks for a list object passed to the argument \code{inputsList}. Within that list, \code{\link[=run_fredi]{run_fredi()}} looks for named list elements -- \code{gdp}, \code{pop}, \code{temp}, and/or \code{slr} -- each containing a data frame with a custom scenario for GDP, state population, temperature, and/or GMSL, respectively. If \code{inputsList = NULL} or \code{inputsList = list()} (default), \code{\link[=run_fredi]{run_fredi()}} uses default trajectories for GDP, population, temperature, and SLR (see \link{gdpDefault}, \link{popDefault}, and \link{gcamScenarios} for more information). \code{\link[=run_fredi]{run_fredi()}} will default back to the default scenarios for any list elements that empty or \code{NULL} (in other words, running \code{run_fredi(inputsList = list())} returns the same outputs as running \code{\link[=run_fredi]{run_fredi()}}). \itemize{ +\item \strong{GDP Inputs.} The input scenario for gross domestic product (GDP) requires national GDP values in 2015$. GDP values must be greater than or equal to zero. +\itemize{ +\item \code{gdp} requires a data frame object with two columns with names \code{"year"}, and \code{"gdp_usd"} containing the year and the national GDP, respectively. GDP values must be greater than or equal to zero. +\item GDP inputs 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 \code{maxYear}). +\item If the user does not specify an input scenario for GDP (i.e., \code{inputsList = list(gdp = NULL)}, \code{\link[=run_fredi]{run_fredi()}} uses a default GDP scenario. +} +\item \strong{Population Inputs.} The input population scenario requires state-level population values. Population values must be greater than or equal to zero. +\itemize{ +\item \code{pop} requires a data frame object with five columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"year"}, and \code{"pop"} containing the year, the NCA region name (one of \code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"}), the state name, the postal code abbreviation for the state, and the state population, respectively. +\item Population inputs 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 \code{maxYear}). +\item If the user does not specify an input scenario for population (i.e., \code{inputsList = list(pop = NULL)}, \code{\link[=run_fredi]{run_fredi()}} uses a default population scenario. +} \item \strong{Temperature Inputs.} The input temperature scenario requires CONUS temperatures in degrees Celsius relative to 1995 (degrees of warming relative to the baseline year--i.e., the central year of the 1986-2005 baseline). CONUS temperature values must be greater than or equal to zero degrees Celsius. \itemize{ \item Users can convert global temperatures to CONUS temperatures using \link{convertTemps}\code{(from = "global")} (or by specifying \link{import_inputs}\code{(temptype = "global")} when using \code{\link[=import_inputs]{import_inputs()}} to import a temperature scenario from a CSV file). -\item \code{tempInput} requires a data frame object with two columns with names \code{"year"}, and \code{"temp_C"} containing the year and CONUS temperatures in degrees Celsius, respectively. +\item \code{temp} requires a data frame object with two columns with names \code{"year"}, and \code{"temp_C"} containing the year and CONUS temperatures in degrees Celsius, respectively. \item Temperature inputs 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 \code{maxYear}). -\item If the user does not specify an input scenario for temperature (i.e., \code{inputsList = list(tempInput = NULL)}, \code{\link[=run_fredi]{run_fredi()}} uses a default temperature scenario. +\item If the user does not specify an input scenario for temperature (i.e., \code{inputsList = list(temp = NULL)}, \code{\link[=run_fredi]{run_fredi()}} uses a default temperature scenario. } \item \strong{SLR Inputs.} The input SLR scenario requires values for changes in global mean sea level rise (GMSL) heights in centimeters (cm). GMSL heights must be greater than or equal to zero. \itemize{ -\item \code{slrInput} requires a data frame object with two columns with names \code{"year"}, \code{"slr_cm"} containing the year and global mean sea level rise (GMSL) in centimeters, respectively. +\item \code{slr} requires a data frame object with two columns with names \code{"year"}, \code{"slr_cm"} containing the year and global mean sea level rise (GMSL) in centimeters, respectively. \item SLR inputs 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 \code{maxYear}). -\item If the user does not specify an input scenario for SLR (i.e., \code{inputsList = list(slrInput = NULL)}, \code{\link[=run_fredi]{run_fredi()}} first converts the input or default CONUS temperature scenario to global temperatures (using \code{\link[=convertTemps]{convertTemps()}}) and then converts the global temperatures to a global mean sea level rise (GMSL) height in centimeters (using \code{\link[=temps2slr]{temps2slr()}}). -} -\item \strong{GDP Inputs.} The input scenario for gross domestic product (GDP) requires national GDP values in 2015$. GDP values must be greater than or equal to zero. -\itemize{ -\item \code{gdpInput} requires a data frame object with two columns with names \code{"year"}, and \code{"gdp_usd"} containing the year and the national GDP, respectively. GDP values must be greater than or equal to zero. -\item GDP inputs 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 \code{maxYear}). -\item If the user does not specify an input scenario for GDP (i.e., \code{inputsList = list(gdpInput = NULL)}, \code{\link[=run_fredi]{run_fredi()}} uses a default GDP scenario. -} -\item \strong{Population Inputs.} The input population scenario requires state-level population values. Population values must be greater than or equal to zero. -\itemize{ -\item \code{popInput} requires a data frame object with five columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"year"}, and \code{"state"} containing the year, the NCA region name, the state name, the postal code abbreviation for the state, and the state population, respectively. -\item Population inputs 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 \code{maxYear}). -\item If the user does not specify an input scenario for population (i.e., \code{inputsList = list(popInput = NULL)}, \code{\link[=run_fredi]{run_fredi()}} uses a default population scenario. +\item If the user does not specify an input scenario for SLR (i.e., \code{inputsList = list(slr = NULL)}, \code{\link[=run_fredi]{run_fredi()}} first converts the input or default CONUS temperature scenario to global temperatures (using \code{\link[=convertTemps]{convertTemps()}}) and then converts the global temperatures to a global mean sea level rise (GMSL) height in centimeters (using \code{\link[=temps2slr]{temps2slr()}}). } } \code{\link[=run_fredi]{run_fredi()}} linearly interpolates missing annual values for all input scenarios using non-missing values (each scenario requires at least two non-missing values as detailed above for each scenario type). After interpolation of the input scenarios, \code{\link[=run_fredi]{run_fredi()}} subsets the input scenarios to values within the analysis period. \itemize{ -\item Temperatures are interpolated using 1995 as the baseline year (i.e., the central year of the 1986-2005 baseline) and GMSL is interpolated using 2000 as the baseline year. In other words, temperature (in degrees Celsius) is set to zero for the year 1995, whereas GMSL is set to zero for the year 2000. The interpolated temperature and GMSL scenarios are combined into a column called \code{driverValue}, along with additional columns for year, the driver unit (column \code{"driverUnit"}, with \code{driverUnit = "degrees Celsius"} and \code{driverUnit = "cm"} for temperature- and SLR-driven sectors, respectively), and the associated model type (column \code{"model_type"}, with \code{model_type = "GCM"} and \code{model_type = "SLR"} for temperature- and SLR-driven sectors, respectively -\item \code{\link[=run_fredi]{run_fredi()}} calculations national population from state-level values and then calculates GDP per capita from values for GDP and national population. Values for state population, national population, national GDP (in 2015$), and national per capita GDP (in 2015$/capita) are provided in the results data frame in columns \code{"state_pop"}, \code{"national_pop"}, \code{"gdp_usd"}, and \code{"gdp_percap"}, respectively. +\item Temperatures are interpolated using 1995 as the baseline year (i.e., the central year of the 1986-2005 baseline) and GMSL is interpolated using 2000 as the baseline year. In other words, temperature (in degrees Celsius) is set to zero for the year 1995, whereas GMSL is set to zero for the year 2000. The interpolated temperature and GMSL scenarios are combined into a column called \code{driverValue}, along with additional columns for year, the driver unit (column \code{"driverUnit"}, with \code{driverUnit = "degrees Celsius"} and \code{driverUnit = "cm"} for temperature- and SLR-driven sectors, respectively), and the associated model type (column \code{"model_type"}, with \code{model_type = "GCM"} and \code{model_type = "SLR"} for temperature- and SLR-driven sectors, respectively. +\item \code{\link[=run_fredi]{run_fredi()}} calculates national population from state-level values and then calculates GDP per capita from values for GDP and national population. Values for state population, national population, national GDP (in 2015$), and national per capita GDP (in 2015$/capita) are provided in the results data frame in columns \code{"pop"}, \code{"national_pop"}, \code{"gdp_usd"}, and \code{"gdp_percap"}, respectively. } By default, \code{\link[=run_fredi]{run_fredi()}} will calculate impacts for all sectors included in the tool. Alternatively, users can pass a character vector specifying a single sector or a subset of sectors using the \code{sectorList} argument. To see a list of sectors included within \link{FrEDI}, run \code{\link[=get_sectorInfo]{get_sectorInfo()}}. If \code{sectorList = NULL} (default), all sectors are included. @@ -99,7 +99,7 @@ Annual impacts for each sector, variant, impact type, and impact year combinatio \code{\link[=run_fredi]{run_fredi()}} aggregates or summarizes results to level(s) of aggregation specified by the user (passed to \code{aggLevels}) using the post-processing helper function \code{\link[=aggregate_impacts]{aggregate_impacts()}}. Users can specify all aggregation levels at once by specifying \code{aggLevels = "all"} (default) or no aggregation levels (\code{aggLevels = "none"}). Users can specify a single aggregation level or multiple aggregation levels by passing a single character string or character vector to \code{aggLevels}. Options for aggregation include calculating national totals (\code{aggLevels = "national"}), averaging across model types and models (\code{aggLevels = "modelaverage"}), summing over all impact types (\code{aggLevels = "impacttype"}), and interpolating between impact year estimates (\code{aggLevels = "impactYear"}). -If the user specifies \code{aggLevels = "none"}, \code{\link[=run_fredi]{run_fredi()}} returns a data frame with columns: \code{"sector"}, \code{"variant"}, \code{"impactType"}, \code{"impactYear"}, \code{"region"}, \code{"state"}, \code{"postal"}, \code{"model_type"}, \code{"model"}, \code{"sectorprimary"}, \code{"includeaggregate"}, \code{"physicalmeasure"}, \code{"driverType"}, \code{"driverUnit"}, \code{"driverValue"}, \code{"gdp_usd"}, \code{"national_pop"}, \code{"gdp_percap"}, \code{"state_pop"}, \code{"year"}, \code{"physical_impacts"}, and \code{"annual_impacts"}. +If the user specifies \code{aggLevels = "none"}, \code{\link[=run_fredi]{run_fredi()}} returns a data frame with columns: \code{"sector"}, \code{"variant"}, \code{"impactType"}, \code{"impactYear"}, \code{"region"}, \code{"state"}, \code{"postal"}, \code{"model_type"}, \code{"model"}, \code{"sectorprimary"}, \code{"includeaggregate"}, \code{"physicalmeasure"}, \code{"driverType"}, \code{"driverUnit"}, \code{"driverValue"}, \code{"gdp_usd"}, \code{"national_pop"}, \code{"gdp_percap"}, \code{"pop"}, \code{"year"}, \code{"physical_impacts"}, and \code{"annual_impacts"}. \itemize{ \item Columns \code{"sector"}, \code{"variant"}, \code{"impactType"}, \code{"impactYear"}, \code{"region"}, \code{"state"}, \code{"postal"}, \code{"model_type"}, and \code{"model"} all contain observation identifiers (sector name, variant, impact type, impact year, region, state, state postal code abbreviation, model type, and model, respectively). \item Columns \code{"sectorprimary"} and \code{"includeaggregate"} contain values that provide information about how to treat sectors and when aggregating over sectors (e.g., summing impacts across sectors). Note that \link{FrEDI} does not currently provide functionality to aggregate over sectors; this information is provided for user convenience. @@ -108,7 +108,7 @@ If the user specifies \code{aggLevels = "none"}, \code{\link[=run_fredi]{run_fre \item Column \code{"includeaggregate"} contains values that provide information about how to treat sectors when aggregating over sectors (e.g., summing impacts across sectors). Sectors that have a value of \code{includeaggregate == 0} should be dropped when aggregating results over sectors, to avoid potential double-counting of impacts for similar sectors. For instance, sectors \strong{ATS Temperature-Related Mortality}, \strong{CIL Temperature-Related Mortality}, and \strong{Extreme Temperature} have values for temperature-related mortality. To avoid double counting, outputs of \code{\link[=run_fredi]{run_fredi()}} should be filtered to values for which \code{includeaggregate > 0}. Sectors with a value of \code{includeaggregate > 0} can be included when aggregating over sectors; most sectors with a value of \code{includeaggregate > 0} will have a value of \code{includeaggregate = 1}. Values of \code{includeaggregate > 1} flag additional information about sectors; currently, only the \strong{Suicide} sector has a value of \code{includeaggregate > 1}, with a value of \code{includeaggregate = 2}. This flag indicates that the impacts from \strong{Suicide} can be included when summing values across sectors, but may have some overlap with impacts from \strong{ATS Temperature-Related Mortality}. For more information about the potential overlap between impacts for \strong{ATS Temperature-Related Mortality} and \strong{Suicide}, visit the technical documentation at \url{https://epa.gov/cira/FrEDI/}, } \item Columns \code{"driverType"}, \code{"driverUnit"}, and \code{"driverValue"} contain information about the temperature and SLR scenarios. -\item Columns \code{"gdp_usd"}, \code{"national_pop"}, \code{"gdp_percap"}, and \code{"state_pop"} contain information about the GDP and population scenarios. +\item Columns \code{"gdp_usd"}, \code{"national_pop"}, \code{"gdp_percap"}, and \code{"pop"} contain information about the GDP and population scenarios. \item Columns \code{"physicalmeasure"} and \code{"physical_impacts"} contain information about physical impacts. \item Column \code{"annual_impacts"} contains information on the economic value associated with annual impacts. } @@ -126,7 +126,7 @@ If the user specifies \code{aggLevels = "all"} or other combinations of aggregat \emph{\code{impacttype}} \tab To aggregate values over impact types, \code{\link[=aggregate_impacts]{aggregate_impacts()}} sums annual impacts (column \code{"annual_impacts"}) across all impact types for each sector. \code{\link[=aggregate_impacts]{aggregate_impacts()}} drops the column \code{"impactType"} and \code{"physicalmeasure"} from the grouping columns when summing over impact types. Years which have missing column data for all impact types return as \code{NA}. All values in column \code{"impactType"} are set to \code{"all"}. Aggregating over impact types, drops columns related to physical impacts (i.e., columns \code{"physicalmeasure"} and \code{"physical_impacts"}). These columns are dropped since aggregating over impact types for some sectors requires summing costs over different types of physical impacts, so reporting the physical impacts would be nonsensical.\cr } -After aggregating values, \code{\link[=aggregate_impacts]{aggregate_impacts()}} joins the data frame of impacts with information about \code{"driverType"}, \code{"driverUnit"}, \code{"driverValue"}, \code{"gdp_usd"}, \code{"national_pop"}, \code{"gdp_percap"}, and \code{"state_pop"}. +After aggregating values, \code{\link[=aggregate_impacts]{aggregate_impacts()}} joins the data frame of impacts with information about \code{"driverType"}, \code{"driverUnit"}, \code{"driverValue"}, \code{"gdp_usd"}, \code{"national_pop"}, \code{"gdp_percap"}, and \code{"pop"}. If \code{outputList = FALSE} (default), \code{\link[=run_fredi]{run_fredi()}} returns a data frame of annual average impacts over the analysis period, for each sector, variant, impact type, impact year, region, state, model type (\code{"GCM"} or \code{"SLR"}), and model. If \code{outputList = TRUE}, in addition to the data frame of impacts, \code{\link[=run_fredi]{run_fredi()}} returns a list object containing information about values for function arguments, driver scenarios, and population and GDP scenarios. } @@ -134,7 +134,7 @@ If \code{outputList = FALSE} (default), \code{\link[=run_fredi]{run_fredi()}} re ### Load FrEDI require(FrEDI) -### Run function with defaults (same as `defaultResults` dataset) +### Run function with defaults run1 <- run_fredi() ### Load climate scenarios and glimpse data @@ -142,16 +142,15 @@ data("gcamScenarios") gcamScenarios |> glimpse() ### Load population scenario and glimpse data -data(popScenario) -popScenario |> glimpse() +data("popDefault") +popDefault |> glimpse() ### Subset climate scenario -temps1 <- gcamScenarios |> filter(scenario=="Hector_GCAM_v5.3_ECS_3.0_ref") -temps1 <- temps1 |> mutate(temp_C = temp_C_global |> convertTemps(from="global")) -temps1 <- temps1 |> select(year, temp_C) +temps1 <- gcamScenarios |> filter(scenario=="ECS_3.0_ref") +temps1 <- temps1 |> select(year, temp_C_conus) ### Run custom scenario -run2 <- run_fredi(inputsList=list(tempInput=temps1, popInput=popScenario)) +run2 <- run_fredi(inputsList=list(temp=temps1, pop=popDefault)) ### Load scenarios from file: scenariosPath <- system.file(package="FrEDI") |> file.path("extdata","scenarios") @@ -159,13 +158,13 @@ scenariosPath |> list.files() ### SLR Scenario File Name -slrInputFile <- scenariosPath |> file.path("slr_from_GCAM.csv") +slrInputFile <- scenariosPath |> file.path("gcamDefault.csv") ### Population Scenario File Name -popInputFile <- scenariosPath |> file.path("State ICLUS Population.csv") +popInputFile <- scenariosPath |> file.path("popDefault.csv") ### Import inputs -x_inputs <- import_inputs(slrfile=slrInputFile, popfile=popInputFile, popArea="state") +x_inputs <- import_inputs(inputsList=list(slr=slrInputFile, pop=popInputFile), popArea="state") ### Run custom scenarios run3 <- run_fredi(inputsList=x_inputs) diff --git a/man/run_fredi_methane.Rd b/man/run_fredi_methane.Rd new file mode 100644 index 0000000..1d57648 --- /dev/null +++ b/man/run_fredi_methane.Rd @@ -0,0 +1,140 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/run_fredi_methane.R +\name{run_fredi_methane} +\alias{run_fredi_methane} +\title{Project annual average impacts from methane, NOx, and ozone.} +\usage{ +run_fredi_methane( + inputsList = list(gdp = NULL, pop = NULL, ch4 = NULL, nox = NULL, o3 = NULL), + elasticity = 1, + maxYear = 2100, + thru2300 = FALSE, + outputList = FALSE, + allCols = FALSE +) +} +\arguments{ +\item{inputsList=list(gdp=NULL, pop=NULL, ch4=NULL, nox=NULL, o3=NULL)}{A list with named elements (\code{gdp}, \code{pop}, \code{ch4}, \code{nox}, and/or \code{o3}), each containing data frames of custom scenarios for gross domestic product (GDP), state-level population, ozone concentration, methane concentration, and NOx emissions, respectively, over a continuous period. Values should start in 2020 or earlier. Values for each scenario type must be within reasonable ranges. For more information, see \code{\link[=import_inputs]{import_inputs()}}.} + +\item{elasticity=1}{A numeric value indicating an elasticity to use for adjusting VSL (defaults to \code{elasticity = 1}).} + +\item{maxYear=2100}{A numeric value indicating the maximum year for the analysis. The range for \code{maxYear} is \verb{[2011, 2300]}. Defaults to \code{maxYear = 2100}.} + +\item{thru2300=FALSE}{A \code{ TRUE/FALSE} shortcut that overrides the \code{maxYear} argument to run the model to 2300. Defaults to \code{thru2300 = FALSE}.} + +\item{outputList=FALSE}{A \code{ TRUE/FALSE} value indicating whether to output results as a data frame object (\code{outputList = FALSE}, default) or to return a list of objects (\code{outputList = TRUE}) that includes information about model provenance (including input arguments and input scenarios) along with the data frame of results.} + +\item{allCols=FALSE}{A \code{TRUE/FALSE} value indicating whether to include intermediate column values in results (e.g., physical and economic multipliers). Used in testing. Defaults to \code{allCols = FALSE}).} +} +\value{ +If \code{outputList=FALSE}, the output of \code{run_fredi_methane()} is a data frame object (described above) containing annual physical and economic impacts over the analysis period, for each region, state, and model. + +If \code{outputList=TRUE}, \code{run_fredi_methane()} returns a list object containing the following: +\itemize{ +\item \strong{\code{statusList}}. A list with values for the arguments passed to \code{run_fredi_methane()} (including defaults if unspecified). +\item \strong{\code{argsList}}. A list with elements named after \code{run_fredi_methane()} arguments, containing the values of the arguments passed to \code{run_fred_methane()} (or default values if unspecified). +\item \strong{\code{scenarios}}. A list with named elements \code{gdp} and \code{pop} and \code{o3} or \code{ch4} and \code{nox} -- each containing the scenarios for GDP, population, and ozone or methane and NOx as used by the model in calculating impacts. +\item \strong{\code{results}}. Containing a data frame of annual physical and economic impacts (i.e., the same data frame returned if \code{outputList = FALSE}). +} +} +\description{ +This function allows users to estimate mortality impacts from changes to ozone concentrations driven by changes in methane concentrations and (optionally) NOx emissions in the atmosphere. +} +\details{ +This function allows users to estimate mortality impacts from changes to ozone concentrations driven by changes in methane concentrations, and (optionally) NOx emissions. + +Users can specify an optional list of custom scenarios with \code{inputsList} (for more information on the format of inputs, see \code{\link[=import_inputs]{import_inputs()}}). The function \code{\link[=import_inputs]{import_inputs()}} can be used to importing custom scenarios from CSV files. \code{\link[=import_inputs]{import_inputs()}} returns a list with named elements \code{gdp}, \code{pop}, \code{o3}, \code{ch4}, and/or \code{nox}, with each respectively containing a data frame with a custom scenario for GDP, state-level population, change in ozone concentration, change in methane concentration, and NOx emissions. If a user imports scenarios using \code{\link[=import_inputs]{import_inputs()}}, they can pass the outputs of \code{\link[=import_inputs]{import_inputs()}} directly to the \code{run_fred_methane()} argument \code{inputsList}. Note that the documentation for \code{\link[=import_inputs]{import_inputs()}} can also provide additional guidance and specification on the formats for each scenario type. + +Otherwise, \code{run_fred_methane()} looks for a list object passed to the argument \code{inputsList}. Within that list, \code{run_fred_methane()} looks for named list elements -- \code{gdp}, \code{pop}, \code{o3}, \code{ch4}, and/or \code{nox} -- with each respectively containing a data frame with a custom scenario for GDP, state-level population, ozone concentration, methane concentration, and/or NOx concentration. If \code{inputsList = NULL} or \code{inputsList = list()} (default), \code{run_fred_methane()} uses default trajectories for GDP, population, ozone concentration, methane concentration, and/or NOx concentration. \code{run_fred_methane()} will default back to the default scenarios for any list elements that empty or \code{NULL} (in other words, running \code{run_fredi(inputsList = list())} returns the same outputs as running \code{run_fred_methane()}). See \link{gdpDefault}, \link{popDefault} for more information about the default GDP and population scenarios. Default scenarios for ozone, methane, and NOx are described in more detail below. +\itemize{ +\item \strong{GDP Inputs.} The input scenario for gross domestic product (GDP) requires national GDP values in 2015$. GDP values must be greater than or equal to zero. +\itemize{ +\item \code{gdp} requires a data frame object with two columns with names \code{"year"}, and \code{"gdp_usd"} containing the year and the national GDP, respectively. GDP values must be greater than or equal to zero. +\item GDP inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). Note that the minimum year for the GDP scenario is different from that for \code{\link[=run_fredi]{run_fredi()}}, because \code{run_fredi_methane()} is only available starting in 2020. +\item If the user does not specify an input scenario for GDP (i.e., \code{inputsList = list(gdp = NULL)}, \code{run_fred_methane()} uses a default GDP scenario. +} +\item \strong{Population Inputs.} The input population scenario requires state-level population values(national-, CONUS-, or region-level population values can be converted to state-level population by immporting inputs using the \code{\link[=import_inputs]{import_inputs()}} function). Population values must be greater than or equal to zero. +\itemize{ +\item \code{pop} requires a data frame object with five columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"year"}, and \code{"pop"} containing the region name (one of \code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"} for CONUS states, or \code{"Alaska"} and \code{"Hawaii"} for Alaska and Hawaii, respectively), the state name, the two-character postal code abbreviation for the state, the year, and the state population, respectively. +\item Population inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). Note that the minimum year for the GDP scenario is different from that for \code{\link[=run_fredi]{run_fredi()}}, because \code{run_fredi_methane()} is only available starting in 2020. +\item If the user does not specify an input scenario for population (i.e., \code{inputsList = list(pop = NULL)}, \code{run_fred_methane()} uses a default population scenario. +} +\item \strong{Ozone Inputs.} The input ozone scenario requires changes in annual state-level ozone concentrations, by GCM model, in parts per trillion by volume (pptv) relative to a 1986-2005 baseline era. In other words, the input ozone scenario requires ozone concentrations specific to the state, GCM model, and year of the analysis. +\itemize{ +\item \code{o3} requires a data frame object with six columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"model"}, \code{"year"}, and \code{"O3_pptv"} containing the region name (\code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"} for CONUS states, or \code{"Alaska"} and \code{"Hawaii"} for Alaska and Hawaii, respectively), the state name, the two-character postal code abbreviation for the state, the GCM model name (\code{"CanESM2"}, \code{"GFDL-CM3"}, \code{"GISS-E2-R"}, \code{"HadGEM2-ES"}, and/or \code{"MIROC5"}), the year, and the change in ozone concentration (in pptv) relative to a 1986-2005 baseline era. +\item Ozone inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). +\item If inputs are specified for ozone \emph{and} methane or NOx (i.e., \code{!is.null(inputsList$o3) & (!is.null(inputsList$ch4) | !is.null(inputsList$nox))}), \code{run_fredi_methane()} will use the ozone scenario in preference of the methane and NOx scenario. +} +\item \strong{Methane Inputs.} The input methane scenario requires changes in annual methane concentrations, at the national level, in parts per billion by volume (ppbv) relative to a 1986-2005 baseline era. +\itemize{ +\item \code{ch4} requires a data frame object with two columns with names \code{"year"} and \code{"CH4_ppbv"} containing the year and the change in methane concentration (in ppbv) relative to a 1986-2005 baseline era. +\item Methane inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). +\item \code{run_fredi_methane()} will override a user-supplied methane scenario with a user-supplied ozone scenario; in other words, \code{run_fredi_methane()} will use the ozone scenario in preference of the methane and NOx scenario. +} +\item \strong{NOx Inputs.} The input NOx scenario requires annual NOx emissions in the US, at the national level, in Megatons (MT) relative to a 1986-2005 baseline. +\itemize{ +\item \code{nox} requires a data frame object with two columns with names \code{"year"} and \code{"NOx_Mt"} containing the year and the change in NOx concentration (in Mt) relative to a 1986-2005 baseline era. +\item NOx inputs must have at least one non-missing value in 2020 or earlier and at least one non-missing value in or after the final analysis year (as specified by \code{maxYear}). +\item \code{run_fredi_methane()} will override a user-supplied methane scenario with a user-supplied ozone scenario; in other words, \code{run_fredi_methane()} will use the ozone scenario in preference of the methane and NOx scenario. +} +} + +If inputs are specified for ozone \emph{and} methane or NOx (i.e., \code{!is.null(inputsList$o3) & (!is.null(inputsList$ch4) | !is.null(inputsList$nox))}), \code{run_fredi_methane()} will use the ozone scenario in preference of the methane and NOx scenario. If no ozone, methane, or NOx scenario are provided (i.e., \code{inputsList$o3}, \code{inputsList$ch4}, and \code{inputsList$nox} are all \code{NULL}), \code{run_fredi_methane()} will use the default ozone scenario to calculate impacts. However, if a user provides an input scenario for methane or NOx (i.e., either \code{inputsList$ch4} or \code{inputsList$nox} are not \code{NULL}) but no ozone scenario is provided (i.e., \code{inputsList$o3} is \code{NULL}), then \code{run_fredi_methane()} will use the methane and NOx scenarios (if either of those inputs is missing, \code{run_fredi_methane()} will use the corresponding default scenario). + +To calculate the change in ozone concentrations when using methane and NOx scenarios, \code{run_fredi_methane()} follows the approach described in EPA (Forthcoming): +\enumerate{ +\item First, \code{run_fredi_methane} calculates values for the change in ozone concentration (in pptv) by multiplying values for a given change in methane concentrations (in ppbv) by a state- and model-specific ozone response matrix (with values in units of concentrations of ozone in pptv relative to concentrations of methane in ppbv). +\item Second, \code{run_fredi_methane} calculates values for NOx factor (\code{NOxFactor}) from the NOx concentrations in Mt (\code{NOX_Mt}), using the equation \verb{NOxFactor = (log(NOX_Mt) \\* k1 + k0) \\* 1e3/556} (where \code{k0} and \code{k1} are coefficients with values of \code{-1.12} and \code{-0.49}, respectively). Note that methane module currently uses the GCM average values for the US, though GCM-specific values are available and could be added in future revisions. +\item Third, \code{run_fredi_methane} calculates a NOx ratio (\code{NOxRatio = NOxFactor / NOxFactor0}) by dividing the NOx factor values (\code{NOxFactor}) from Step 2 by a reference NOx factor (\code{NOxFactor0=-4.088991}), where the value for \code{NOxFactor0} was calculated for a reference NOx concentration (\code{NOX_Mt0=10.528}) using the equation from Step 2. +\item Fourth, \code{run_fredi_methane} adjusts the values for change in ozone concentration from Step 1 by the NOx ratio from Step 3. +} + +\code{run_fredi_methane} uses the following default scenarios: +\itemize{ +\item \strong{Methane}. The methane default scenario, \code{ch4Default}, uses a constant value of \code{CH4_ppbv=100} for change in methane concentration (in ppbv) for the years 2020 through 2100. See \link{ch4Default} for more information on the default scenario. Note that the temperature scenario used to produce this default methane scenario differs from the default temperature scenario used in main \code{FrEDI} (\code{\link[=run_fredi]{run_fredi()}}) and the \code{FrEDI} SV module (\code{\link[=run_fredi_sv]{run_fredi_sv()}}). +\item \strong{NOx}. The NOx default scenario, \code{noxDefault}, uses a constant value of \code{NOx_Mt=10.528} for change in NOx concentration (in Mt) for the years 2020 through 2100. +\item \strong{Ozone}. The ozone default scenario, \code{o3Default}, uses state- and GCM-specific constant values for change in ozone concentration (\code{O3_pptv} in pptv) for the years 2020 through 2100, as calculated from the default methane and NOx scenarios using the approach described above. +} + +\code{run_fredi_methane()} linearly interpolates missing annual values for all input scenarios using non-missing values (each scenario requires at least two non-missing values as detailed above for each scenario type). After interpolation of the input scenarios, \code{run_fredi_methane()} subsets the input scenarios to values within the analysis period (years above 2020 and ending in the year specified by \code{maxYear}). + +By default, \code{run_fredi_methane()} calculates impacts starting in the year 2020 and ending in 2100. Specify an alternative end year for the analysis using the \code{maxYear} argument. \code{maxYear} has a default value of \code{2100} and minimum and maximum values of \code{2020} and \code{2300}, respectively. Alternatively, users can set argument \code{thru2300 = TRUE} to override the \code{maxYear} argument and set \code{maxYear = 2300}. Note that the default scenarios included within \link{FrEDI} stop in the year 2100; users must provide custom input scenarios out to the desired end year \strong{and} specify a \code{maxYear >= 2100} (and \code{maxYear <= 2300}) in order to return non-missing values for years after 2100. + +\code{run_fredi_methane()} calculates national population from state population values and then calculates GDP per capita from values for GDP and national population. Values for state population, national population, national GDP (in 2015$), and national per capita GDP (in 2015$/capita) are provided in the results data frame in columns \code{"pop"}, \code{"national_pop"}, \code{"gdp_usd"}, and \code{"gdp_percap"}, respectively. \code{run_fredi_methane()} converts the physical impacts (excess deaths) to an economic impact using a Value of Statistical Life (VSL) approach. VSL values are adjusted over time by scaling GDP per capita (relative to CONUS population) relative to a reference GDP per capita. For more information, refer to EPA (2021). + +The process used by the methane module to calculate physical impacts (excess respiratory deaths) from ozone is as follows: +\enumerate{ +\item \code{run_fredi_methane()} estimates a time-dependent national respiratory mortality rate (in deaths per capita) from national population values relative to a reference population. +\item State-level respiratory mortality (deaths) is then calculated by the national respiratory mortality rate by state population. +\item \code{run_fredi_methane()} then calculates a state-level respiratory mortality ratio by dividing the state-level respiratory mortality by a reference respiratory mortality. +\item \code{run_fredi_methane()} also calculates a state- and model-specific ozone ratio by dividing the change in ozone concentration values in pptv by reference values. +\item To calculate the number of excess respiratory mortality due to ozone, \code{run_fredi_methane()} multiplies the state- and model-specific baseline values for excess respiratory mortality by the state-level respiratory mortality ratio and the state- and model-specific ozone ratio. These +} + +To calculate the economic impacts of excess respiratory deaths from ozone, \code{run_fredi_methane()} multiplies the physical impacts by VSL adjusted for GDP and population, as described above. + +If \code{outputList = FALSE} (default), \code{run_fredi_methane()} returns a data frame of annual physical and economic impacts over the analysis period, for each region, state, and model. If \code{outputList = TRUE}, in addition to the data frame of impacts, \code{run_fred_methane()} returns a list object containing information about values for function arguments and scenarios for GDP, population, and ozone or methane and NOx. +} +\examples{ +### Load FrEDI +require(FrEDI) + +### Load population and GDP scenarios and glimpse data +data("popDefault"); popDefault |> glimpse() +data("gdpDefault"); gdpDefault |> glimpse() + + +### Run FrEDI methane with O3 inputs +example1 <- run_fredi_methane(inputsList=list(gdp=gdpDefault, pop=popDefault, o3=o3Default)) + +### Run FrEDI methane with methane inputs +example1 <- run_fredi_methane(inputsList=list(gdp=gdpDefault, pop=popDefault, ch4=ch4Default)) + +### Run FrEDI methane with methane and NOx inputs +example1 <- run_fredi_methane(inputsList=list(gdp=gdpDefault, pop=popDefault, ch4=ch4Default, nox=noxDefault)) + + +} +\references{ +Environmental Protection Agency (EPA). (Forthcoming). Technical Documentation on The Framework for Evaluating Damages and Impacts (FrEDI). Technical Report EPA 430-R-21-004, EPA, Washington, DC. Available at \url{https://epa.gov/cira/FrEDI/}. +} diff --git a/man/run_fredi_sv.Rd b/man/run_fredi_sv.Rd index 496cea2..7a373cd 100644 --- a/man/run_fredi_sv.Rd +++ b/man/run_fredi_sv.Rd @@ -6,8 +6,7 @@ \usage{ run_fredi_sv( sector = NULL, - driverInput = NULL, - popInput = NULL, + inputsList = list(pop = NULL, temp = NULL, slr = NULL), silent = TRUE, .testing = FALSE ) @@ -15,18 +14,24 @@ run_fredi_sv( \arguments{ \item{sector}{A character string indicating the sector for which the FrEDI SV module should calculate impacts (see \code{\link[=get_sv_sectorInfo]{get_sv_sectorInfo()}} for a list of available sectors).} -\item{driverInput}{A data frame of up to four custom scenarios for drivers (temperature or global mean sea level rise). \code{driverInput} requires a data frame with columns of \code{"year"} and \code{"scenario"}. The data frame must also include a third column: \code{"temp_C"} for temperature-driven sectors (containing temperature values in degrees Celsius of warming for the contiguous U.S.) or \code{"slr_cm"} for sea level rise (SLR)-driven sectors (containing values for global mean sea level rise in centimeters). Run \code{get_sv_sectorInfo(gcmOnly=TRUE)} to see temperature-driven sectors in the SV module and \code{get_sv_sectorInfo(slrOnly=TRUE)} to see SLR-driven scenarios. Users can also pass a data frame with all four columns (\code{"year"}, \code{"scenario"}, \code{"temp_C"}, and \code{"slr_cm"}), in which case \code{\link[=run_fredi_sv]{run_fredi_sv()}} determines whether to use the \code{"temp_C"} or \code{"slr_cm"} column as the driver trajectory based on the specified sector. Driver inputs for all scenarios should start in the year 2000 or earlier. All scenarios must include at least two non-missing values (especially values before or at 2000 and at or after 2100). If any required columns are missing, \code{\link[=run_fredi_sv]{run_fredi_sv()}} will use the default temperature or sea level rise scenario from \code{\link[=run_fredi]{run_fredi()}}. If the data frame passed to \code{driverInput} has more than four unique scenarios, \code{\link[=run_fredi_sv]{run_fredi_sv()}} will only run the first four scenarios.} +\item{silent}{A logical (\code{TRUE/FALSE}) value indicating the level of messaging desired by the user (defaults to \code{silent=TRUE})} -\item{popInput}{The input population scenario requires a data frame object with a single scenario of state-level population values. +\item{inputsList=list(pop=NULL, temp=NULL, slr=NULL)}{A list with named elements (\code{pop}, \code{temp}, and/or \code{slr}), each containing data frames of custom scenarios for state-level population, temperature, and/or global mean sea level rise (GMSL) trajectories, respectively, over a continuous period. Temperature and sea level rise inputs should start in 2000 or earlier. Values for population scenarios can start in 2010 or earlier. Values for each scenario type must be within reasonable ranges. For more information, see \code{\link[=import_inputs]{import_inputs()}}. \itemize{ -\item The population scenario must have five columns with names \code{"year"}, \code{"region"}, \code{"state"}, \code{"postal"}, and \code{"state_pop"} containing the year, the NCA region name, the state name, the postal code abbreviation (e.g., "ME" for "Maine") for the state, and the state population, respectively. -\item \code{popInput} only accepts a a single scenario, in contrast to \code{driverInput}. In other words, \code{\link[=run_fredi_sv]{run_fredi_sv()}} uses the same population scenario for any and all driver scenarios passed to \code{driverInput}. -\item If the user does not specify an input scenario for population (i.e., \code{popInput = NULL}, \code{\link[=run_fredi_sv]{run_fredi_sv()}} uses a default population scenario. +\item \strong{pop}. The input population scenario requires a data frame object with a single scenario of population values for each of the 48 U.S. states and the District of Columbia comprising the contiguous U.S. (CONUS). +\itemize{ +\item The population scenario must have five columns with names \code{"region"}, \code{"state"}, \code{"postal"}, \code{"year"}, and \code{"_pop"} containing the NCA region name (\code{"Midwest"}, \code{"Northeast"}, \code{"Northern Plains"}, \code{"Northwest"}, \code{"Southeast"}, \code{"Southern Plains"}, or \code{"Southwest"}), the state name, the two-letter postal code abbreviation for the state (e.g., \code{"ME"} for Maine), the year, and the state population, respectively. +\item The input population scenario can only contain a single scenario, in contrast to values for temperature or SLR inputs. In other words, \code{\link[=run_fredi_sv]{run_fredi_sv()}} uses the same population scenario when running any and all of the temperature or SLR scenarios passed to \code{run_fredi_sv()}. +\item If the user does not specify an input scenario for population (i.e., \code{popInput = NULL}, \code{\link[=run_fredi_sv]{run_fredi_sv()}} uses a default population scenario (see documentation for \link{popScenario}). \item Population inputs 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 (2100). \item Population values must be greater than or equal to zero. +} +\item \strong{temp} or \strong{slr}. The input temperature or SLR scenario should be a data frame containing one or more custom scenarios. These inputs should be formulated similarly to those for \code{\link[=run_fredi]{run_fredi()}} and \code{\link[=import_inputs]{import_inputs()}}, with an additional column (\code{scenario}) indicating the unique scenario identifier. Temperature and/or SLR input scenarios must have at least one non-missing value in the year 2000 or earlier and at least one non-missing value in or after the final analysis year (2100). +\itemize{ +\item \strong{temp}. Temperature inputs are used by \code{run_fredi_sv()} with temperature-driven sectors; run \code{get_sv_sectorInfo(gcmOnly=TRUE)} to get a list of the temperature-driven sectors available for the SV module. Temperature inputs require a data frame with columns of \code{year}, \code{temp_C}, and \code{scenario}, respectively containing the year associated with an observation, temperature values for CONUS in degrees Celsius of warming relative to a 1995 baseline (where 1995 is the central year of a 1986-2005 baseline period -- i.e., values should start at zero in the year 1995), and a unique scenario identifier. If no temperature scenario is specified (i.e., \code{inputsList$temp} is \code{NULL}) when running a temperature-driven sector, \code{run_fredi_sv()} will use a default temperature scenario (see \link{FrEDI:gcamScenarios}). +\item \strong{slr}. SLR inputs are used by \code{run_fredi_sv()} with sea level rise-driven sectors; run \code{get_sv_sectorInfo(slrOnly=TRUE)} to get a list of the SLR-driven sectors available for the SV module. SLR inputs require a data frame with columns of \code{year}, \code{slr_cm}, and \code{scenario}, respectively containing the global mean sea level rise in centimeters relative to a 2000 baseline (i.e., values should start at zero in the year 2000), and a unique scenario identifier. If no SLR scenario is specified (i.e., \code{inputsList$slr} is \code{NULL}) when running a temperature-driven sector: if a user has supplied a temperature scenario (i.e., \code{inputsList$temp} is not \code{NULL}), \code{run_fredi_sv()} will calculate sea level rise values from the temperature inputs using the \code{\link[=temps2slr]{temps2slr()}} function; if no temperature scenario is provided, \code{run_fredi_sv} will use a default SLR scenario (see \link{FrEDI:gcamScenarios}). +} }} - -\item{silent}{A logical (\code{TRUE/FALSE}) value indicating the level of messaging desired by the user (defaults to \code{silent=TRUE}).} } \value{ The output of \code{\link[=run_fredi_sv]{run_fredi_sv()}} is an R data frame object containing average annual physical impacts for socially vulnerable groups, at the NCA region level and five-year increments. @@ -40,22 +45,6 @@ The output of \code{\link[=run_fredi_sv]{run_fredi_sv()}} is an R data frame obj Users can run \code{\link[=run_fredi_sv]{run_fredi_sv()}} to generate annual physical impacts for SV groups for individual sectors. When running \code{\link[=run_fredi_sv]{run_fredi_sv()}}, users must specify one of the sectors in the SV module; use \code{\link[=get_sv_sectorInfo]{get_sv_sectorInfo()}} for a list of available sectors. \code{\link[=run_fredi_sv]{run_fredi_sv()}} can be run with default population and climate (temperature and SLR) trajectories or use \code{\link[=run_fredi_sv]{run_fredi_sv()}} to run custom scenarios. Running \code{\link[=run_fredi_sv]{run_fredi_sv()}} with custom climate scenarios requires passing a data frame of scenarios to the \code{driverInput} argument. \code{\link[=run_fredi_sv]{run_fredi_sv()}} can also be run with a custom population scenario by passing a data frame of regional population trajectories to the \code{popInput} argument; unlike climate scenarios, \code{\link[=run_fredi_sv]{run_fredi_sv()}} will only run a single scenario at a time. -\itemize{ -\item \code{driverInput} can take a data frame containing up to four custom scenarios for drivers (temperature or global mean sea level rise). \code{driverInput} requires a data frame with columns of \code{"year"} and \code{"scenario"}. The data frame must also include a third column: \code{"temp_C"} for temperature-driven sectors (containing temperature values in degrees Celsius of warming for the contiguous U.S.) or \code{"slr_cm"} for sea level rise (SLR)-driven sectors (containing values for global mean sea level rise in centimeters). Run \code{get_sv_sectorInfo(gcmOnly = TRUE)} to see temperature-driven sectors in the SV module and \code{get_sv_sectorInfo(slrOnly = TRUE)} to see SLR-driven scenarios. Users can also pass a data frame with all four columns (\code{"year"}, \code{"scenario"}, \code{"temp_C"}, and \code{"slr_cm"}), in which case \code{\link[=run_fredi_sv]{run_fredi_sv()}} determines whether to use the \code{"temp_C"} or \code{"slr_cm"} column as the driver trajectory based on the specified sector. If any required columns are missing, \code{\link[=run_fredi_sv]{run_fredi_sv()}} will use the default temperature or sea level rise scenario from \code{\link[=run_fredi]{run_fredi()}}. If the data frame passed to \code{driverInput} has more than four unique scenarios, \code{\link[=run_fredi_sv]{run_fredi_sv()}} will only run the first four scenarios. -\itemize{ -\item Temperature inputs must be temperature change in degrees Celsius for the contiguous U.S. (use \code{\link[=convertTemps]{convertTemps()}} to convert global temperatures to CONUS temperatures before passing to \code{driverInput}) relative to a 1995 baseline (where 1995 is the central year of a 1986-2005 baseline period; values should start at zero in the year 1995). -\item Sea level rise inputs must be in centimeters relative to a 2000 baseline (i.e., values should start at zero in the year 2000). Driver inputs for all scenarios should start in the year 2000 or earlier. All scenarios must include at least two non-missing values (especially values before or at 2000 and at or after 2100). -} -\item The input population scenario requires a data frame object with a single scenario of state-level population values. -\itemize{ -\item The population scenario must have five columns with names \code{"year"}, \code{"region"}, \code{"state"}, \code{"postal"}, and \code{"state_pop"} containing the year, the NCA region name, the state name, the postal code abbreviation (e.g., "ME" for "Maine") for the state, and the state population, respectively. -\item \code{popInput} only accepts a a single scenario, in contrast to \code{driverInput}. In other words, \code{\link[=run_fredi_sv]{run_fredi_sv()}} uses the same population scenario for any and all driver scenarios passed to \code{driverInput}. -\item If the user does not specify an input scenario for population (i.e., \code{popInput = NULL}, \code{\link[=run_fredi_sv]{run_fredi_sv()}} uses a default population scenario. -\item Population inputs 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 (2100). -\item Population values must be greater than or equal to zero. -The default regional population scenario is drawn from the Integrated Climate and Land Use Scenarios version 2 (ICLUSv2) model (Bierwagen et al, 2010; EPA 2017) under the Median variant projection of United Nations (United Nations, 2015). Note that the FrEDI SV default population scenario differs from the default population scenario used by \code{\link[=run_fredi]{run_fredi()}}. -} -} The output of \code{\link[=run_fredi_sv]{run_fredi_sv()}} is an R data frame object containing average annual physical impacts for socially vulnerable groups, at the NCA region level and five-year increments. } @@ -76,13 +65,21 @@ df_sv <- run_fredi_sv(sector="Coastal Properties") df_sv <- run_fredi_sv(sector="Extreme Temperature") ### Load temperature scenarios -load(gcamScenarios) +data(gcamScenarios) ### Load population scenario -load(popScenario) +data(popScenario) ### Run SV Module for "Extreme Temperature" with custom population and temperature scenarios -df_sv <- run_fredi_sv(sector = "Extreme Temperature", driverInput = gcamScenarios, popInput = popScenario) +df_sv <- run_fredi_sv(sector = "Extreme Temperature", inputsList=list(pop=popScenario, temp=gcamScenarios) + +### Run SV Module for "Coastal Properties" with custom population and SLR scenarios +df_sv <- run_fredi_sv(sector = "Coastal Properties", inputsList=list(pop=popScenario, slr=gcamScenarios) + +### Run SV Module for "Coastal Properties" with custom population and temperature scenarios +df_sv <- run_fredi_sv(sector = "Coastal Properties", inputsList=list(pop=popScenario, temp=gcamScenarios) + + } \references{