Write blank final-to-useful templates — write_fu_allocation

The analyst often starts with IEA extended energy balance data covering primary and final energy stages. This function writes a blank Excel template file that, when filled, allow the energy conversion chain to be extended to the useful stage. This function saves an Excel workbook to path that contains an analyst's template.

Usage

write_fu_allocation_template(
  .fu_allocation_template,
  path,
  ledger_side = IEATools::iea_cols$ledger_side,
  consumption = IEATools::ledger_sides$consumption,
  flow_aggregation_point = IEATools::iea_cols$flow_aggregation_point,
  eiou = IEATools::tfc_compare_flows$energy_industry_own_use,
  fu_allocations_tab_name = IEATools::fu_analysis_file_info$fu_allocation_tab_name,
  machine = IEATools::template_cols$machine,
  eu_product = IEATools::template_cols$eu_product,
  quantity = IEATools::template_cols$quantity,
  e_dot = IEATools::iea_cols$e_dot,
  e_dot_perc = IEATools::template_cols$e_dot_perc,
  maximum_values = IEATools::template_cols$maximum_values,
  header_row_font_color = "#FFFFFF",
  header_row_shading_color = "#5A80B8",
  energy_row_font_color_fd = "#104273",
  energy_row_shading_color_fd = "#B8D8F5",
  energy_row_font_color_eiou = "#918700",
  energy_row_shading_color_eiou = "#FCFCAB",
  dont_fill_shading_color = "#A8A8A8",
  overwrite_file = FALSE,
  n_allocation_rows = 4,
  .rownum = ".rownum"
)

Arguments

.fu_allocation_template: a data frame produced by fu_allocation_template()
path: the file path into which the blank template file will be written. Include both folder and file name. If not present, the ".xlsx" extension is added.
ledger_side: the name of the ledger side column in .tidy_iea_df. Default is "Ledger.side".
consumption: the string identifier for consumption in the ledger_side column. Default is "Consumption".
flow_aggregation_point: the name of the flow aggregation point column in .tidy_iea_df. Default is "Flow.aggregation.point".
eiou: the string identifier for energy industry own use in the flow_aggregation_point column. Default is "Energy industry own use".
fu_allocations_tab_name: the name of the tab on which the template will be written. Default is "FU Allocations".
machine: the name of the machine column in output. Default is "Machine"
eu_product: the name of the useful energy product column in output. Default is "Eu.product".
quantity: the name of the quantity column to be created on output. Default is "Quantity".
e_dot: the name of the energy flow rate column in .tidy_iea_df and the name of the energy flow rate rows to be included in the Excel file that is written by this function. Default is "E.dot".
e_dot_perc: the name of the energy flow rate percentage row to be included in the Excel file that is written by this function. Default is "E.dot.perc".
maximum_values: the name of the maximum values column in output. Default is "Maximum.values".
header_row_font_color: a hex string representing the font color for the header row in the Excel file that is written by this function. Default is "#FFFFFF", white.
header_row_shading_color: a hex string representing the shading color for the header row in the Excel file that is written by this function. Default is "#5A80B8", medium blue.
energy_row_font_color_fd: a hex string representing the font color for e_dot and e_dot_perc final demand rows in the Excel file that is written by this function. Default is "#104273", a dark blue color.
energy_row_shading_color_fd: a hex string representing the shading color for e_dot and e_dot_perc final demand rows in the Excel file that is written by this function. Default is "#104273", a light blue color.
energy_row_font_color_eiou: a hex string representing the font color for e_dot and e_dot_perc energy industry own use rows in the Excel file that is written by this function. Default is "#104273", a dark yellow color.
energy_row_shading_color_eiou: a hex string representing the shading color for e_dot and e_dot_perc energy industry own use rows in the Excel file that is written by this function. Default is "#104273", a light yellow color.
dont_fill_shading_color: a hex string representing the shading color for cells that don't require inputs. Default is "#A8A8A8", a medium gray color.
overwrite_file: a boolean that tells whether an existing file at path will be overwritten. Default is FALSE. If path already exists and overwrite = FALSE, an error is given.
n_allocation_rows: the number of allocation rows to write for each final energy product. Default is 3.
.rownum: a temporary column created internally. .rownum must not exist in .tidy_iea_df when write_fu_allocation_template is called. Default is ".rownum".

Value

the value of the path argument

Details

Allocations are to be placed in C_x rows of the template.

Formatting is applied to the template:

Gray cells indicate cells that will be ignored when the template is read later. Analysts may fill those cells, but it is not necessary to do so.
Blue cells indicate final demand energy consumption.
Yellow cells indicate energy industry own use energy consumption.
Rows are written in same order as IEA extended energy balance data.
Columns are written in a reasonable order, namely that left-to-right order approximates flow through the energy conversion chain.

Examples

f <- tempfile(fileext = ".xlsx")
load_tidy_iea_df() %>% 
  specify_all() %>% 
  fu_allocation_template() %>% 
  write_fu_allocation_template(f)
#> [1] "/tmp/Rtmp59FTd3/file17581488ec2f.xlsx"
if (file.exists(f)) {
  file.remove(f)
}
#> [1] TRUE