Augment an IEA data frame

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 Energy.type 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 Energy.type Last.stage Ledger.side Flow.aggregation.point Flow 
#>   <chr>   <chr>  <chr>       <chr>      <chr>       <chr>                  <chr>
#> 1 World   PCM    E           Final      Supply      Total primary energy … Prod…
#> 2 World   PCM    E           Final      Supply      TFC compare            Stat…
#> 3 World   PCM    E           Final      Supply      Transformation proces… Main…
#> 4 World   PCM    E           Final      Supply      Transformation proces… Non-…
#> 5 World   PCM    E           Final      Supply      Energy industry own u… Coal…
#> 6 World   PCM    E           Final      Supply      Energy industry own u… 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>