augment_iea_df: Augment an IEA data frame
In MatthewHeun/IEATools: Tools for Working with International Energy Agency Data
augment_iea_df R Documentation
Augment an IEA data frame
Description
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.
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.
Value
.iea_df with additional columns named ledger_side, flow_aggregation_point, energy_type, and unit.
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()
MatthewHeun/IEATools documentation built on Dec. 14, 2024, 12:08 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| augment_iea_df | R Documentation |
Augment an IEA data frame
Description
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 |
country |
The name of the country column in |
ledger_side |
The name of the ledger side column to be added to |
flow_aggregation_point |
The name of the flow aggregation point column to be added to |
flow |
The name of the flow column in |
product |
The name of the product column in |
energy_type |
The name of the energy type column to be added to |
energy_type_val |
The value to put in the |
method |
The name of the method column to be added to |
method_val |
The value to put in the |
last_stage |
The name of the last stage column to be added to |
last_stage_val |
The value to put in the |
unit |
The name of the unit column to be added to |
unit_val |
The value to put in the |
supply |
The string that identifies supply ledger side.
Default is |
consumption |
The string that identifies consumption |
tpes |
The string that identifies total primary energy supply |
tpes_flows |
A vector of strings that give flows that are aggregated to |
tfc_compare |
A string that identifies the |
tfc_compare_flows |
A vector of strings that give |
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 |
transformation_processes |
The string that indicates transformation processes in the |
tp_flows_suffix |
The suffix for transformation processes in the |
nstp_flows_suffix |
The suffix for non-specified transformation processes in the |
mapep |
The string that identifies main activity producer electricity plants in the |
eiou |
The string that identifies energy industry own use in the |
eiou_flows_suffix |
The suffix for energy industry own use in the |
coal_mines |
The string that identifies coal mines in the |
non_specified |
The string that identifies non-specified flows in the |
tfc |
The string that identifies total final consumption in the |
tfc_flows |
A vector of strings that give total final consumption in the |
industry |
A string that names the industry |
industry_flows |
A vector of strings representing |
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 |
transport_flows |
A vector of strings representing |
other |
A string that names the other |
other_flows |
A vector of strings representing |
non_energy |
A string that names the non-energy |
non_energy_flows |
A list of |
memo_non_energy_flows |
A list of |
electricity_output |
A string that names the electricity output |
electricity_output_flows_prefix |
A string prefix for |
heat_output |
A string that names the heat output |
heat_output_flows_prefix |
A string prefix for |
.rownum |
The name of a column created (and destroyed) internally by this function.
The |
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.
Value
.iea_df with additional columns named ledger_side, flow_aggregation_point, energy_type, and unit.
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()
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.