Complete an FU Allocation table — complete_fu_allocation

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".

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.

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.

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(!(FlowAggregationPoint == IEATools::tfc_flows$other & 
                    EfProduct == 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(FlowAggregationPoint == IEATools::tfc_flows$other & 
                  EfProduct == IEATools::biofuels_and_waste_products$primary_solid_biofuels & 
                  Destination == IEATools::other_flows$residential) %>% 
  dplyr::select(!c(Method, EnergyType, LastStage, FlowAggregationPoint))
#>   Country  LedgerSide Unit              EfProduct         Machine EuProduct
#> 1     ZAF Consumption ktoe Primary solid biofuels            <NA>      <NA>
#> 2     ZAF Consumption ktoe Primary solid biofuels            <NA>      <NA>
#> 3     ZAF Consumption ktoe Primary solid biofuels Wood cookstoves MTH.100.C
#> 4     ZAF Consumption ktoe Primary solid biofuels   Wood furnaces  LTH.20.C
#> 5     ZAF Consumption ktoe Primary solid biofuels            <NA>      <NA>
#>   Destination Quantity MaximumValues         1971         2000
#> 1 Residential     Edot  5574.9498000 3869.3035000 5574.9498000
#> 2 Residential Edot [%]     0.1198823    0.1198823    0.1139165
#> 3 Residential  C_1 [%]            NA    0.5000000    0.5000000
#> 4 Residential  C_2 [%]            NA    0.5000000    0.5000000
#> 5 Residential  C_3 [%]            NA           NA           NA
# 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(FlowAggregationPoint == IEATools::tfc_flows$other & 
                  EfProduct == IEATools::biofuels_and_waste_products$primary_solid_biofuels & 
                  Destination == IEATools::other_flows$residential) %>% 
  dplyr::select(!c(Method, EnergyType, LastStage, FlowAggregationPoint))
#> # A tibble: 4 × 10
#>   Country LedgerSide  EfProduct     Machine EuProduct Destination Quantity  Year
#>   <chr>   <chr>       <chr>         <chr>   <chr>     <chr>       <chr>    <dbl>
#> 1 GHA     Consumption Primary soli… Wood c… MTH.100.C Residential C_1 [%]   1971
#> 2 GHA     Consumption Primary soli… Wood c… MTH.100.C Residential C_1 [%]   2000
#> 3 GHA     Consumption Primary soli… Wood f… LTH.20.C  Residential C_2 [%]   1971
#> 4 GHA     Consumption Primary soli… Wood f… LTH.20.C  Residential C_2 [%]   2000
#> # ℹ 2 more variables: Value <dbl>, CSource <chr>