calc_tidy_iea_df_balances: Calculate balances on a tidy IEA data frame

In MatthewHeun/IEATools: Tools for Working with International Energy Agency Data

Calculate balances on a tidy IEA data frame

Description

It is important to know whether energy flows are balanced before proceeding with further analyses. This function calculates energy balances by groups in .tidy_iea_df. So be sure to group .tidy_iea_df by appropriate variables before calling this function. Grouping should definitely be done on the Product column. Typically, grouping is also done on 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.

Usage

calc_tidy_iea_df_balances(
  .tidy_iea_df,
  ledger_side = IEATools::iea_cols$ledger_side,
  flow_aggregation_point = IEATools::iea_cols$flow_aggregation_point,
  flow = IEATools::iea_cols$flow,
  product = IEATools::iea_cols$product,
  e_dot = IEATools::iea_cols$e_dot,
  unit = IEATools::iea_cols$unit,
  supply = IEATools::ledger_sides$supply,
  consumption = IEATools::ledger_sides$consumption,
  matnames = IEATools::mat_meta_cols$matnames,
  balancing = "balancing",
  supply_sum = "supply_sum",
  consumption_sum = "consumption_sum",
  supply_minus_consumption = "supply_minus_consumption",
  balance_OK = "balance_OK",
  err = "err",
  tol = 1e-06
)

Arguments

.tidy_iea_df	an IEA-style data frame containing a ledger_side, product, flow, and energy rate (e_dot) columns along with grouping columns, typically Country, Year, Product, etc. a Ledger.side column.
ledger_side, flow_aggregation_point, flow, product, e_dot, unit	See IEATools::iea_cols.
supply, consumption	See IEATools::ledger_sides.
matnames	See IEATools::mat_meta_cols.
balancing	The ledger side of balancing flows, if any balancing flow has been added to the .tidy_iea_df.
supply_sum	the name of a new column that will contain the sum of all supply for that group. Default is "supply_sum".
consumption_sum	the name of a new column that will contain the sum of all consumption for that group. Default is "consumption_sum".
supply_minus_consumption	the name of a new column that will contain the difference between supply and consumption for that group. Default is "supply_minus_consumption".
balance_OK	the name of a new logical column that tells whether a row's energy balance is OK. Default is "balance_OK".
err	the name of a new column that indicates the energy balance error for each group. Default is "err".
tol	if the difference between supply and consumption is greater than tol, balance_OK will be set to FALSE. Default is 1e-6.

Details

Supply side and consumption side energy flows are aggregated to a supply_sum and a consumption_sum column. There are two possibilities:

1. A Product appears only on the supply side, because it is completely transformed before reaching the consumption side of the ledger. In this case, the consumption_sum column will have an NA value, and the supply_minus_consumption column will also have an NA value.

2. A Product appears on both the supply and the demand sides of the ledger and, therefore, is not NA in the consumption_sum column and the supply_minus_consumption column. The column balance_OK is calculated as follows:

3. For the first situation, consumption_sum will be 0 (within tol) if the Product is balanced and balance_OK will have a value of TRUE. If not, balance_OK will have a value of FALSE.

4. In the second situation, the difference between supply_sum and consumption_sum is calculated (supply_minus_consumption). If the product is balanced, supply_minus_consumption will be 0 (within tol) and balance_OK will be TRUE. If not, balance_OK will be FALSE.

Value

.tidy_iea_df with additional columns supply_sum, consumption_sum, supply_minus_consumption, balance_OK, and err.

Examples

library(dplyr)
Ebal <- load_tidy_iea_df() %>% 
  calc_tidy_iea_df_balances()
head(Ebal, 5)

MatthewHeun/IEATools documentation built on Dec. 14, 2024, 12:08 a.m.