Augment an IEA data frame — augment_iea

This function prepares an IEA data frame created by iea_df() for use in R. It works on IEA data from the 2018 and 2019 releases of the IEA's extended energy balances.

Usage

augment_iea_df(
  .iea_df,
  country = IEATools::iea_cols$country,
  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,
  energy_type = IEATools::iea_cols$energy_type,
  energy_type_val = "E",
  method = IEATools::iea_cols$method,
  method_val = "PCM",
  last_stage = IEATools::iea_cols$last_stage,
  last_stage_val = "Final",
  unit = IEATools::iea_cols$unit,
  unit_val = "TJ",
  supply = "Supply",
  consumption = "Consumption",
  tpes = IEATools::tfc_compare_flows$total_primary_energy_supply,
  tpes_flows = IEATools::tpes_flows,
  tfc_compare = "TFC compare",
  tfc_compare_flows = IEATools::tfc_compare_flows,
  transfers = "Transfers",
  statistical_differences = IEATools::tfc_compare_flows$statistical_differences,
  losses = IEATools::tfc_compare_flows$losses,
  transformation_processes = IEATools::tfc_compare_flows$transformation_processes,
  tp_flows_suffix = "(transf.)",
  nstp_flows_suffix = "(transformation)",
  mapep = IEATools::transformation_processes$main_activity_producer_electricity_plants,
  eiou = "Energy industry own use",
  eiou_flows_suffix = "(energy)",
  coal_mines = "Coal mines",
  non_specified = "Non-specified",
  tfc = "Total final consumption",
  tfc_flows = IEATools::tfc_flows,
  industry = "Industry",
  industry_flows = IEATools::industry_flows,
  iron_and_steel = "Iron and steel",
  mining_and_quarrying = "Mining and quarrying",
  transport = "Transport",
  transport_flows = IEATools::transport_flows,
  other = "Other",
  other_flows = IEATools::other_flows,
  non_energy = "Non-energy use",
  non_energy_flows = IEATools::non_energy_flows,
  memo_non_energy_flows = IEATools::memo_non_energy_flows,
  electricity_output = "Electricity output (GWh)",
  electricity_output_flows_prefix = "Electricity output (GWh)-",
  heat_output = "Heat output",
  heat_output_flows_prefix = "Heat output-",
  .rownum = ".rownum"
)

Arguments

.iea_df: A data frame produced by the iea_df() function.
country: The name of the country column in .iea_df. Default is IEATools::iea_cols$country.
ledger_side: The name of the ledger side column to be added to .iea_df. Default is IEATools::iea_cols$ledger_side.
flow_aggregation_point: The name of the flow aggregation point column to be added to .iea_df. Default is IEATools::iea_cols$flow_aggregation_point.
flow: The name of the flow column in .iea_df. Default is IEATools::iea_cols$flow.
product: The name of the product column in .iea_df. Default is IEATools::iea_cols$product.
energy_type: The name of the energy type column to be added to .iea_df. Default is IEATools::iea_cols$energy_type.
energy_type_val: The value to put in the energy_type column. Default is "E".
method: The name of the method column to be added to .iea_df. Default is IEATools::iea_cols$method.
method_val: The value to put in the method column. Default is "PCM" (Physical Content Method, which is used by the IEA).
last_stage: The name of the last stage column to be added to .iea_df. Default is IEATools::iea_cols$last_stage.
last_stage_val: The value to put in the last_stage column. Default is "Final" (which is the last stage supplied by the IEA).
unit: The name of the unit column to be added to .iea_df. Default is IEATools::iea_cols$unit.
unit_val: The value to put in the unit column. Default is "TJ" for terajoule.
supply: The string that identifies supply ledger side. Default is IEATools::iea_cols$ledger_side.
consumption: The string that identifies consumption Ledger.side. Default is "Consumption".
tpes: The string that identifies total primary energy supply Flow.aggregation.point. Default is "Total primary energy supply".
tpes_flows: A vector of strings that give flows that are aggregated to Total primary energy supply.
tfc_compare: A string that identifies the TFC compare flow aggregation point. Default is "TFC compare".
tfc_compare_flows: A vector of strings that give Flows that are aggregated to TFC compare.
transfers: = A string that identifies transfers in the flow column. Default is "Transfers".
statistical_differences: A string that identifies statistical differences in flow column. Default is "Statistical differences".
losses: The string that indicates losses in the Flow column. Default is "Losses".
transformation_processes: The string that indicates transformation processes in the Flow column. Default is "Transformation processes".
tp_flows_suffix: The suffix for transformation processes in the Flow column. Default is "(transf.)".
nstp_flows_suffix: The suffix for non-specified transformation processes in the Flow column. Default is "(transformation)".
mapep: The string that identifies main activity producer electricity plants in the Flow column. Default is "Main activity producer electricity plants".
eiou: The string that identifies energy industry own use in the Flow column. Default is "Energy industry own use".
eiou_flows_suffix: The suffix for energy industry own use in the Flow column. Default is "(energy)".
coal_mines: The string that identifies coal mines in the Flow column. Default is "Coal mines".
non_specified: The string that identifies non-specified flows in the Flow column. Default is "Non-specified".
tfc: The string that identifies total final consumption in the Flow column. Default is "Total final consumption".
tfc_flows: A vector of strings that give total final consumption in the Flow column.
industry: A string that names the industry Flow.aggregation.point. Default is "Industry".
industry_flows: A vector of strings representing Flows to be aggregated in the Industry Flow.aggregation.point.
iron_and_steel: A string that identifies the iron and steel industry. Default is "Iron and steel".
mining_and_quarrying: A string that identifies the mining and quarrying industry. Default is "Mining and quarrying".
transport: A string that names the transport Flow.aggregation.point. Default is "Transport".
transport_flows: A vector of strings representing Flows to be aggregated in the Transport Flow.aggregation.point.
other: A string that names the other Flow.aggregation.point. Default is "Other".
other_flows: A vector of strings representing Flows to be aggregated in the Other Flow.aggregation.point.
non_energy: A string that names the non-energy Flow.aggregation.point. Default is "Non-energy use".
non_energy_flows: A list of Flows to be aggregated to the Non-energy use Flow.aggregation.point.
memo_non_energy_flows: A list of Flows to be aggregated to "Memo: Non-energy use in industry". Default is IEATools::memo_non_energy_flows.
electricity_output: A string that names the electricity output Flow. Default is "Electricity output (GWh)".
electricity_output_flows_prefix: A string prefix for Flows to be aggregated in electricity output. Default is "Electricity output (GWh)-".
heat_output: A string that names the heat output Flow. Default is "Heat output".
heat_output_flows_prefix: A string prefix for Flows to be aggregated in heat output. Default is "Heat output-".
.rownum: The name of a column created (and destroyed) internally by this function. The .rownum column temporarily holds row numbers for internal calculations. The .rownum column is deleted before returning.

Value

.iea_df with additional columns named ledger_side, flow_aggregation_point, energy_type, and unit.

Details

This function solves several problems. The first problem is that metadata in the COUNTRY, FLOW, and PRODUCT columns of an IEA data table are not unique. A second problem is that the FLOW column contains both industries to which energy is flowing and the type of flow that is involved. (E.g., the suffix "(energy)" means that the flow is an own use by the energy industry. The "(transf.)" suffix means that a flow is involved in a transformation process between primary and final energy.

To solve these problems, two additional columns are added: Ledger.side and Flow.aggregation.point. Ledger.side can be one of "Supply" or "Consumption", corresponding to the top or bottom of the IEA's tables, respectively. Flow.aggregation.point indicates the next level of aggregation for these data. Flow.aggregation.point can be one of "Total primary energy supply", "Transformation processes", "Energy industry own use", or "TFC compare" on the Supply side of the ledger. On the Consumption side of the ledger, Flow.aggregation.point can be one of "Industry", "Transport", "Other", "Non-energy use", or "Memo: Non-energy use in industry". When the Flow.aggregation.point column is present, the need for the "(energy)" and "(transf.)" suffixes is eliminated, so they are deleted.

The third problem this function solves is that energy type and units are not specified in IEA data. An EnergyType column is added with the value of energy_type_val. (Default is E, for energy, as opposed to X, which would be exergy.) A Unit column is added with the value of unit_val. (Default is "TJ", although any string can be specified in unit_val.)

Note that this function decides where to divide Supply from Consumption. To do so, it first looks for rows in which Flow is "Losses". The last "Losses" row is the last row of the "Supply" side of the ledger. If "Losses" rows are not found, the function looks for rows in which Flow is "Total final consumption". The first "Total final consumption" row is the first row of the Consumption side of the ledger. If neither "Losses" nor "Total final consumption" Flows are present, an error is generated.

Examples

iea_df(text = paste0(",,TIME,1960,1961\n",
                     "COUNTRY,FLOW,PRODUCT\n",
                     "World,Production,Hard coal (if no detail),42,43\n",
                     "World,Statistical differences,Hard coal (if no detail),7,8\n",
                     "World,Main activity producer electricity plants,",
                       "Hard coal (if no detail),9,10\n",
                     "World,Non-specified,Hard coal (if no detail),11,12\n",
                     "World,Coal mines,Hard coal (if no detail),13,14\n",
                     "World,Non-specified,Hard coal (if no detail),11,12\n",
                     "World,Losses,Hard coal (if no detail),1,2\n",
                     "World,Iron and steel,Hard coal (if no detail),5,6\n")) %>% 
  rename_iea_df_cols() %>% 
  augment_iea_df()
#> # A tibble: 8 × 11
#>   Country Method EnergyType LastStage LedgerSide  FlowAggregationPoint     Flow 
#>   <chr>   <chr>  <chr>      <chr>     <chr>       <chr>                    <chr>
#> 1 World   PCM    E          Final     Supply      Total primary energy su… Prod…
#> 2 World   PCM    E          Final     Supply      TFC compare              Stat…
#> 3 World   PCM    E          Final     Supply      Transformation processes Main…
#> 4 World   PCM    E          Final     Supply      Transformation processes Non-…
#> 5 World   PCM    E          Final     Supply      Energy industry own use  Coal…
#> 6 World   PCM    E          Final     Supply      Energy industry own use  Non-…
#> 7 World   PCM    E          Final     Supply      TFC compare              Loss…
#> 8 World   PCM    E          Final     Consumption Industry                 Iron…
#> # ℹ 4 more variables: Product <chr>, Unit <chr>, `1960` <dbl>, `1961` <dbl>