Complete a final-to-useful efficiency table — complete_eta_fu

An FU (final-to-useful) efficiency table tells the efficiency with which final energy carriers are converted to useful energy carriers by final-to-useful machines. It also provides the exergy-to-energy ratio for the useful product (phi.u). A template for an FU efficiency table can be created with eta_fu_template(). If the analyst does not know some FU efficiencies or exergy-to-energy efficiencies for a given country, this function can be used to build a complete FU Efficiency table by supplying efficiencies and exergy-to-energy ratios from any number of exemplar countries.

Usage

complete_eta_fu_table(
  eta_fu_table,
  exemplar_eta_fu_tables,
  fu_allocation_table,
  which_quantity = c(IEATools::template_cols$eta_fu, IEATools::template_cols$phi_u),
  country = IEATools::iea_cols$country,
  method = IEATools::iea_cols$method,
  energy_type = IEATools::iea_cols$energy_type,
  last_stage = IEATools::iea_cols$last_stage,
  e_dot = IEATools::iea_cols$e_dot,
  unit = IEATools::iea_cols$unit,
  year = IEATools::iea_cols$year,
  ledger_side = IEATools::iea_cols$ledger_side,
  flow_aggregation_point = IEATools::iea_cols$flow_aggregation_point,
  machine = IEATools::template_cols$machine,
  eu_product = IEATools::template_cols$eu_product,
  e_dot_perc = IEATools::template_cols$e_dot_perc,
  e_dot_machine = IEATools::template_cols$e_dot_machine,
  e_dot_machine_perc = IEATools::template_cols$e_dot_machine_perc,
  ef_product = IEATools::template_cols$ef_product,
  destination = IEATools::template_cols$destination,
  eta_fu = IEATools::template_cols$eta_fu,
  phi_u = IEATools::template_cols$phi_u,
  quantity = IEATools::template_cols$quantity,
  maximum_values = IEATools::template_cols$maximum_values,
  c_source = IEATools::template_cols$c_source,
  eta_fu_source = IEATools::template_cols$eta_fu_source,
  .values = IEATools::template_cols$.values
)

Arguments

eta_fu_table: The efficiency table to be completed, possibly having missing incomplete rows. Note that efficiency tables can include energy efficiencies (eta_fu) and exergy-to-energy ratios (phi.u).
exemplar_eta_fu_tables: A list of efficiency tables, each queried in turn for information needed by eta_fu_table. Similar to eta_fu_table, exemplar tables can include energy efficiencies (eta_fu) and exergy-to-energy ratios (phi.u).
fu_allocation_table: An FU (final-to-useful) allocation table from which the needed combinations of final-to-useful machines and useful products is determined. This data frame can be "tidy" or wide by year.
which_quantity: A vector of quantities to be completed in the eta_FU table. Default is c(IEATools::template_cols$eta_fu, IEATools::template_cols$phi_u). Must be one or both of the default values.
country, method, energy_type, ledger_side, flow_aggregation_point, last_stage, e_dot, unit, year: See IEATools::iea_cols.
machine, eu_product, e_dot_perc, e_dot_machine, e_dot_machine_perc, eta_fu, phi_u, quantity, maximum_values, ef_product, destination, c_source, eta_fu_source, .values: See IEATools::template_cols.

Value

A tidy version of eta_fu_table with missing values filled from exemplar_eta_fu_tables.

Details

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

fu_allocation_table supplies information about which data are needed for a complete FU Efficiency table. The fu_allocation_table data frame should be obtained from a call to load_fu_allocation_data().

If eta_fu_table can't be completed (because not enough information is available in exemplar_eta_fu_tables), a warning is emitted and a data frame is returned containing rows from fu_allocation_table that were not found.

Examples

# Load efficiency tables
eta_fu_table <- load_eta_fu_data()
eta_fu_table_GHA <- eta_fu_table %>% 
  dplyr::filter(.data[[IEATools::iea_cols$country]] == "GHA")
eta_fu_table_ZAF <- eta_fu_table %>% 
  dplyr::filter(.data[[IEATools::iea_cols$country]] == "ZAF")
# Load an FU Allocation table
fu_allocation_table <- load_fu_allocation_data() %>% 
  dplyr::select(!IEATools::template_cols$maximum_values) %>% 
  dplyr::filter(!.data[[IEATools::template_cols$quantity]] 
    %in% c(IEATools::iea_cols$e_dot, 
           IEATools::template_cols$e_dot_perc)) %>% 
  # Make it tidy
  tidyr::pivot_longer(cols = year_cols(., return_names = TRUE), 
                      names_to = IEATools::iea_cols$year,
                      values_to = IEATools::template_cols$.values) %>% 
  dplyr::filter(!is.na(.data[[IEATools::template_cols$.values]]))
fu_allocation_table_GHA <- fu_allocation_table %>% 
  dplyr::filter(.data[[IEATools::iea_cols$country]] == "GHA") 
# Eliminate 2 machines (Automobiles and Irons) from GHA and 
# see if their efficiencies get picked up from ZAF and World.
eta_fu_table_GHA_incomplete <- eta_fu_table_GHA %>% 
  dplyr::filter(.data[[IEATools::template_cols$machine]] != "Automobiles", 
                .data[[IEATools::template_cols$machine]] != "Irons")
# Make exemplar tables from ZAF.
# The first exemplar (ZAF) will have Automobiles but not Irons.
exemplar_ZAF <- eta_fu_table_ZAF %>% 
  dplyr::filter(.data[[IEATools::template_cols$machine]] != "Irons")
# The second exemplar (World) will have Irons, but not Automobiles.
exemplar_World <- eta_fu_table_ZAF %>% 
  dplyr::filter(.data[[IEATools::template_cols$machine]] != "Automobiles") %>% 
  dplyr::mutate(
    "{IEATools::iea_cols$country}" := "World"
  )
# Now call the completion function to pick up Automobiles from ZAF and Irons from World
completed <- complete_eta_fu_table(
               eta_fu_table = eta_fu_table_GHA_incomplete,
               exemplar_eta_fu_tables = list(exemplar_ZAF, exemplar_World), 
               fu_allocation_table = fu_allocation_table_GHA)
# Check that we got Automobiles from ZAF
completed %>% 
  dplyr::filter(.data[[IEATools::template_cols$machine]] == "Automobiles", 
                .data[[IEATools::template_cols$eta_fu_source]] == "ZAF")
#> # A tibble: 4 × 10
#>   Country Method EnergyType LastStage Machine     EuProduct Quantity  Year Value
#>   <chr>   <chr>  <chr>      <chr>     <chr>       <chr>     <chr>    <dbl> <dbl>
#> 1 GHA     PCM    E          Final     Automobiles MD        etafu     1971  0.3 
#> 2 GHA     PCM    E          Final     Automobiles MD        etafu     2000  0.31
#> 3 GHA     PCM    E          Final     Automobiles MD        phiu      1971  1   
#> 4 GHA     PCM    E          Final     Automobiles MD        phiu      2000  1   
#> # ℹ 1 more variable: etafuSource <chr>
# Check that we got Irons from World
completed %>% 
  dplyr::filter(.data[[IEATools::template_cols$machine]] == "Irons", 
                .data[[IEATools::template_cols$eta_fu_source]] == "World")
#> # A tibble: 4 × 10
#>   Country Method EnergyType LastStage Machine EuProduct Quantity  Year Value
#>   <chr>   <chr>  <chr>      <chr>     <chr>   <chr>     <chr>    <dbl> <dbl>
#> 1 GHA     PCM    E          Final     Irons   MTH.200.C etafu     1971 0.3  
#> 2 GHA     PCM    E          Final     Irons   MTH.200.C etafu     2000 0.35 
#> 3 GHA     PCM    E          Final     Irons   MTH.200.C phiu      1971 0.370
#> 4 GHA     PCM    E          Final     Irons   MTH.200.C phiu      2000 0.370
#> # ℹ 1 more variable: etafuSource <chr>