Adds a balancing vector to the Balancing matrix

This function adds a balancing vector to the .tidy_iea_df in the Balancing matrix when the data frame is not balanced.

add_balancing_vector(
  .tidy_iea_df,
  country = IEATools::iea_cols$country,
  method = IEATools::iea_cols$method,
  energy_type = IEATools::iea_cols$energy_type,
  last_stage = IEATools::iea_cols$last_stage,
  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,
  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",
  balancing_matrix = "B"
)

Arguments

.tidy_iea_df

The .tidy_iea_df for which a balancing vector needs being added.

country, method, energy_type, last_stage, year, ledger_side, flow_aggregation_point, flow, product, e_dot, unit

See IEATools::iea_cols.

supply

The name of the supply ledger side. Default is IEATools::ledger_sides$supply.

consumption

The name of the consumption ledger side. Default is IEATools::ledger_sides$consumption.

matnames

The column name of the column having matrices names. Default is IEATools::mat_meta_cols$matnames.

balancing

The name of the balancing ledger side. Default is "balancing".

supply_sum

The name of the supply sum column (total supply for each product). Default is "supply_sum".

consumption_sum

The name of the consumption sum column (total consumption for each product). Default is "consumption_sum".

supply_minus_consumption

The name of the column calculating the difference between total supply and consumption for each product. Default is "supply_minus_consumption".

balance_OK

A boolean stating whether flows for each product are balanced or not. Default is "balance_OK".

err

The numerical error observed when calculating the balance. Balanced flows will return 0 Default is "err".

balancing_matrix

The name of the Balancing matrix. Default is "B".

Value

The .tidy_iea_df with balancing flows added when needed.

Details

The balancing flow is added by adding a single flow for each product for which consumption and supply are not balanced. So, a single vector is added, but a few flows may be added, depending the number of products for which flows do not balance. The ledger side of balancing flows is "balancing", as these are neither actual supply nor consumption flows, but unbalances that are somehow present in IEA data. Note: one needs to add the column containing matrices names first, most likely using the IEATools::add_psut_matnames() function.

Examples

# When we build the MR-PSUT with the AB example, we get unbalanced products.
# Note that this is done on purpose to reflect reality of IEA data.
tidy_AB_data %>%
IEATools::add_psut_matnames() %>%
 transform_to_gma() %>%
 IEATools::calc_tidy_iea_df_balances() %>%
 dplyr::filter(balance_OK == FALSE) %>%
 print()
#> # A tibble: 6 × 12
#>   Country Method Energy.type Last.stage  Year Product           Unit  supply_sum
#>   <chr>   <chr>  <chr>       <chr>      <dbl> <chr>             <chr>      <dbl>
#> 1 World   PCM    E           Final       2018 {A}_Coke oven co… ktoe         680
#> 2 World   PCM    E           Final       2018 {A}_Crude oil     ktoe         500
#> 3 World   PCM    E           Final       2018 {B}_Coke oven co… ktoe          20
#> 4 World   PCM    E           Final       2018 {B}_Coking coal   ktoe        2000
#> 5 World   PCM    E           Final       2018 {B}_Crude oil     ktoe        3000
#> 6 World   PCM    E           Final       2018 {B}_Natural gas   ktoe        2500
#> # ℹ 4 more variables: consumption_sum <dbl>, supply_minus_consumption <dbl>,
#> #   balance_OK <lgl>, err <dbl>
# Now, if we add the balancing vector, we obtain balanced flows:
tidy_AB_data %>%
IEATools::add_psut_matnames() %>%
 transform_to_gma() %>%
 add_balancing_vector() %>%
 IEATools::calc_tidy_iea_df_balances() %>%
 dplyr::filter(balance_OK == FALSE) %>%
 print()
#> # A tibble: 0 × 12
#> # ℹ 12 variables: Country <chr>, Method <chr>, Energy.type <chr>,
#> #   Last.stage <chr>, Year <dbl>, Product <chr>, Unit <chr>, supply_sum <dbl>,
#> #   consumption_sum <dbl>, supply_minus_consumption <dbl>, balance_OK <lgl>,
#> #   err <dbl>
# Let's have a look to balancing flows, which are all ascribed to the Balancing matrix:
tidy_AB_data %>%
IEATools::add_psut_matnames() %>%
 transform_to_gma() %>%
 add_balancing_vector() %>%
 dplyr::filter(matnames == "B") %>%
 print()
#> # A tibble: 6 × 12
#>   Country Method Energy.type Last.stage  Year Ledger.side Flow.aggregation.point
#>   <chr>   <chr>  <chr>       <chr>      <dbl> <chr>       <chr>                 
#> 1 World   PCM    E           Final       2018 balancing   balancing             
#> 2 World   PCM    E           Final       2018 balancing   balancing             
#> 3 World   PCM    E           Final       2018 balancing   balancing             
#> 4 World   PCM    E           Final       2018 balancing   balancing             
#> 5 World   PCM    E           Final       2018 balancing   balancing             
#> 6 World   PCM    E           Final       2018 balancing   balancing             
#> # ℹ 5 more variables: Flow <chr>, Product <chr>, Unit <chr>, E.dot <dbl>,
#> #   matnames <chr>