Skip to contents

Write energy conversion chain matrices to an Excel file

Source: R/excel.R
write_ecc_to_excel.Rd

It is often helpful to see energy conversion chain (ECC) matrices in Excel format, arranged spatially. This function takes ECC matrices and writes them to an Excel file.

Usage

write_ecc_to_excel(
  .psut_data = NULL,
  path,
  overwrite_file = FALSE,
  worksheet_names = NULL,
  pad = 2,
  include_named_regions = TRUE,
  R = Recca::psut_cols$R,
  U = Recca::psut_cols$U,
  V = Recca::psut_cols$V,
  Y = Recca::psut_cols$Y,
  r_eiou = Recca::psut_cols$r_eiou,
  U_eiou = Recca::psut_cols$U_eiou,
  U_feed = Recca::psut_cols$U_feed,
  S_units = Recca::psut_cols$S_units,
  .wrote_mats_colname = "Wrote mats",
  UV_bg_color = "#FDF2D0",
  RY_bg_color = "#D3712D",
  calculated_bg_color = "#D9D9D9",
  col_widths = 7
)

Arguments

.psut_data

A list or data frame of energy conversion chains. Default is NULL, in which case single matrices can be supplied in the R, U, V, Y, r_eiou, U_eiou, U_feed, and S_units arguments.

path

The path of the Excel file to be created.

overwrite_file

A boolean that tells whether you want to overwrite the file at path, if it already exists. Default is FALSE.

worksheet_names

A string or string vector identifying the names for the worksheets in the workbook. Alternatively, when .psut_data is a data frame, the string name of a column in the data frame containing the names of the worksheets. When NULL, the default, tabs are numbered sequentially.

pad

The number of rows and columns between adjacent matrices in the Excel sheet. Default is 2.

include_named_regions

A boolean that tells whether to name regions of the Excel tabs according to matrices. Default is TRUE.

R, U, U_feed, U_eiou, r_eiou, V, Y, S_units

Names of ECC matrices or actual matrices. See Recca::psut_cols.

.wrote_mats_colname

The name of the outgoing column that tells whether a worksheet was written successfully. Default is "Wrote mats".

UV_bg_color

The color of cells containing U and V matrices. Default is a creamy yellow.

RY_bg_color

The color of cells containing R and Y matrices. Default is a rust color.

calculated_bg_color

The color of cells containing calculated matrices. Default is gray.

col_widths

The widths of columns of matrices. Default is 7 to save space.

Value

An unmodified version of .psut_data (if not NULL) or a list of the incoming matrices.

Details

If .psut_data is a PSUT data frame, each row is written to a different tab in the output file at path.

When worksheet_names is not NULL (the default), be sure that worksheet names are unique. Also, be aware that worksheet names must have 31 characters or fewer. Furthermore, the worksheet names may not contain any of the following characters: \ / ? * [ ].

When include_named_regions is TRUE (the default), named regions for matrices are added to Excel sheets. The format for the names is <<matrix symbol>>_<<worksheet name>>. For example, "R_4" for the R matrix on the sheet named "4". The names help to identify matrices in high-level overviews of the Excel file and can also be used for later reading matrices from Excel files. The region names apply to the numbers in a matrix only, not to the row and column labels. Row names are one column left of the named region. Column names are one row above the named region.

Note that region names are more restricted than worksheet names and may not contain any of the following characters: ! @ # $ % ^ & * ( ) + - / = { } [ ] | \ : ; " ' < > , . ? spaces. Best to stick with letters, numbers, and underscores.

Finally, note that because region names include the worksheet name, worksheet names should avoid illegal characters for region names. Again, best to stick with letters, numbers, and underscores.

A warning is given when any worksheet names or region names contain illegal characters.

[ ]: R:%20%20 [ ]: R:%20

Examples

if (FALSE) { # \dontrun{
ecc <- UKEnergy2000mats %>%
  tidyr::pivot_wider(names_from = "matrix.name",
                     values_from = "matrix") |>
dplyr::mutate(
  # Specify worksheet names using metadata guaranteed to be unique.
  worksheet_names = paste(EnergyType, LastStage, sep = "_")
)
ecc_temp_path <- tempfile(pattern = "write_excel_ecc_test_file", fileext = ".xlsx")
write_ecc_to_excel(ecc,
                   path = ecc_temp_path,
                   worksheet_names = "worksheet_names",
                   overwrite = TRUE)
} # }