Fix IEA energy balances — fix_tidy_iea_df

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".

Value

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

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, Energy.type, 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).

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, Energy.type, Last.stage, 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
#> # A tibble: 78 × 12
#>    Country Method Energy.type Last.stage  Year Product          Unit  supply_sum
#>    <chr>   <chr>  <chr>       <chr>      <dbl> <chr>            <chr>      <dbl>
#>  1 GHA     PCM    E           Final       1971 Aviation gasoli… TJ       0      
#>  2 GHA     PCM    E           Final       1971 Charcoal         TJ       4.99e+3
#>  3 GHA     PCM    E           Final       1971 Crude oil        TJ      -1.00e-4
#>  4 GHA     PCM    E           Final       1971 Electricity      TJ       9.85e+3
#>  5 GHA     PCM    E           Final       1971 Fuel oil         TJ       3.98e+3
#>  6 GHA     PCM    E           Final       1971 Gas/diesel oil … TJ       9.14e+3
#>  7 GHA     PCM    E           Final       1971 Hydro            TJ       0      
#>  8 GHA     PCM    E           Final       1971 Kerosene type j… TJ       0      
#>  9 GHA     PCM    E           Final       1971 Liquefied petro… TJ       1.42e+2
#> 10 GHA     PCM    E           Final       1971 Lubricants       TJ       7.56e+2
#> # ℹ 68 more rows
#> # ℹ 4 more variables: consumption_sum <dbl>, supply_minus_consumption <dbl>,
#> #   balance_OK <lgl>, err <dbl>
# 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()
#> [1] FALSE
# Fix the imbalances.
balanced <- grouped_iea_df %>% 
  fix_tidy_iea_df_balances() %>% 
  calc_tidy_iea_df_balances()
balanced
#> # A tibble: 78 × 12
#>    Country Method Energy.type Last.stage  Year Product          Unit  supply_sum
#>    <chr>   <chr>  <chr>       <chr>      <dbl> <chr>            <chr>      <dbl>
#>  1 GHA     PCM    E           Final       1971 Aviation gasoli… TJ            0 
#>  2 GHA     PCM    E           Final       1971 Charcoal         TJ         4990.
#>  3 GHA     PCM    E           Final       1971 Crude oil        TJ            0 
#>  4 GHA     PCM    E           Final       1971 Electricity      TJ         9846.
#>  5 GHA     PCM    E           Final       1971 Fuel oil         TJ         3980.
#>  6 GHA     PCM    E           Final       1971 Gas/diesel oil … TJ         9136.
#>  7 GHA     PCM    E           Final       1971 Hydro            TJ            0 
#>  8 GHA     PCM    E           Final       1971 Kerosene type j… TJ            0 
#>  9 GHA     PCM    E           Final       1971 Liquefied petro… TJ          142.
#> 10 GHA     PCM    E           Final       1971 Lubricants       TJ          756.
#> # ℹ 68 more rows
#> # ℹ 4 more variables: consumption_sum <dbl>, supply_minus_consumption <dbl>,
#> #   balance_OK <lgl>, err <dbl>
balanced %>% 
  tidy_iea_df_balanced()
#> [1] TRUE