fix_tidy_iea_df_balances: Fix IEA energy balances

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

Fix IEA energy balances

Description

IEA extended energy balance data are sometimes not quite balanced. In fact, supply and consumption are often wrong by a few ktoe or TJ for any given Product in a Country in a Year. This function ensures that the balance is perfect by adjusting the ⁠Statistical differences⁠ flow on a per-product basis.

Usage

fix_tidy_iea_df_balances(
  .tidy_iea_df,
  max_fix = 1,
  remove_zeroes = TRUE,
  country = IEATools::iea_cols$country,
  year = IEATools::iea_cols$year,
  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,
  supply = IEATools::ledger_sides$supply,
  consumption = IEATools::ledger_sides$consumption,
  tfc_compare = IEATools::aggregation_flows$tfc_compare,
  statistical_differences = IEATools::tfc_compare_flows$statistical_differences,
  .err = ".err"
)

Arguments

.tidy_iea_df	a tidy data frame containing IEA extended energy balance data
max_fix	the maximum energy balance that will be fixed without giving an error. Default is 1.
remove_zeroes	a logical telling whether to remove 0s after balancing. Default is TRUE.
ledger_side, flow_aggregation_point, country, year, flow, product, e_dot	See IEATools::iea_cols.
supply, consumption	See IEATools::ledger_sides.
tfc_compare	See IEATools::aggregation_flows.
statistical_differences	See IEATools::tfc_compare_flows.
.err	the name of a temporary error column added to .tidy_iea_df. Default is ".err".

Details

This function assumes that .tidy_iea_df is grouped appropriately prior to passing into this function. 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, 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() and adjusts the value of the statistical_differences column to compensate for any imbalances that are present.

If energy balance for any product is greater than max_fix (default 1), an error will be emitted, and execution will halt. This behavior is intended to identify any places where there are gross energy imbalances that should be investigated prior to further analysis.

If .tidy_iea_df has no rows (as could happen with a country for which data are unavailable for a given year), .tidy_iea_df is returned unmodified (i.e., with no rows).

Value

.tidy_iea_df with adjusted statistical_differences flows such that the data for each product are in perfect energy balance.

Examples

library(dplyr)
# Balances are calculated for each group.
# 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, 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 
# on a per-product basis.
# The `err` column shows the magnitude of the imbalances.
unbalanced <- grouped_iea_df %>% 
  calc_tidy_iea_df_balances()
unbalanced
# The `tidy_iea_df_balanced` function returns `TRUE` if and only if `all` of the groups (rows) 
# in `unbalanced` are balanced.
unbalanced %>% 
  tidy_iea_df_balanced()
# Fix the imbalances.
balanced <- grouped_iea_df %>% 
  fix_tidy_iea_df_balances() %>% 
  calc_tidy_iea_df_balances()
balanced
balanced %>% 
  tidy_iea_df_balanced()

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