extend_to_useful: Move an ECC from final to useful as its last stage

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

Move an ECC from final to useful as its last stage

Description

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_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 1e-3.
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_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.

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.

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

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()

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