Merge branch 'release-0.1.76'

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: IEATools
 Type: Package
 Title: Tools for Working with International Energy Agency Data
-Version: 0.1.75
-Date: 2024-02-03
+Version: 0.1.76
+Date: 2024-12-09
 Authors@R: c(person(given = "Matthew Kuperus", family = "Heun", role = c("aut", "cre"),
                     email = "[email protected]", 
                     comment = c(ORCID = "0000-0002-7438-214X")),
@@ -15,7 +15,7 @@ License: MIT + file LICENSE
 Language: en-US
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 Roxygen: list(markdown = TRUE)
 Depends: R (>= 2.10)
 Config/testthat/edition: 3

NAMESPACE

@@ -44,6 +44,7 @@ export(gather_producer_autoproducer)
 export(iea_df)
 export(iea_file_OK)
 export(insert_after)
+export(load_electricity_heat_output)
 export(load_eta_fu_data)
 export(load_fu_allocation_data)
 export(load_phi_constants_table)
@@ -72,10 +73,13 @@ export(slurp_iea_to_raw_df)
 export(sort_iea_df)
 export(specify_all)
 export(specify_bunkers)
+export(specify_distribution_losses)
+export(specify_electricity_grid)
 export(specify_interface_industries)
 export(specify_non_energy_use)
 export(specify_primary_production)
 export(specify_production_to_resources)
+export(specify_renewable_plants)
 export(specify_tp_eiou)
 export(split_oil_gas_extraction_eiou)
 export(stack_final_useful_df)

NEWS.md

@@ -8,7 +8,34 @@ Cite all releases with doi [10.5281/zenodo.5086371](https://doi.org/10.5281/zeno
 which always resolves to the latest release.
 
 
-## IEATools 0.1.75 (2024-02-03)
+## IEATools 0.1.76 (2024-12-09)
+
+* New function `load_electricity_heat_output()`
+  creates a data frame of IEA electricity and heat output
+  information.
+* Change names of columns to avoid PostgreSQL 
+  database conflicts. 
+  PostgreSQL doesn't like column names containing "."
+  because "." is the separator for "schema.table".
+* New `specify_distribution_losses()` function
+  to specify distribution industries, within which transportation and
+  distribution losses occur.
+* Argument added to `add_nuclear_industry()` to ascribe some EIOU 
+  to the nuclear industry according to its output share.
+* New `specify_renewable_plants()` function 
+  to specify renewable energy plants.
+* New `specify_electricity_grid()` function 
+  to add an electricity grid.
+* The `.iea_file` argument to `slurp_iea_to_raw_df()`
+  is now vectorized, which will enable sending 
+  a vector of country IEA data files in `.iea_file`.
+* Fixed several tests for new column names and added 
+  a couple new tests for new features.
+    * Now at 1365 tests, all passing.
+    * Test coverage remains at 100%.
+
+
+## IEATools 0.1.75 (2024-02-03) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10613604.svg)](https://doi.org/10.5281/zenodo.10613604)
 
 * `extend_to_useful_helper()` and `extend_to_useful()`
   now return additional matrices, namely

R/data.R

@@ -127,7 +127,7 @@
 #' \item{C_eiou}{The name of the EIOU allocation rows in final-to-useful templates.}
 #' \item{C_Y}{The name of the final demand allocation rows in final-to-useful templates.}
 #' \item{C_perc}{The name of the percentage allocation rows in final-to-useful templates.}
-#' \item{e_dot_max}{The name of the maximum E.dot column in final-to-useful templates.}
+#' \item{e_dot_max}{The name of the maximum Edot column in final-to-useful templates.}
 #' \item{e_dot_dest}{The name of the column representing the destination for energy flows in final-to-useful templates.}
 #' \item{e_dot_perc}{The name of the energy flow percentage column in final-to-useful templates.}
 #' \item{e_dot_machine}{The name of the column representing energy flow into a machine in final-to-useful templates.}
@@ -181,6 +181,7 @@
 #' \item{sector}{The type of entity that absorbs final demand.}
 #' \item{product}{The inputs and outputs of industries.}
 #' \item{unit}{Units of physical measurement such as ktoe or TJ.}
+#' \item{other}{Used for, e.g., the 1-dimension of a vector.}
 #' }
 #' 
 #' @examples
@@ -478,6 +479,34 @@
 "electricity_products"
 
 
+#' Heat products
+#'
+#' A string vector containing names of products classified by the IEA as heat products.
+#' 
+#' @format A string vector with `r length(heat_products)` entries.
+#' \describe{
+#' \item{heat}{The string identifier for Heat.}
+#' }
+#' 
+#' @examples
+#' heat_products
+"heat_products"
+
+
+#' Nuclear products
+#'
+#' A string vector containing names of products classified by the IEA as nuclear products.
+#' 
+#' @format A string vector with `r length(nuclear_products)` entries.
+#' \describe{
+#' \item{nuclear}{The string identifier for Nuclear}
+#' }
+#' 
+#' @examples
+#' nuclear_products
+"nuclear_products"
+
+
 #' Non-energy products
 #'
 #' A string vector containing names of products classified as "Non-energy" by
@@ -1149,8 +1178,8 @@
 #' \item{phi_constants_names}{The string name of the tab in the Excel file containing the constant phi values table.}
 #' \item{product_colname}{The string name of the energy product column in the constant phi values table.}
 #' \item{phi_colname}{The string name of the constant phi value column in the constant phi values table.}
-#' \item{is_useful_colname}{The string name of the is.useful column in the constant phi values table.}
-#' \item{phi_source_colname}{The string name of the phi.source column in the completed phi values table.}
+#' \item{is_useful_colname}{The string name of the IsUseful column in the constant phi values table.}
+#' \item{phi_source_colname}{The string name of the PhiSource column in the completed phi values table.}
 #' }
 #'
 #' @examples
@@ -1311,4 +1340,67 @@
 "Fixed_RUSEST_heat"
 
 
+#' Renewable energy industries names
+#'
+#' A string list containing the names of renewable industries added with the `specify_renewable_plants()` function.
+#'
+#' @format A string list with `r length(renewable_industries)` entries.
+#' \describe{
+#' \item{geothermal_plants}{The string name of geothermal plants.}
+#' \item{hydro_plants}{The string name of hydropower plants.}
+#' \item{solar_pv_plants}{The string name of solar photovoltaics plants.}
+#' \item{solar_th_plants}{The string name of solar thermal plants.}
+#' \item{oceanic_plants}{The string name of oceanic power plants.}
+#' \item{wind_power_plants}{The string name of wind power plants.}
+#' }
+#'
+#' @examples
+#' renewable_industries
+"renewable_industries"
+
 
+#' Grid industries names
+#'
+#' A string list containing the names of the grid industries that can be added.
+#'
+#' @format A string list with `r length(grid_industries)` entries.
+#' \describe{
+#' \item{electricity_grid}{The string name of the electricity grid industry.}
+#' }
+#'
+#' @examples
+#' grid_industries
+"grid_industries"
+
+
+#' Distribution industry name
+#'
+#' A character string containing the name of the distribution industry
+#'
+#' @format A character string
+#' \describe{
+#' A character string containing the name of the distribution industry
+#' }
+#'
+#' @examples
+#' distribution_industry
+"distribution_industry"
+
+
+#' Electricity and heat output names
+#'
+#' A character vector containing the prefixes for 
+#' electricity and heat outputs.
+#'
+#' @format A character string
+#' \describe{
+#' \item{electricity_output_prefix}{The string prefix for electricity output.}
+#' \item{heat_output_prefix}{The string prefix for heat output.}
+#' \item{output_machine_delimiter}{The string delimiter between output energy flow and the machine name.}
+#' \item{input_product}{The name of the input product column.}
+#' \item{output_machine_delimiter}{The name of the output product column.}
+#' }
+#'
+#' @examples
+#' elec_heat_output
+"elec_heat_output"

R/electricity_heat_output.R

@@ -0,0 +1,85 @@
+#' Extract a data frame of electricity and heat output information
+#'
+#' @param .iea_file The IEA data file to read
+#' @param electricity_output_prefix The prefix for electricity output rows.
+#'                                  Default is `IEATools::elec_heat_output$electricity_output_prefix`.
+#' @param heat_output_prefix The prefix for heat output rows.
+#'                           Default is `IEATools::elec_heat_output$heat_output_prefix`.
+#' @param country,year,flow,product,e_dot,unit_colname See `IEATools::iea_cols`.
+#' @param input_colname,output_colname,output_machine_delimiter See `IEATools::elec_heat_output`.
+#' @param machine_colname See `IEATools::template_cols`.
+#' @param unit The desired output unit. Default is "TJ". Best not to change this.
+#' @param electricity A string that defines electricity output. 
+#'                    Default is "Electricity".
+#' @param total See `IEATools::memo_aggregation_product_prefixes`.
+#' @param memo See `IEATools::memo_aggregation_flow_prefixes`.
+#'
+#' @return A data frame of electricity and heat output data.
+#'
+#' @export
+#'
+#' @examples
+#' sample_iea_data_path() |> 
+#'   load_electricity_heat_output()
+load_electricity_heat_output <- function(.iea_file = NULL, 
+                                         electricity_output_prefix = IEATools::elec_heat_output$electricity_output_prefix, 
+                                         heat_output_prefix = IEATools::elec_heat_output$heat_output_prefix,
+                                         country = IEATools::iea_cols$country,
+                                         year = IEATools::iea_cols$year,
+                                         flow = IEATools::iea_cols$flow, 
+                                         product = IEATools::iea_cols$product,
+                                         e_dot = IEATools::iea_cols$e_dot,
+                                         input_colname = IEATools::elec_heat_output$input_product,
+                                         output_colname = IEATools::elec_heat_output$output_product, 
+                                         machine_colname = IEATools::template_cols$machine, 
+                                         unit_colname = IEATools::iea_cols$unit,
+                                         unit = "TJ",
+                                         electricity = "Electricity", 
+                                         output_machine_delimiter = IEATools::elec_heat_output$output_machine_delimiter, 
+                                         total = IEATools::memo_aggregation_product_prefixes$total, 
+                                         memo = IEATools::memo_aggregation_flow_prefixes$memo) {
+
+  iea_data <- .iea_file |>
+    iea_df() |> 
+    rename_iea_df_cols() |> 
+    clean_iea_whitespace() |> 
+    use_iso_countries()
+  elec_heat_data <- iea_data |> 
+    dplyr::filter((startsWith(.data[[flow]], electricity_output_prefix) | 
+                     startsWith(.data[[flow]], heat_output_prefix)), 
+                  .data[[product]] != total, 
+                  !startsWith(.data[[product]], memo)) |> 
+    tidyr::separate_wider_delim(dplyr::all_of(flow), delim = "-", names = c(output_colname, machine_colname)) |> 
+    dplyr::mutate(
+      # Capitalize first letter of machine name.
+      "{machine_colname}" := stringr::str_to_sentence(.data[[machine_colname]]), 
+      # Select only the first word in the output column, either "Electricity" or "Heat"
+      "{output_colname}" := stringr::word(.data[[output_colname]], 1),
+      # Fix chp
+      "{machine_colname}" := stringr::str_replace(.data[[machine_colname]], "chp", "CHP")
+    ) |> 
+    dplyr::rename(
+      "{input_colname}" := dplyr::all_of(product)
+    ) |> 
+    tidyr::pivot_longer(cols = !dplyr::all_of(c(country, output_colname, machine_colname, input_colname)),
+                        names_to = year,
+                        values_to = e_dot) |> 
+    dplyr::filter(.data[[e_dot]] != 0) |> 
+    dplyr::mutate(
+      # Convert GWh to TJ for electricity only.
+      "{e_dot}" := dplyr::case_when(
+        # Convert for electricity only.
+        .data[[output_colname]] == electricity ~ .data[[e_dot]] * 3.6, 
+        # Heat is already in TJ.
+        TRUE ~ .data[[e_dot]]
+      ),
+      # Set the unit string.
+      "{unit_colname}" := unit, 
+      # Year should be numeric
+      "{year}" := as.numeric(.data[[year]])
+    ) |> 
+    # Update the order of columns.
+    dplyr::select(dplyr::all_of(c(country, year, input_colname, machine_colname, output_colname, e_dot, unit_colname)))
+
+  return(elec_heat_data)
+}

R/energy_balance.R

@@ -8,7 +8,7 @@
 #' before calling this function.
 #' Grouping should _definitely_ be done on the `Product` column.
 #' Typically, grouping is also done on 
-#' `Country`, `Method`, `Year`, `Energy.type`, `Last.stage`, etc. columns.
+#' `Country`, `Method`, `Year`, `EnergyType`, `Last.stage`, etc. columns.
 #' Grouping should _not_ be done on the `Ledger.side` column or the `Flow` column.
 #' To test whether all balances are OK, 
 #' use the `tidy_iea_df_balanced()` function.
@@ -167,7 +167,7 @@ tidy_iea_df_balanced <- function(.tidy_iea_df_balances,
 #' The `Product` column should definitely be included in `grouping_vars`, 
 #' but any other grouping level is fine. 
 #' Typically, grouping should be done by 
-#' `Country`, `Year`, `Energy.type`, `Last.stage`, `Product`, etc. columns.
+#' `Country`, `Year`, `EnergyType`, `Last.stage`, `Product`, etc. columns.
 #' Grouping should _not_ be done on the `flow_aggregation_point`, `Flow`, or `ledger_side` columns.
 #' 
 #' Internally, this function calls [calc_tidy_iea_df_balances()]
@@ -202,7 +202,7 @@ tidy_iea_df_balanced <- function(.tidy_iea_df_balances,
 #' # Remember that grouping should _not_ be done on
 #' # the `flow_aggregation_point`, `Flow`, or `ledger_side` columns.
 #' grouped_iea_df <- load_tidy_iea_df() %>% 
-#'   group_by(Country, Method, Energy.type, Last.stage, Year, Product)
+#'   group_by(Country, Method, EnergyType, LastStage, Year, Product)
 #' # unbalanced will not be balanced, because the IEA data are not in perfect balance.
 #' # Because we have grouped by key variables, 
 #' # `calc_tidy_iea_df_balances` provides energy balances 
@@ -296,4 +296,4 @@ fix_tidy_iea_df_balances <- function(.tidy_iea_df,
       dplyr::filter(!(.data[[e_dot]] == 0))
   }
   return(out)
-}
+}

R/final_to_useful.R

@@ -6,9 +6,9 @@
 #' This function uses information in a filled allocation template (created by `write_fu_allocation_template()`)
 #' to create allocation matrices (**C**). 
 #' 
-#' rownames of the **C** matrices are taken from the `Ef.product` and `Destination` columns of `.fu_allocation_table`
-#' and have the form "`Ef.product` `r RCLabels::arrow_notation[["pref_end"]]` `Destination`".
-#' colnames of the **C** matrices are taken from the `Machine` and `Eu.product` columns of `.fu_allocation_table`
+#' rownames of the **C** matrices are taken from the `EfProduct` and `Destination` columns of `.fu_allocation_table`
+#' and have the form "`EfProduct` `r RCLabels::arrow_notation[["pref_end"]]` `Destination`".
+#' colnames of the **C** matrices are taken from the `Machine` and `EuProduct` columns of `.fu_allocation_table`
 #' and have the form "machine `r RCLabels::arrow_notation[["pref_end"]]` useful energy form".
 #' 
 #' **C** matrices are created for both energy industry own use
@@ -150,9 +150,9 @@ form_C_mats <- function(.fu_allocation_table,
   prepped <- gathered %>% 
     # Create row and column names.
     dplyr::mutate(
-      # Row names come from Ef.product -> Destination for both C_Y and C_EIOU.
+      # Row names come from EfProduct -> Destination for both C_Y and C_EIOU.
       "{rownames}" := RCLabels::paste_pref_suff(pref = .data[[ef_product]], suff = .data[[destination]], notation = notation),
-      # Column names come from Machine -> Eu.product for both C_Y and C_EIOU.
+      # Column names come from Machine -> EuProduct for both C_Y and C_EIOU.
       "{colnames}" := RCLabels::paste_pref_suff(pref = .data[[machine]], suff = .data[[eu_product]], notation = notation),
       # Row types are Product -> Industry
       # "{rowtypes}" := product,
@@ -712,7 +712,8 @@ extend_to_useful <- function(.sutdata = NULL,
     # Get the detail Y_u matrix
     Y_fu_details_mat <- res_Y[[details_fu]]
     # Add a NULL U_EIOU_u_details matrix
-    U_eiou_fu_details_mat <- NULL
+    # U_eiou_fu_details_mat <- NULL
+    U_eiou_fu_details_mat <- matsbyname::hadamardproduct_byname(U_useful_mat, 0)
 
     # Now check to see if we have any EIOU. 
     # If so, make further adjustments to the matrices.