add_psut_matnames: Add a column of matrix names to tidy data frame

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

Add a column of matrix names to tidy data frame

Description

This function adds a column of matrix names to a tidy data frame wherein each row of .tidy_iea_df is a single value in an energy conversion chain. The default argument values assume that .tidy_iea_df uses IEA-style nomenclature and terminology, although .tidy_iea_df does not necessarily need to contain IEA data. In a typical workflow, this function would be followed by a call to add_row_col_meta() and matsindf::collapse_to_matrices().

Usage

add_psut_matnames(
  .tidy_iea_df,
  R_includes_all_exogenous_flows = TRUE,
  ledger_side = IEATools::iea_cols$ledger_side,
  flow_aggregation_point = IEATools::iea_cols$flow_aggregation_point,
  flow = IEATools::iea_cols$flow,
  product = IEATools::iea_cols$product,
  e_dot = IEATools::iea_cols$e_dot,
  supply = IEATools::ledger_sides$supply,
  consumption = IEATools::ledger_sides$consumption,
  production = IEATools::tpes_flows$production,
  resources = IEATools::tpes_flows$resources,
  eiou = IEATools::tfc_compare_flows$energy_industry_own_use,
  pos_supply_in_R = c(IEATools::tpes_flows$resources, IEATools::tpes_flows$imports,
    IEATools::tpes_flows$international_aviation_bunkers,
    IEATools::tpes_flows$international_marine_bunkers,
    IEATools::tfc_compare_flows$statistical_differences,
    IEATools::tpes_flows$stock_changes),
  neg_supply_in_fd = c(IEATools::tpes_flows$exports,
    IEATools::tpes_flows$international_aviation_bunkers,
    IEATools::tpes_flows$international_marine_bunkers,
    IEATools::tpes_flows$stock_changes, IEATools::tfc_compare_flows$losses,
    IEATools::tfc_compare_flows$statistical_differences),
  matnames = IEATools::mat_meta_cols$matnames,
  R = IEATools::psut_cols$R,
  U_feed = IEATools::psut_cols$U_feed,
  U_EIOU = IEATools::psut_cols$U_eiou,
  V = IEATools::psut_cols$V,
  Y = IEATools::psut_cols$Y
)

Arguments

.tidy_iea_df	a data frame with ledger_side, flow_aggregation_point, flow, and e_dot columns.
R_includes_all_exogenous_flows	Tells how to construct the R matrix. Default is TRUE. See details.
ledger_side, flow_aggregation_point, flow, product, e_dot	See IEATools::iea_cols.
supply, consumption	See IEATools::ledger_sides.
production, resources	See IEATools::tpes_flows.
eiou	See IEATools::tfc_compare_flows.
pos_supply_in_R	For "Resources", "Imports", "Statistical differences", "X Bunkers", and "Stock changes", positive flows should be placed in the R matrix. See IEATools::tfc_compare_flows.
neg_supply_in_fd	For "Exports", "International aviation bunkers", "International marine bunkers", and "Stock changes", see IEATools::tpes_flows. For "Losses" and "Statistical differences", see IEATools::tfc_compare_flows.
matnames	See IEATools::mat_meta_cols.
R, U_feed, U_EIOU, V, Y	See IEATools::psut_matnames.

Details

This function respects groups when identifying entries in the resource matrix (R). So be sure to group .tidy_iea_df before calling this function.

If .tidy_iea_df already has a matnames column, this function returns the .tidy_iea_df without modification, assuming that the caller has already supplied a destination matrix name for each row of .tidy_iea_df.

The argument R_includes_all_exogenous_flows controls how the R matrix is formed. When TRUE, all exogenous flows (including Resources, Production, Bunkers, Imports, Statistical differences, and Stock changes) are placed in the R matrix. When FALSE, only Resources and Production are placed in the R matrix. Default is TRUE. FALSE retains previous behavior.

Value

.tidy_iea_df with an added column matnames.

Examples

library(dplyr)
load_tidy_iea_df() %>% 
  add_psut_matnames() %>%
  glimpse()

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