Move an ECC from final to useful as its last stage

move_to_useful_last_stage(
  .tidy_psut_data,
  tidy_C_data,
  tidy_eta_fu_data,
  last_stage = IEATools::iea_cols$last_stage,
  unit = IEATools::iea_cols$unit,
  final = IEATools::last_stages$final,
  useful = IEATools::last_stages$useful,
  R = IEATools::psut_cols$R,
  U_eiou = IEATools::psut_cols$U_eiou,
  U_excl_eiou = IEATools::psut_cols$U_excl_eiou,
  V = IEATools::psut_cols$V,
  Y = IEATools::psut_cols$Y,
  matnames = IEATools::mat_meta_cols$matnames,
  matvals = IEATools::mat_meta_cols$matvals,
  C_eiou = IEATools::template_cols$C_eiou,
  C_Y = IEATools::template_cols$C_Y,
  eta_fu = IEATools::template_cols$eta_fu,
  .useful = ".useful",
  .eta_fu_hat = ".eta_fu_hat"
)

Arguments

.tidy_psut_data	A tidy data frame of PSUT matrices that represent an energy conversion chain. Matrix names should be in the `matnames` column, and matrices themselves should be in the `matvals` column. The last stage of these ECCs should be final (not useful). `.tidy_psut_data` is likely the result of calling (in sequence) `load_tidy_iea_df()` `%>%` `specify_all()` `%>%` `prep_psut()`
tidy_C_data	a tidy data frame of final-to-useful allocation matrices, probably the result of calling `form_C_mats()`.
tidy_eta_fu_data	a tidy data frame of final-to-useful machine efficiency matrices, probably the result of calling `form_eta_fu_phi_u_vecs`.
last_stage, unit	See `IEATools::iea_cols$last_stage`. Each of these should be a column in all of `.tidy_psut_data`, `C_data`, and `eta_fu_data`.
final, useful	See `IEATools::last_stages`.
R, U_eiou, U_excl_eiou, V, Y	See `IEATools::psut_cols`. These matrices should be found in the `matvals` column of the `.tidy_psut_data` data frame.
matnames, matvals	See `IEATools::mat_meta_cols`.
C_eiou, C_Y, eta_fu	See `IEATools::template_cols`. `C_eiou` and `C_Y` matrices should be found in the `matvals` column of the `C_Y_data` data frame. `eta_fu` should be found in the `matvals` column of the `eta_fu_data` data frame.
.useful	A suffix applied to versions of PSUT matrices where useful is the last stage. Default is ".useful".
.eta_fu_hat	an internal matrix name. Default is ".eta_fu_hat".

Value

a version of .tidy_sut_data that contains additional rows with useful final stage ECC matrices