Merge pull request #143 from USEPA/state_level_updateFunctionDoc

State level update function doc

.github/workflows/build_fredi.yml

@@ -40,31 +40,34 @@ jobs:
           rm *.tar.gz
 
 
-      - name: Run create_DoW_results
+      - name: Build Package
         run: |
           Rscript -e '
-          ### Main repo path, FrEDI project path, scripts path
-          rPath0   <- ".";
-          pPath0   <- rPath0 |> file.path("FrEDI")
-          oPath0   <- pPath0 |> file.path("data", "defaultResults.rda")
+            ### Main repo path, FrEDI project path, scripts path
+            rPath0   <- ".";
+            pPath0   <- rPath0 |> file.path("FrEDI")
+            # oPath0   <- pPath0 |> file.path("data", "defaultResults.rda")
 
-          ###### Create Default Results ######
-          pPath0 |> devtools::load_all()
-          defaultResults <- run_fredi()
-          save(defaultResults, file=oPath0))
+            ###### Create Default Results ######
+            # pPath0 |> devtools::load_all()
+            # defaultResults <- run_fredi()
+            # save(defaultResults, file=oPath0)
 
-          ###### Update Documentation ######
-          ###### - Build Manual
-          ###### - Add and build vignettes
-          ###### - Generate Documentation
-          roxygen2::roxygenise(pPath0)
-          devtools::document(pkg = pPath0)
-          # devtools::build_manual(pkg = pPath0)
-          # devtools::build_vignettes(pkg = pPath0)
+            ###### Update Documentation ######
+            ###### - Build Manual
+            ###### - Add and build vignettes
+            ###### - Generate Documentation
+            roxygen2::roxygenise(pPath0)
+            devtools::document(pkg = pPath0)
+            # devtools::build_manual(pkg = pPath0)
+            # devtools::build_vignettes(pkg = pPath0)
+
+            ###### Build Package ######
+            ###### - Build Package but do not include vignettes
+            # devtools::build(pkg=pPath0, path=rPath0)
+            # pPath0 |> print()
+            devtools::build(pkg=pPath0)
 
-          ###### Build Package ######
-          ###### - Build Package but don't include vignettes
-          devtools::build(pkg=pPath0, path=rPath0)
           '
 
 
@@ -73,6 +76,7 @@ jobs:
           git config --local core.autocrlf false
           git config --local user.email "${{ github.actor }}@users.noreply.github.com"
           git config --local user.name  "${{ github.actor }}"
+          git add FrEDI/data/defaultResults.rda
           git add *.tar.gz
           git pull origin ${{ github.head_ref }} --autostash --rebase -X ours
           git commit -a -m "New package build"

FrEDI/DESCRIPTION

@@ -1,6 +1,6 @@
 Package: FrEDI
 Title: The Framework for Evaluating Damages and Impacts (FrEDI)
-Version: 3.4
+Version: 4.0
 Authors@R: c(person("Corinne", "Hartin",
                     email   = "[email protected]",
                     role    = c("aut","cre"),
@@ -31,7 +31,8 @@ Description: This R package models damages and impacts from climate change in th
     implement FrEDI for projecting impacts from climate change and sea level rise for a selected set of 
     sectors. Version 3 and above includes a module for estimating impacts on socially vulnerable populations for 
     select sectors. Versions > 3.3.0 extend calculations out to 2300 to facilitate the calculation of Net Present Values 
-    (NPV) but only contains default values through 2090--users must provide their own inputs through 2300. 
+    (NPV) but only contains default values through 2090--users must provide their own inputs through 2300. Versions 4.0 and 
+    above calculate values at the state-level for most sectors.  
 License: file LICENSE
 Encoding: UTF-8
 Depends: R (>= 3.5.0),

FrEDI/NAMESPACE

@@ -2,7 +2,6 @@
 
 export(aggregate_impacts)
 export(convertTemps)
-export(get_plots)
 export(get_sectorInfo)
 export(get_sv_sectorInfo)
 export(import_inputs)

FrEDI/R/FrEDI.R

@@ -57,7 +57,7 @@
 #' By submitting a pull request to the GitHub and/or by installing this package, you make an agreement with EPA that you will not submit a claim of compensation for services rendered to EPA or any other federal agency. Further, you agree not to charge the time you spend developing software code related to this project to any federal grant or cooperative agreement.
 #'
 #'
-#' @docType package
+#' @docType _PACKAGE
 #' @name FrEDI
 #' @md
 NULL

FrEDI/R/aggregate_impacts.R

@@ -6,37 +6,40 @@
 #' Summarize and aggregate impacts from FrEDI (calculate national totals, average across models, sum impact types, and interpolate between impact estimate years).
 #'
 #' @param data      Data frame of results FrEDI (outputs from [FrEDI::run_fredi()])
-#' @param columns   Character vector of columns for which to aggregate results (defaults to `columns=c("annual_impacts"`)).
-#' @param aggLevels Levels of aggregation at which to summarize data: one or more of `c("national", "modelAverage", "impactYear", "impactType", "all")`. Defaults to all levels (i.e., `aggLevels="all"`).
-#' @param groupByCols Character vector indicating which columns to use for grouping. Defaults to `groupByCols=c("sector", "variant", "impactYear", "impactType", "model_type", "model", "region")`. Note that the `"variant"` column referred to below contains information about the variant (or adaptation) name or `“N/A”`, as applicable.
+#' @param columns   Character vector of columns for which to aggregate results (defaults to `columns=c( "physical_impacts", "annual_impacts")`).
+#' @param aggLevels Levels of aggregation at which to summarize data: one or more of `c( "national", "modelAverage", "impactYear", "impactType", "all" )`. Defaults to all levels (i.e., `aggLevels="all"`). Note that, if `"impacttype"` is in `aggLevels` (e.g., `aggLevels= "all"`), column `"physical_measure"` is dropped from the `groupByCols` and column `"physical_impacts"` is dropped from `columns`. This is because aggregating over impact types for some sectors requires summing costs over different types of physical impacts, so reporting the physical impacts would be nonsensical.
+#' @param groupByCols Character vector indicating which columns to use for grouping. Defaults to `groupByCols=c( "sector", "variant", "impactYear", "impactType", "model_type", "model", "sectorprimary", "includeaggregate", "physicalmeasure", "region", "state", "postal" )`. Note that the `"variant"` column referred to below contains information about the variant or adaptation name (or `“N/A”`), as applicable.
 #'
 #' @details
-#' This post-processing helper function aggregates and summarizes the FrEDI results to levels of aggregation specified by the user (passed to `aggLevels`). Users can specify a single aggregation level or multiple aggregation levels by passing a single character string or character vector to `aggLevels`. Options for aggregation include calculating national totals (`aggLevels="national"`), averaging across model types and models (`aggLevels="modelAverage"`), summing over all impact types (`aggLevels="impactType"`), and interpolating between impact year estimates (`aggLevels="impactYear"`). Users can specify all aggregation levels at once by specifying `aggLevels="all"` (default).
-#' This post-processing helper function aggregates and summarizes temperature binning results to levels of aggregation specified by the user (passed to `aggLevels`). Users can specify a single aggregation level or multiple aggregation levels by passing a single character string or character vector to `aggLevels`. Options for aggregation include calculating national totals (`aggLevels="national"`), averaging across model types and models (`aggLevels="modelaverage"`), summing over all impact types (`aggLevels="impacttype"`), and interpolate between impact year estimates (`aggLevels="impactyear"`). Users can specify all aggregation levels at once by specifying `aggLevels="all"` (default) or no aggregation levels (`aggLevels="none"`).
+#' This function can be used to aggregate and summarize the FrEDI results to levels of aggregation specified by the user (passed to `aggLevels`). Users can specify all aggregation levels at once by specifying `aggLevels= "all"` (default) or no aggregation levels (`aggLevels= "none"`). Users can specify a single aggregation level or multiple aggregation levels by passing a single character string or character vector to `aggLevels`. Options for aggregation include calculating national totals (`aggLevels= "national"`), averaging across model types and models (`aggLevels= "modelAverage"`), summing over all impact types (`aggLevels= "impactType"`), and interpolating between impact year estimates (`aggLevels= "impactYear"`).
 #'
-#' Before aggregating impacts for national totals and/or model averages, [FrEDI::aggregate_impacts()] will drop any pre-summarized results  (i.e., values for which `region="National Total"` and/or for which `model="average"`, respectively) that are already present in the data `and then reaggregate at those levels.
 #'
-#' For each of the `aggLevels`, [FrEDI::aggregate_impacts()] performs the following calculations (note that the `"variant"` column referred to below contains information about the variant (or adaptation) name or `“N/A”`, as applicable):
+#' Before aggregating impacts for national totals and/or model averages, [FrEDI::aggregate_impacts()] will drop any pre-summarized results (i.e., values for which `region= "National Total"` and/or for which `model= "Average"`, respectively) that are already present in the data and then re-summarize results at those respective levels.
+#'
+#' If users specify `aggLevels= "none"`, [FrEDI::aggregate_impacts()] returns the data frame passed to the `data` argument.
+#'
+#' If users specify `aggLevels= "all"` or other combinations of aggregation levels, the [FrEDI::aggregate_impacts()] function uses performs the following calculations using the grouping columns specified by the `groupByCols` argument: `"sector"`, `"variant"`, `"impactType"`, `"impactYear"`, `"region"`, `"state"`, `"postal"`, `"model_type"`, `"model"`, `"sectorprimary"`, `"includeaggregate"`, `"physicalmeasure"`, and `"year"`.
 #'
 #' \tabular{ll}{
 #' \strong{Aggregation Level} \tab \strong{Description} \cr
-#' `national` \tab Annual values are summed across all regions present in the data. I.e., data is grouped by columns `"sector"`, `"variant"`, `"impactType"`,  `"impactYear"`, `"model_type"`, `"model"`, and `"year"`) and summed across regions. Years which have missing column data for all regions return as `NA`. The rows of the data frame of national values (with column `region="National Total"`) are then added as rows to the results. \cr
-#' `modelaverage` \tab For temperature-driven sectors, annual results are averaged across all GCM models present in the data. I.e., data is grouped by columns `"sector"`, `"variant"`, `"impactType"`, `"impactYear"`, `"model_type"`, `"region"`, and `"year"` and averaged across models (SLR impacts are estimated as an interpolation between SLR scenarios). Averages exclude missing values. Years which have missing column data for all models return as `NA`. The rows of model averages (with column `model="Average"` are then added as rows to the results data frame. \cr
-#' `impacttype` \tab Annual results are summed across all impact types by sector present in the data. I.e., data is grouped by columns `"sector"`, `"variant"`, `"impactType"`, `"impactYear"`,`"model_type"`, `"model"`, `"region"`, and `"year"` and summed across impact types. Mutates column `impactType="all"` for all values. Years which have missing column data for all impact types return as `NA`. If results are aggregated across impact types, information about physical impacts (columns `"physicalmeasure"` and `"physical_impacts"`) are dropped.\cr
-#' `impactyear` \tab Annual results for sectors with only one impact year estimate (i.e., `impactYear = "N/A"`) are separated from those with multiple impact year estimates. Sectors with multiple impact years have separate results for impact years 2010 and 2090. For these sectors, annual results are linearly interpolated between impact year estimates. For any model run years above 2090, annual results for sectors with multiple impact years return the 2090 estimate. The interpolated values are bound back to the results for sectors with a single impact year estimate, and column `impactYear` set to `impactYear="Interpolation"` for all values. \cr
+#' *`impactyear`* \tab To aggregate over impact years, [FrEDI::aggregate_impacts()] first separates results for sectors with only one impact year estimate (i.e., `impactYear= "N/A"`) from from observations with multiple impact year estimates (i.e., sectors with results for both `impactYear= "2010"` and `impactYear= "2090"`). For these sectors with multiple impact years, physical impacts and annual costs (columns `"physical_impacts"` and `"annual_impacts"`) are linearly interpolated between impact year estimates. For any model run years above 2090, annual results for sectors with multiple impact years return the 2090 estimate. The interpolated values are then row-bound to the results for sectors with a single impact year estimate, and column `impactYear` set to `impactYear= "Interpolation"` for all values. If `"impactyear"` is included in `aggLevels` (e.g., `aggLevels= "all"`), [FrEDI::aggregate_impacts()] aggregates over impact years before performing other types of aggregation. \cr
+#'
+#' *`modelaverage`* \tab To aggregate over models for temperature-driven sectors, [FrEDI::aggregate_impacts()] averages physical impacts and annual costs (columns `"physical_impacts"` and `"annual_impacts"`, respectively) across all GCM models present in the data. [FrEDI::aggregate_impacts()] drops the column `"model"` from the grouping columns when averaging over models. Averages exclude observations with missing values. However, If all values within a grouping are missing, the model average is set to `NA`. The values in column `"model"` are set to `"Average"` for model averages and the model averages data frame is then row-bound to the main results data frame. For SLR-driven sectors, there is no need for additional model aggregation; these values already have `model="Interpolation"`. If `"modelaverage"` is included in `aggLevels` (e.g., `aggLevels= "all"`), [FrEDI::aggregate_impacts()] first aggregates over impact years  (if `"impactyear"` present in `aggLevels` or if `aggLevels="all"`) before aggregating over models.\cr
+#'
+#' *`national`* \tab To aggregate values to the national level, [FrEDI::aggregate_impacts()] sums physical impacts and annual costs (columns `"physical_impacts"` and `"annual_impacts"`, respectively) across all regions present in the data. [FrEDI::aggregate_impacts()] drops the columns `"region"`, `"state"`, and `"postal"` when summing over states and regions. Years which have missing column data for all regions return as `NA`. Values for column `"region"` are set to `"National Total"`; values for column `"state"` are set to `All`, and values for column `"postal"` are set to `US`. The data frame with national totals is then row-bound to the main results data frame. If `"national"` is included in `aggLevels` (e.g., `aggLevels= "all"`), [FrEDI::aggregate_impacts()] first aggregates over impact years and/or models (if `"impactyear"` and/or `"modelaverage"` are present in `aggLevels` or if `aggLevels= "all"`) before aggregating over models.\cr
+#'
+#' *`impacttype`* \tab To aggregate values over impact types, [FrEDI::aggregate_impacts()] sums annual impacts (column `"annual_impacts"`) across all impact types for each sector. [FrEDI::aggregate_impacts()] drops the column `"impactType"` and `"physicalmeasure"` from the grouping columns when summing over impact types. Years which have missing column data for all impact types return as `NA`. All values in column `"impactType"` are set to `"all"`. Aggregating over impact types, drops columns related to physical impacts (i.e., columns `"physicalmeasure"` and `"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
 #' }
 #'
-#' Note that [FrEDI::aggregate_impacts()] drops columns not used in grouping or aggregation.
+#' After aggregating values, [FrEDI::aggregate_impacts()] joins the data frame of impacts with information about `"driverType"`, `"driverUnit"`, `"driverValue"`, `"gdp_usd"`, `"national_pop"`, `"gdp_percap"`, and `"state_pop"`.
 #'
-#' @return
-#' The output of [FrEDI::run_fredi()] is an R data frame object containing annual average impacts, by year (2010-2090), summarized at the specified aggregation and grouping levels.
 #'
 #' @examples
 #' ### Create temperature binning scenario
-#' df_tempExOut <- run_fredi(aggLevels="none", pv=TRUE, silent=TRUE)
+#' df_results1 <- run_fredi(aggLevels="none", silent=TRUE)
 #'
 #' ### Aggregate temperature binning summary across multiple columns
-#' agg_tempExOut <- df_tempExOut |> aggregate_impacts(columns=c("annual_impacts", "discounted_impacts"))
+#' df_results2 <- df_results1 |> aggregate_impacts(columns=c("annual_impacts"), aggLevels="all")
 #'
 #' @references Environmental Protection Agency (EPA). 2021. Technical Documentation on The Framework for Evaluating Damages and Impacts (FrEDI). Technical Report EPA 430-R-21-004, EPA, Washington, DC. Available at <https://epa.gov/cira/FrEDI/>.
 #'
@@ -48,7 +51,7 @@
 aggregate_impacts <- function(
     data,             ### Data frame of outputs from temperature binning
     aggLevels   = c("national", "modelaverage", "impacttype", "impactyear"),  ### Levels of aggregation
-    columns     = c("annual_impacts"), ### Columns to aggregate
+    columns     = c("physical_impacts", "annual_impacts"), ### Columns to aggregate
     groupByCols = c("sector", "variant", "impactType", "impactYear") |>
       c("region", "state", "postal") |>
       c("model_type", "model") |>