Writing Annex Stats to Disc

TODO(R)

Usage

annex_write_stats(x, file, user, mode = "write", ..., quiet = FALSE)

Arguments

x

object of class annex_stat as returned by annex_stats() (wide or long format).

file

name (or path) to the XLSX file where to store the data. Must end with xlsx (not case sensitive). See 'Details'.

user

positive integer, the user identifier given by the project team. Will be appended to the data set.

mode,

character, writing mode. Can be one of "write" (default), "append" (add new data) or "update" (update existing data). See 'Mode' for more information.

...

not yet used.

quiet

logical. If set TRUE messages will be printed.

Value

No return, creates a new XLSX file (see argument file) and stores the data, or updates an existing XLSX file (see argument section 'Writing mode').

Details

This function is used to write the annex statistics - the final output - into an XLSX file. The output is based on a template file shipped with the package with a predefined format.

If the output file does not exist, the template will be copied and modified by (i) saving the data into the "STAT" sheet as well as pre-filling some additional meta sheets which have to be manually edited/entered by the user.

By default, overwrite = FALSE. If the output file already exists, the function will be terminated. However, it can be set to TRUE to allow annex_write_stats() to manipulate/overwrite the current data in that XLSX file. It tries to preserve all custom data (TODO(R): not yet implemented).

Writing mode

There are three writing modes. Warning: Depending on the mode used, existing data can get lost (i.e., removed). The following modes are available:

write: Default mode, write data into a fresh XLSX file. It is assumed that the output file does not yet exist. If it exists an error will be thrown as it is unkown if the user would like to append new data to an existing file or update (overwrite) data in an existing file.

append: Append data to an existing XLSX file. This mode expects that the file does already exist and is in the correct format (will check sheets and columns against the template). If file does not exist or the content of file does not follow the format of the template, an error will be thrown.

mode = "append" falls back to mode = "write" if the output file does not yet exist.

Else the data of x will be appended to the sheet 'STAT' and additional entries in the 'META*' sheets will be created if needed. In case the new object x contains data which are already in STAT an error will be thrown (so the new data to be appended must be unique).

update: Update the data of an existing file. Warning: this will delete (drop) existing data in the sheet 'STAT' and append new entries in the 'META*' sheets (won't delete existing entries). The latter could cause additional warnings when validating the file if there are 'META*' entries which are no longer needed (as the data have been deleted).

Author

Reto Stauffer