Add a column of matrix names to tidy data frame

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.

Value

.tidy_iea_df with an added column 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.

Examples

library(dplyr)
load_tidy_iea_df() %>% 
  add_psut_matnames() %>%
  glimpse()
#> Rows: 403
#> Columns: 12
#> $ Country                <chr> "GHA", "GHA", "GHA", "GHA", "GHA", "GHA", "GHA"…
#> $ Method                 <chr> "PCM", "PCM", "PCM", "PCM", "PCM", "PCM", "PCM"…
#> $ Energy.type            <chr> "E", "E", "E", "E", "E", "E", "E", "E", "E", "E…
#> $ Last.stage             <chr> "Final", "Final", "Final", "Final", "Final", "F…
#> $ Year                   <dbl> 1971, 2000, 1971, 2000, 1971, 2000, 2000, 2000,…
#> $ Ledger.side            <chr> "Supply", "Supply", "Supply", "Supply", "Supply…
#> $ Flow.aggregation.point <chr> "Total primary energy supply", "Total primary e…
#> $ Flow                   <chr> "Production", "Production", "Production", "Prod…
#> $ Product                <chr> "Primary solid biofuels", "Primary solid biofue…
#> $ Unit                   <chr> "TJ", "TJ", "TJ", "TJ", "TJ", "TJ", "TJ", "TJ",…
#> $ E.dot                  <dbl> 87399.9985, 162908.9993, 10472.4010, 23792.3995…
#> $ matnames               <chr> "V", "V", "V", "V", "R", "R", "R", "R", "R", "R…