Merge pull request #306 from USEPA/release_v1.6.0

Remove export of fxns designed for internal use; other minor doc and write out updates for models with external import factors

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: useeior
 Type: Package
 Title: USEEIO R modeling software
-Version: 1.5.3
-Date: 2024-7-13
+Version: 1.6.0
+Date: 2024-8-2
 Authors@R: c(
   person("Ben","Young", email="[email protected]", role="aut"),
   person("Jorge","Vendries", email="[email protected]", role="aut"),

R/CalculationFunctions.R

@@ -123,7 +123,6 @@ prepareDemandVectorForImportResults <- function(model, demand = "Production", lo
 #' @param location, str optional location code for demand vector, required for two-region models
 #' @param use_domestic_requirements bool, if TRUE, return only domestic portion of results
 #' @param household_emissions, bool, if TRUE, include calculation of emissions from households
-#' @export
 #' @return A list with LCI and LCIA results (in data.frame format) of the EEIO model.
 calculateResultsWithExternalFactors <- function(model, perspective = "FINAL", demand = "Consumption", location = NULL,
                                                 use_domestic_requirements = FALSE, household_emissions = FALSE) {
@@ -217,7 +216,6 @@ calculateResultsWithExternalFactors <- function(model, perspective = "FINAL", de
 #' if FALSE, use complete demand and L matrix.
 #' @param location, str optional location code for demand vector, required for two-region models
 #' @param household_emissions, bool, if TRUE, include calculation of emissions from households
-#' @export
 #' @return A list with LCI and LCIA results (in data.frame format) of the EEIO model.
 calculateStandardResults <- function(model, perspective, f, use_domestic_requirements = FALSE,
                                      location = NULL, household_emissions = FALSE) {
@@ -372,7 +370,7 @@ calculatePercentContributiontoImpact <- function (x,y) {
 #' @param indicator, str, index of a model indicator for use in the D matrix, e.g. "Acidification Potential".
 #' @param domestic, boolean, sets model to use domestic flow matrix. Default is FALSE.
 #' @return A dataframe sorted by contribution (high-to-low), also showing "L", "D", "impact".
-#' @export
+## @export
 calculateSectorContributiontoImpact <- function (model, sector, indicator, domestic=FALSE) {
   L <- model$L
   if (domestic) {
@@ -416,7 +414,6 @@ calculateFlowContributiontoImpact <- function (model, sector, indicator, domesti
 #' @param to_level    The level of BEA code this matrix will be aggregated to
 #' @param crosswalk   Sector crosswalk between levels of detail
 #' @return An aggregated matrix with sectors as rows
-#' @export
 aggregateResultMatrixbyRow <- function (matrix, to_level, crosswalk) {
   # Determine the columns within MasterCrosswalk that will be used in aggregation
   from_code <- "USEEIO"
@@ -517,7 +514,6 @@ calculateMarginSectorImpacts <- function(model) {
 #' @param location, str optional location code for demand vector, required for two-region models
 #' @param characterized, bool, TRUE to characterize using C matrix, FALSE to show LCI
 #' @return A result vector with rows for final demand sector(s)
-#' @export
 calculateHouseholdEmissions <- function(model, f, location, characterized=FALSE) {
   if(!"B_h" %in% names(model)) {
     logging::logwarn("Household emissions not found in this model")

R/StateiorFunctions.R

@@ -286,7 +286,6 @@ validate2RCommodityTotals <- function(model) {
 #' @param v_One A vector of totals derived from specific 2R model object
 #' @param v_Two A vector of totals dervied from a different 2R model object than v_One
 #' @return A list of sectors that failed the comparison between the two specified q vectors. 
-#' @export
 compare2RVectorTotals <- function(v_One, v_Two) {
 
   # Calculate relative differences in v_One and v_Two

R/ValidateModel.R

@@ -5,7 +5,6 @@
 #' @param use_domestic, a logical value indicating whether to use domestic demand vector
 #' @param tolerance, a numeric value, tolerance level of the comparison
 #' @return A list with pass/fail validation result and the cell-by-cell relative diff matrix
-#' @export
 compareEandLCIResult <- function(model, use_domestic = FALSE, tolerance = 0.05) {
   # Prepare left side of the equation
   CbS_cast <- standardizeandcastSatelliteTable(model$CbS,model)
@@ -80,7 +79,6 @@ calculateProductofLeontiefAndProductionDemand <- function (model, use_domestic)
 #' @param use_domestic, a logical value indicating whether to use domestic demand vector
 #' @param tolerance, a numeric value, tolerance level of the comparison
 #' @return A list with pass/fail validation result and the cell-by-cell relative diff matrix
-#' @export
 compareOutputandLeontiefXDemand <- function(model, use_domestic=FALSE, tolerance=0.05) {
   # Generate output and scaling vector
   if(model$specs$CommodityorIndustryType == "Commodity") {
@@ -111,7 +109,6 @@ compareOutputandLeontiefXDemand <- function(model, use_domestic=FALSE, tolerance
 #' @param model A complete EEIO model: a list with USEEIO model components and attributes
 #' @param tolerance, a numeric value, tolerance level of the comparison
 #' @return A list with pass/fail validation result and the cell-by-cell relative diff matrix
-#' @export 
 compareCommodityOutputandDomesticUseplusProductionDemand <- function(model, tolerance=0.05) {
   q <- removeHybridProcesses(model, model$q)
   demand <- model$DemandVectors$vectors[endsWith(names(model$DemandVectors$vectors),"Production_Domestic")][[1]]
@@ -141,7 +138,6 @@ compareCommodityOutputandDomesticUseplusProductionDemand <- function(model, tole
 #' @param model A complete EEIO model: a list with USEEIO model components and attributes
 #' @param tolerance, a numeric value, tolerance level of the comparison
 #' @return A list with pass/fail validation result and the cell-by-cell relative diff matrix
-#' @export 
 compareCommodityOutputXMarketShareandIndustryOutputwithCPITransformation <- function(model, tolerance=0.05) {
   if(model$specs$BaseIOSchema == 2012){
     target_year <- "2017"

R/WriteModel.R

@@ -1,7 +1,7 @@
 # Functions for exporting the model to disc
 
 #' The vector of matrices to write out
-matrices <- c("V", "U", "U_d", "A", "A_d", "B", "C", "D", "L", "L_d",
+matrices <- c("V", "U", "U_d", "A", "A_d", "A_m", "B", "C", "D", "L", "L_d",
               "M", "M_d", "M_m", "N", "N_d", "N_m",
               "Rho", "Phi", "Tau")
 

format_specs/Model.md

@@ -21,6 +21,7 @@ Items are listed in the order in which they appear in a built Model object in R.
 | InternationalTradeAdjustmentMeta | data.frame | metadata | Metadata for international trade adjusment in [sector meta with group format](#Sector-Meta-with-Group) |
 | MarginSectors | data.frame | metadata | Margin sector metadata in [sector meta format](#sector-meta) |
 | ValueAddedMeta | data.frame | metadata | Value added metadata in [sector meta format](#sector-meta) |
+| ImportMatrix | data.frame | supporting data | A version of the model Use table with imports only |
 | MultiYearIndustryOutput | data.frame | supporting data | Multi-year industry output in [sector-by-year format](#sector-by-year) |
 | MultiYearCommodityOutput | data.frame | supporting data | Multi-year commodity output  in [sector-by-year format](#sector-by-year) |
 | Margins | data.frame | supporting data | [The final consumer margins table](#margins) |
@@ -283,8 +284,8 @@ sectors |       |
         +-------+
 ```
 
-The related `A_d` matrix provides direct sector inputs per dollar sector output that are only from the US.
-
+The related `A_d` matrix provides direct sector inputs per dollar sector output for inputs that are from the US.
+The related `A_m` matrix provides direct sector inputs per dollar output for inputs that are international imports if a model is built with [ExternalImportFactors](ModelSpecification.md).
 #### L
 `L` is also a `sector x sector` matrix and contains in each column `i` the
 total requirements of the respective sectors inputs per 1 USD of output
@@ -298,7 +299,8 @@ sectors |       |
         +-------+
 ```
 
-The related `L_d` matrix provides direct + indirect sector inputs per dollar output that are only from the US.
+The related `L_d` matrix provides direct + indirect sector inputs per dollar output for inputs that are from the US.
+
 
 #### B
 The satellite matrix `B` is a `flow x sector` matrix and contains in
@@ -387,7 +389,7 @@ flows           |       |
 ```
 
 The related `M_d` matrix provides direct + indirect emissions and resources per dollar output that are only from the US.
-While the `M_m` matrix provides direct + indirect emissions and resources per dollar of imported goods if a model is built with [ExternalImportFactors](ModelSpecification.md).
+The related `M_m` matrix provides direct + indirect emissions and resources per dollar of imported goods if a model is built with [ExternalImportFactors](ModelSpecification.md).
 
 #### N
 The matrix `N` is a `indicator x sector` matrix and contains in each column
@@ -402,4 +404,4 @@ indicators      |       |
 ```
 
 The related `N_d` matrix provides direct + indirect impact results per dollar output that are only from the US.
-While the `N_m` matrix provides direct + indirect impact results per dollar of imported goods if a model is built with [ExternalImportFactors](ModelSpecification.md).
+The related `N_m` matrix provides direct + indirect impact results per dollar of imported goods if a model is built with [ExternalImportFactors](ModelSpecification.md).

inst/extdata/modelspecs/USEEIOv2.3-GHG.yml

@@ -31,7 +31,7 @@ SatelliteTable:
       USEPA_GHG_2024:
         Title: "GHG Inventory"
         Author: "USEPA"
-        DataYear: 2022
+        DataYear: 2019
         URL: "https://www.epa.gov/ghgemissions/inventory-us-greenhouse-gas-emissions-and-sinks-1990-2022"
         Primary: TRUE
 

inst/extdata/modelspecs/USEEIOv2.3-s-GHG-19.yml

@@ -31,7 +31,7 @@ SatelliteTable:
       USEPA_GHG_2024:
         Title: "GHG Inventory"
         Author: "USEPA"
-        DataYear: 2022
+        DataYear: 2019
         URL: "https://www.epa.gov/ghgemissions/inventory-us-greenhouse-gas-emissions-and-sinks-1990-2022"
         Primary: TRUE