complete_fu_allocation_table: Complete an FU Allocation table

In MatthewHeun/IEATools: Tools for Working with International Energy Agency Data

Complete an FU Allocation table

Description

An FU (final-to-useful) Allocation table tells how final energy carriers are allocated to final-to-useful machines in each final demand sector. A template for an FU Allocation table can be created with fu_allocation_template(). If the analyst does not know some (or any) FU allocations for a given country, this function can be used to build a complete FU allocation table by supplying allocations from any number of exemplar countries.

Usage

complete_fu_allocation_table(
  fu_allocation_table,
  country_to_complete,
  exemplar_fu_allocation_tables,
  tidy_specified_iea_data,
  country = IEATools::iea_cols$country,
  ledger_side = IEATools::iea_cols$ledger_side,
  flow = IEATools::iea_cols$flow,
  product = IEATools::iea_cols$product,
  e_dot = IEATools::iea_cols$e_dot,
  year = IEATools::iea_cols$year,
  flow_aggregation_point = IEATools::iea_cols$flow_aggregation_point,
  supply = IEATools::ledger_sides$supply,
  consumption = IEATools::ledger_sides$consumption,
  eiou = IEATools::tfc_compare_flows$energy_industry_own_use,
  e_dot_perc = IEATools::template_cols$e_dot_perc,
  destination = IEATools::template_cols$destination,
  machine = IEATools::template_cols$machine,
  eu_product = IEATools::template_cols$eu_product,
  ef_product = IEATools::template_cols$ef_product,
  maximum_values = IEATools::template_cols$maximum_values,
  quantity = IEATools::template_cols$quantity,
  c_source = IEATools::template_cols$c_source,
  .values = IEATools::template_cols$.values
)

Arguments

fu_allocation_table	The FU allocation table to be completed. This data frame is probably read by load_fu_allocation_data(). If NULL, the table will be constructed exclusively from information available in the exemplar country tables. Only one country is allowed in this data frame.
country_to_complete	The country whose FU Allocation table is to be completed.
exemplar_fu_allocation_tables	A list of FU Allocation tables, each probably created by load_fu_allocation_data(). Note that each exemplar table must contain data for a single country only. If more than one country is found, an error occurs.
tidy_specified_iea_data	A data frame of specified IEA data in tidy format.
country, ledger_side, flow, product, e_dot, year, flow_aggregation_point	See IEATools::ieacols.
supply, consumption	See IEATools::ledger_sides.
eiou	See IEATools::tfc_compar_flows.
e_dot_perc, destination, machine, eu_product, ef_product, maximum_values, quantity	See IEATools::template_cols.
c_source	The name of a column added to output that describes the source of the allocation values (the C values). Default is "C_source".
.values	The name of a values column created internally. Default is "values".

Details

fu_allocation_table is the FU Allocation table to be completed. Any missing information is obtained from the FU Allocation tables of the exemplar countries, provided in the exemplar_fu_allocation_tables argument. Each exemplar table is interrogated in order, with data taken from the first exemplar that contains the needed information.

tidy_specified_iea_data supplies information about which data are needed. The tidy_specified_iea_data data frame should be obtained from a call to specify_all().

If fu_allocation_table can't be completed (because not enough information is available in exemplar_fu_allocation_tables), an error is emitted and a data frame is returned containing rows from tidy_specified_iea_data that were not allocated.

Only 1 country can be specified in country_to_complete. More than 1 country will throw an error.

Value

A tidy data frame containing a completed FU Allocation table to replace argument fu_allocation_table. Note that the max_vals column is absent on output. Also, the e_dot and e_dot_perc rows are absent on output.

Examples

fu_table <- load_fu_allocation_data()
# Make an FU Allocation table for Ghana that is missing Residential consumption of PSBs.
# Allocations for Residential consumption of PSBs will be picked up from the exemplar, South Africa.
fu_table_GHA <- fu_table %>% 
  dplyr::filter(Country == "GHA") %>% 
  dplyr::filter(!(Flow.aggregation.point == IEATools::tfc_flows$other & 
                    Ef.product == IEATools::biofuels_and_waste_products$primary_solid_biofuels & 
                    Destination == IEATools::other_flows$residential))
# Make the exemplar, South Africa.
fu_table_ZAF <- fu_table %>% 
  dplyr::filter(Country == "ZAF")
# The South African data have Residential PSB consumption, 
# which will be used to complete the Ghanaian FU Allocation table.
fu_table_ZAF %>% 
  dplyr::filter(Flow.aggregation.point == IEATools::tfc_flows$other & 
                  Ef.product == IEATools::biofuels_and_waste_products$primary_solid_biofuels & 
                  Destination == IEATools::other_flows$residential) %>% 
  dplyr::select(!c(Method, Energy.type, Last.stage, Flow.aggregation.point))
# Get the IEA data for GHA and ZAF and specify it.
tidy_specified_iea_data <- load_tidy_iea_df() %>% 
  specify_all()
# Now complete the Ghanaian FU Allocation table using information from South Africa.
completed <- complete_fu_allocation_table(fu_allocation_table = fu_table_GHA, 
                                          country_to_complete = "GHA",
                                          exemplar_fu_allocation_tables = list(fu_table_ZAF), 
                                          tidy_specified_iea_data = tidy_specified_iea_data)
# Note that the C_source column shows that these data have been taken from South Africa.
completed %>% 
  dplyr::filter(Flow.aggregation.point == IEATools::tfc_flows$other & 
                  Ef.product == IEATools::biofuels_and_waste_products$primary_solid_biofuels & 
                  Destination == IEATools::other_flows$residential) %>% 
  dplyr::select(!c(Method, Energy.type, Last.stage, Flow.aggregation.point))

MatthewHeun/IEATools documentation built on Feb. 6, 2024, 3:29 p.m.