Move an ECC from final to useful as its last stage — extend_to

This function uses a matrix method to move from final energy/exergy to useful energy/exergy as the last stage of an energy conversion chain.

Usage

extend_to_useful(
  .sutdata = NULL,
  tol = 0.1,
  R = IEATools::psut_cols$R,
  U_feed = IEATools::psut_cols$U_feed,
  U_eiou = IEATools::psut_cols$U_eiou,
  U = IEATools::psut_cols$U,
  r_eiou = IEATools::psut_cols$r_eiou,
  V = IEATools::psut_cols$V,
  Y = IEATools::psut_cols$Y,
  C_eiou = IEATools::template_cols$C_eiou,
  C_Y = IEATools::template_cols$C_Y,
  eta_fu = IEATools::template_cols$eta_fu,
  phi_u = IEATools::template_cols$phi_u,
  last_stage = IEATools::iea_cols$last_stage,
  final = IEATools::last_stages$final,
  useful = IEATools::last_stages$useful,
  industry_type = IEATools::row_col_types$industry,
  product_type = IEATools::row_col_types$product,
  interface_ind = IEATools::interface_industries,
  losses = IEATools::tfc_compare_flows$losses,
  stat_diffs = IEATools::tfc_compare_flows$statistical_differences,
  arrow_note = RCLabels::arrow_notation,
  from_note = RCLabels::from_notation,
  .add_to_U_f = ".add_to_U_f",
  .add_to_U_eiou = ".add_to_U_eiou",
  .add_to_V_f = ".add_to_V_f",
  .add_to_dest = ".repl_dest",
  details_fu = "details_fu",
  .err = ".err",
  .e_bal_ok = ".e_bal_ok",
  .sep = "_",
  U_eiou_details_default_rownames = RCLabels::paste_pref_suff(pref =
    IEATools::electricity_products$electricity, suff =
    IEATools::transformation_processes$main_activity_producer_electricity_plants,
    notation = arrow_note),
  U_eiou_details_default_colnames = RCLabels::paste_pref_suff(pref = "L", suff =
    "Industrial electric lamps", notation = from_note),
  U_feed_name = IEATools::psut_cols$U_feed,
  U_eiou_name = IEATools::psut_cols$U_eiou,
  U_name = IEATools::psut_cols$U,
  r_eiou_name = IEATools::psut_cols$r_eiou,
  V_name = IEATools::psut_cols$V,
  Y_name = IEATools::psut_cols$Y,
  Y_fu_details_name = IEATools::psut_cols$Y_fu_details,
  U_eiou_fu_details_name = IEATools::psut_cols$U_eiou_fu_details
)

Arguments

.sutdata: A wide-by-matrices data frame of PSUT matrices that represent an energy conversion chain. Each row of .sutdata should contain the matrices that represent one energy conversion chain. Matrices should be in columns identified by their names. The last stage of these ECCs should be final (not useful). .sutdata is likely the result of calling (in sequence) load_tidy_iea_df(), specify_all(), and prep_psut(). .sutdata should also include columns of matrices C_Y, C_eiou, and eta_fu, probably created by functions form_C_mats() and form_eta_fu_phi_u_vecs(). .sutdata can also be a named list of matrices that forms a store of variables. Default is NULL to enable use of single matrices, too.
tol: The allowable error in energy balances for the outgoing matrices (last stage useful). Default is 0.1.
R, U_eiou, U_feed, U, r_eiou, V, Y: See IEATools::psut_cols. These should be strings (if .sutdata is a data frame or a list) or individual matrices (if .sutdata is NULL).
C_eiou, C_Y, eta_fu, phi_u: See IEATools::template_cols. These should be strings (if .sutdata is a data frame or a list) or individual matrices (if .sutdata is NULL).
last_stage: See IEATools::iea_cols$last_stage.
final, useful: See IEATools::last_stages.
industry_type, product_type: See IEATools::row_col_types
interface_ind: See IEATools::interface_industries. Interface industries are kept same from Y_final to Y_useful.
losses: See IEATools::tfc_compare_flows. Losses are kept same from Y_final to Y_useful.
stat_diffs: See IEATools::tfc_compare_flows. Statistical differences are kept same from Y_final to Y_useful.
arrow_note, from_note: The row and column notation in the eta_fu vectors. See RCLabels::notation_vec(). Defaults is RCLabels::arrow_notation and RCLabels::from_notation.
.add_to_U_f: An internal matrix name for the a matrix to be added to the U_feed_f matrix to form the useful form of the U_feed matrix. Default is ".add_to_U_f".
.add_to_U_eiou: An internal matrix name for the a matrix to be added to the U_eiou_f matrix to form the useful form of the U_eiou matrix. Default is ".add_to_U_eiou".
.add_to_V_f: An internal matrix name for a matrix to add to the Y_f matrix. Default is ".add_to_V_f".
.add_to_dest: An internal matrix name for a matrix that replaces a previous energy destination. Default is ".repl_dest".
details_fu: An internal matrix name for a matrix that contains detailed information about the final-to-useful extension, namely, final energy product, destination sector, final-to-useful machine, and useful energy product.
.err: An internal matrix name for calculating energy balance errors. Default is ".err".
.e_bal_ok: An internal column name for assessing whether energy balance is within acceptable tolerances set by the tol argument. Default is ".e_bal_OK".
.sep: A separator between matrix names and final or useful indicators. Default is "_".
U_eiou_details_default_rownames, U_eiou_details_default_colnames: Default row and column names for the U_EIOU_fu_details matrices when there is no EIOU.
U_eiou_name, U_feed_name, U_name, r_eiou_name, V_name, Y_name, Y_fu_details_name, U_eiou_fu_details_name: See IEATools::psut_cols. Distinct from U_feed,U_eiou, U, r_eiou, V, and Y (which can be matrices or strings), these variables determine the names of these matrices on output. Default values are taken from IEATools::psut_cols. Note that .sep and useful are appended to the strings in U_eiou_name ... Y_name to form the output names.

Value

Output depends on input, roughly according to conventions in matsindf::apply(). If .sutdata is NULL and individual matrices are supplied in U_eiou, U_feed, U, r_eiou, V, and Y arguments, output is a named list of individual matrices with .sep and useful appended. If .sutdata is a named list of individual matrices, the output is a list of matrices with .sep and final or .sep and useful appended to the names. If .sutdata is a data frame, output will be a data frame of matrices with column names with with .sep and final or .sep and useful appended to the names (when gather = FALSE). If .sutdata is a data frame, output will be a data frame of matrices with a last.stage column containing final or useful and columns named for matrices (when gather = TRUE, the default).

Details

.sutdata or individual matrices are always assumed to have final energy as its last stage.

Internally, this function uses matsindf::matsindf_apply() to perform its calculations. If .sutdata is NULL, and R, U_eiou, U_feed, U, r_eiou, V, and Y are individual matrices, the output is a named list of matrices containing new values for U_eiou, U_feed, U, r_eiou, V, and Y matrices, named with .sep plus useful appended to the variable names.

If .sutdata is a named list of matrices, output is a list of matrices with names appended to include .sep and useful, where appropriate. Note that output matrices are appended to the original list supplied to .sutdata.

If .sutdata is a data frame, arguments R, U_feed, U_eiou, U, r_eiou, V, Y, C_eiou, C_Y, eta_fu, and phi_u should all be strings (as the default) identifying which columns in .sutdata should be used for each matrix. Output is a data frame with additional columns with names appended with paste0(.sep, useful).

If final and useful versions of matrices are desired to be stacked (rbinded), call stack_final_useful_df() subsequent to calling extend_to_useful().

An energy balance check is performed on the useful matrices. If the energy balance check fails, a warning is emitted and additional diagnostic information will appear in the output: .err and .e_bal_ok.

If .sutdata is a data frame with no rows or a list of length 0, NULL is returned.

Examples

C_data <- load_fu_allocation_data() %>% 
  form_C_mats()
eta_fu_data <- load_eta_fu_data() %>% 
  form_eta_fu_phi_u_vecs()
m_cols <- eta_fu_data %>% 
  IEATools::meta_cols(return_names = TRUE,
                      years_to_keep = IEATools::iea_cols$year,
                      not_meta = c(IEATools::template_cols$eta_fu,
                                   IEATools::template_cols$phi_u))
psut_mats <- load_tidy_iea_df() %>% 
  specify_all() %>% 
  prep_psut()
extended_to_useful <- psut_mats |> 
  dplyr::full_join(C_data, by = m_cols) %>% 
  dplyr::full_join(eta_fu_data, by = m_cols) |> 
  extend_to_useful()
extended_to_useful %>% 
  head()
#> # A tibble: 4 × 25
#>   Country Method EnergyType LastStage  Year Y        S_units  R        U       
#>   <chr>   <chr>  <chr>      <chr>     <dbl> <list>   <list>   <list>   <list>  
#> 1 GHA     PCM    E          Final      1971 <dbl[…]> <dbl[…]> <dbl[…]> <dbl[…]>
#> 2 GHA     PCM    E          Final      2000 <dbl[…]> <dbl[…]> <dbl[…]> <dbl[…]>
#> 3 ZAF     PCM    E          Final      1971 <dbl[…]> <dbl[…]> <dbl[…]> <dbl[…]>
#> 4 ZAF     PCM    E          Final      2000 <dbl[…]> <dbl[…]> <dbl[…]> <dbl[…]>
#> # ℹ 16 more variables: U_feed <list>, U_EIOU <list>, r_EIOU <list>, V <list>,
#> #   C_EIOU <list>, C_Y <list>, etafu <list>, phiu <list>, U_feed_Useful <list>,
#> #   U_EIOU_Useful <list>, U_Useful <list>, r_EIOU_Useful <list>,
#> #   V_Useful <list>, Y_Useful <list>, Y_fu_details <list>,
#> #   U_EIOU_fu_details <list>