write_fu_allocation_template: Write blank final-to-useful templates

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

Write blank final-to-useful templates

Description

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 IEATools::iea_cols$ledger_side.
consumption	the string identifier for consumption in the ledger_side column. Default is IEATools::ledger_sides$consumption.
flow_aggregation_point	the name of the flow aggregation point column in .tidy_iea_df. Default is IEATools::iea_cols$flow_aggregation_point.
eiou	the string identifier for energy industry own use in the flow_aggregation_point column. Default is IEATools::tfc_compare_flows$energy_industry_own_use.
fu_allocations_tab_name	the name of the tab on which the template will be written. Default is IEATools::fu_analysis_file_info$fu_allocation_tab_name.
machine	the name of the machine column in output. Default is IEATools::template_cols$machine.
eu_product	the name of the useful energy product column in output. Default is IEATools::template_cols$eu_product.
quantity	the name of the quantity column to be created on output. Default is IEATools::template_cols$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 "Edot".
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 "Edot.perc".
maximum_values	the name of the maximum values column in output. Default is IEATools::template_cols$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".

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.

Value

the value of the path argument

Examples

f <- tempfile(fileext = ".xlsx")
load_tidy_iea_df() %>% 
  specify_all() %>% 
  fu_allocation_template() %>% 
  write_fu_allocation_template(f)
if (file.exists(f)) {
  file.remove(f)
}

MatthewHeun/IEATools documentation built on Dec. 14, 2024, 12:08 a.m.