Skip to contents

Create allocation matrices (C) from an allocation table

form_C_mats.Rd

This function uses information in a filled allocation template (created by write_fu_allocation_template()) to create allocation matrices (C).

Usage

form_C_mats(
  .fu_allocation_table,
  matrix_class = c("matrix", "Matrix"),
  ledger_side = IEATools::iea_cols$ledger_side,
  flow_aggregation_point = IEATools::iea_cols$flow_aggregation_point,
  e_dot = IEATools::iea_cols$e_dot,
  unit = IEATools::iea_cols$unit,
  year = IEATools::iea_cols$year,
  supply = IEATools::ledger_sides$supply,
  consumption = IEATools::ledger_sides$consumption,
  quantity = IEATools::template_cols$quantity,
  machine = IEATools::template_cols$machine,
  ef_product = IEATools::template_cols$ef_product,
  eu_product = IEATools::template_cols$eu_product,
  destination = IEATools::template_cols$destination,
  e_dot_perc = IEATools::template_cols$e_dot_perc,
  maximum_values = IEATools::template_cols$maximum_values,
  matnames = IEATools::mat_meta_cols$matnames,
  matvals = IEATools::mat_meta_cols$matvals,
  rownames = IEATools::mat_meta_cols$rownames,
  colnames = IEATools::mat_meta_cols$colnames,
  rowtypes = IEATools::mat_meta_cols$rowtypes,
  coltypes = IEATools::mat_meta_cols$coltypes,
  product = IEATools::row_col_types$product,
  industry = IEATools::row_col_types$industry,
  notation = RCLabels::arrow_notation,
  tol = 1e-06,
  C_eiou = IEATools::template_cols$C_eiou,
  C_Y = IEATools::template_cols$C_Y,
  .should_be_1_vector = ".should_be_1_vector",
  .is_1 = ".is_1",
  .all_1 = ".all_1"
)

Arguments

.fu_allocation_table

a final-to-useful allocation table read by load_fu_allocation_data(). A template for this table should have been created by fu_allocation_table() and write_fu_allocation_table(). This object can also be a tidy data frame with year data gathered into a Year column.

matrix_class

The type of matrix to be created, one of "matrix" or "Matrix". Default is "matrix".

ledger_side, flow_aggregation_point, e_dot, unit, year

See IEATools::iea_cols.

supply, consumption

See IEATools::ledger_sides.

quantity, machine, ef_product, eu_product, destination, e_dot_perc, maximum_values, C_eiou, C_Y

See IEATools::template_cols.

matnames, matvals, rownames, colnames, rowtypes, coltypes

See IEATools::mat_meta_cols.

product, industry

See IEATools::row_col_types.

notation

The notation used for this template. See RCLabels::notation_vec(). Default is RCLabels::arrow_notation.

tol

The allowable amount by which a row sum in a C matrix can be different from 1. Default is 1e-6.

.should_be_1_vector

A temporary column created internally for error checking (and not returned unless there is an error). This column should contain 1 vectors (i.e., vectors filled with 1's).

.is_1

A temporary column created internally (and not returned unless there is an error) that contains TRUE or FALSE depending on whether a rowsum was 1.

.all_1

A temporary column created internally (and not returned unless there is an error) that tells whether a 1-vector was created by rowsums.

Value

A wide-by-matrices data frame with metadata columns (and year) along with columns for C_eiou and C_Y matrices. If not all rows of a C matrix sum to 1, a warning is emitted, and a data frame is returned which shows the errors.

Details

rownames of the C matrices are taken from the Ef.product and Destination columns of .fu_allocation_table and have the form "Ef.product -> Destination". colnames of the C matrices are taken from the Machine and Eu.product columns of .fu_allocation_table and have the form "machine -> useful energy form".

C matrices are created for both energy industry own use and final demand (C_eiou and C_Y, respectively).

Rows of the output C matrices should sum to 1. If there is a problem, a data frame that shows the errors is returned. Such errors probably indicate the FU template was not filled correctly.

Examples

load_fu_allocation_data() %>% 
  form_C_mats()
#> # A tibble: 4 × 7
#>   Country Method Energy.type Last.stage  Year C_EIOU        C_Y            
#>   <chr>   <chr>  <chr>       <chr>      <dbl> <list>        <list>         
#> 1 GHA     PCM    E           Final       1971 <dbl [2 × 3]> <dbl [23 × 21]>
#> 2 GHA     PCM    E           Final       2000 <dbl [2 × 3]> <dbl [24 × 20]>
#> 3 ZAF     PCM    E           Final       1971 <dbl [3 × 3]> <dbl [45 × 30]>
#> 4 ZAF     PCM    E           Final       2000 <dbl [8 × 5]> <dbl [95 × 41]>