Author: Stefan Fleck
Date: 2023-03-26

# tatoo package vignette

#### Stefan Fleck

#### 2023-03-26

    library(magrittr)
    library(tatoo)

# Introduction

tatoo is designed for creating excel reports from lists of `data.frame`s with minimal effort, while still providing some basic formatting capabilities. tatoo functions can combine data.frames in ways that require additional effort in base R, and to add metadata (id, title, …) that can be used for printing and xlsx export. The Tatoo_report class is provided as a convenient helper to write several such tables to a workbook, one table per worksheet.

Tatoo tables and reports can directly be saved to .xlsx files, or convert to `Workbook` objects with `as_workbook()` so that you can process them further using the openxlsx package. While tatoo implements convenient print methods so that you can preview the tables you created in the console, most of the functionality provided by this package only makes real sense for xlsx export.

    df1 <- data.frame(
      Species = c("setosa", "versicolor", "virginica"),
      length = c(5.01, 5.94, 6.59),
      width = c(3.43, 2.77, 2.97)
    )

    df2 <- data.frame(
      Species = c("setosa", "versicolor", "virginica"),
      length = c(0.35, 0.52, 0.64),
      width = c(0.38, 0.31, 0.32)
    )

# Tagged tables

a table with added captions

`tag_table()` allows you to attach different levels of captioning to a data.frame or Tatoo_table. Those captions are used for printing and .xlsx export.

    # Create metadata object
    ex_meta <- tt_meta(
      table_id  = 'T01',
      title     = 'Example Table',
      longtitle = 'This is an example for tables created with the tatool package',
      subtitle  = 'It features a lot of titles and very little data',
      footer    = c('This table was created from the iris dataset',
                    'It consists of 3 different types of irises’',
                     '(Setosa, Versicolour, and Virginica)')
    )

    # Create metadata object
    tagged_table <- tag_table(
      df1,
      meta = ex_meta
    )

    print(tagged_table)

    ## T01: Example Table - This is an example for tables created with the tatool package
    ## It features a lot of titles and very little data
    ## Species    length width
    ## setosa     5.01   3.43
    ## versicolor 5.94   2.77
    ## virginica  6.59   2.97
    ## This table was created from the iris dataset
    ## It consists of 3 different types of irises’
    ## (Setosa, Versicolour, and Virginica)

Metadata can also be assigned an modified via set function.

    meta(df1)  <- ex_meta # df1 gets automatically converted to a Tagged_table

    title(df1) <- 'A table with a title'
    table_id(df1) <- NULL
    longtitle(df1) <- NULL
    subtitle(df1) <- NULL
    footer(df1) <- NULL

    print(df1)

    ## A table with a title
    ## Species    length width
    ## setosa     5.01   3.43
    ## versicolor 5.94   2.77
    ## virginica  6.59   2.97

# Mashed tables

Tables combined with alternating rows or columns

Combine two data.frames in such a way that you and up with alternating rows or columns. Internally, a Mashed_table is just a list of two or more tables, and metadata on how to combine them.

Mashed_tables can be constructed from individual data.frames or a list of data.frames

    mashed_table <- mash_table(df1, df2)
    mashed_table <- mash_table_list(list(df1, df2)) # same as above

    title(mashed_table) <- 'A mashed table'
    subtitle(mashed_table) <-
      'Two or more tables mashed together so that rows or columns alternate'

    print(mashed_table)

    ## A mashed table
    ## Two or more tables mashed together so that rows or columns alternate
    ## Species    length width
    ## setosa     5.01   3.43
    ## setosa     0.35   0.38
    ## versicolor 5.94   2.77
    ## versicolor 0.52   0.31
    ## virginica  6.59   2.97
    ## virginica  0.64   0.32

Additional formatting parameters can be saved as attributes to a mash table. Those attributes honored by the print and (more significantly) the `as_workbook()` methods.

A row-mashed table

    mashed_table_row <- mash_table(
      df1, df2,
      mash_method = 'row',
      insert_blank_row = FALSE,
      meta = tt_meta(title = 'A row-mashed table')
    )
    print(mashed_table_row)

    ## A row-mashed table
    ## Species    length width
    ## setosa     5.01   3.43
    ## setosa     0.35   0.38
    ## versicolor 5.94   2.77
    ## versicolor 0.52   0.31
    ## virginica  6.59   2.97
    ## virginica  0.64   0.32

A col-mashed table

    mashed_table_col <- mash_table(
      mean = df1, sd = df2,
      mash_method = 'col',
      id_vars = 'Species',
      meta = tt_meta(title = 'A col-mashed table')
    )

    print(mashed_table_col)

    ## A col-mashed table
    ## ..........  ..length..  ..width...
    ##    Species  mean    sd  mean    sd
    ## setosa      5.01  0.35  3.43  0.38
    ## versicolor  5.94  0.52  2.77  0.31
    ## virginica   6.59  0.64  2.97  0.32

The display parameters are just saved as attributes, and can be modified conveniently via set functions. Named mashed tables will have two layers of colnames in print and xlsx output.

    mash_method(mashed_table) <- 'col'
    id_vars(mashed_table) <- 'Species'
    names(mashed_table) <- c('mean', 'sd')

    print(mashed_table)

    ## A mashed table
    ## Two or more tables mashed together so that rows or columns alternate
    ## ..........  ..length..  ..width...
    ##    Species  mean    sd  mean    sd
    ## setosa      5.01  0.35  3.43  0.38
    ## versicolor  5.94  0.52  2.77  0.31
    ## virginica   6.59  0.64  2.97  0.32

You can also directly override the display parameters saved in the Mashed_table object for printing and xlsx export

    print(mashed_table, mash_method = 'row', insert_blank_row = TRUE)

    ## A mashed table
    ## Two or more tables mashed together so that rows or columns alternate
    ## Species    length width
    ## setosa     5.01   3.43
    ## setosa     0.35   0.38
    ##
    ## versicolor 5.94   2.77
    ## versicolor 0.52   0.31
    ##
    ## virginica  6.59   2.97
    ## virginica  0.64   0.32

All Tatoo table classes can be converted to openxlsx Workbooks via `as_workbook()`. Examples for finished .xlsx files are beyond the scope of this vignette.

    as_workbook(mashed_table)

    ## A Workbook object.
    ##
    ## Worksheets:
    ##  Sheet 1: "1"
    ##
    ##
    ##
    ##  Worksheet write order: 1
    ##  Active Sheet 1: "1"
    ##  Position: 1

## Convenience functions

`rmash()` and `cmash()` are convenient shortcut functions if you just need to quickly mash together a data.frame (similar to `rbind()` and `cbind()`). Note that the result is a data.table and not a data.frame, so if you are not familiar with the data.table package you might want to manually convert the result to a data.frame to prevent headaches.

### rmash

`rmash()` can be used on several data.frames or on an existing Mashed table.

    rmash(df1, df2)
    rmash(mashed_table)

    ##       Species length width
    ## 1:     setosa   5.01  3.43
    ## 2:     setosa   0.35  0.38
    ## 3: versicolor   5.94  2.77
    ## 4: versicolor   0.52  0.31
    ## 5:  virginica   6.59  2.97
    ## 6:  virginica   0.64  0.32

`rmash()` also supports the `insert_blank_row` argument of `Mashed_table()` for consistency.

    rmash(df1, df2, insert_blank_row = TRUE)

    ##       Species length width
    ## 1:     setosa   5.01  3.43
    ## 2:     setosa   0.35  0.38
    ## 3:
    ## 4: versicolor   5.94  2.77
    ## 5: versicolor   0.52  0.31
    ## 6:
    ## 7:  virginica   6.59  2.97
    ## 8:  virginica   0.64  0.32

### cmash

The interface of `cmash()` is very similar to `rmash()`

    cmash(df1,  df2)
    cmash(mashed_table)

    ##       Species    Species length length width width
    ## 1:     setosa     setosa   5.01   0.35  3.43  0.38
    ## 2: versicolor versicolor   5.94   0.52  2.77  0.31
    ## 3:  virginica  virginica   6.59   0.64  2.97  0.32

More polished output can be produced by naming the inputs and using the `id_vars` argument.

    cmash(mean = df1, sd = df2, id_vars = 'Species')

    ##       Species length.mean length.sd width.mean width.sd
    ## 1:     setosa        5.01      0.35       3.43     0.38
    ## 2: versicolor        5.94      0.52       2.77     0.31
    ## 3:  virginica        6.59      0.64       2.97     0.32

# Composite tables

a table with multi-column headings

`comp_table()` works like `cbind()`, but separate super-headings are preserved for each table. Names for each table can be provided directly, or alternatively the `comp_table_list()` constructor can be used as above with mash_table.

    composite_table <- comp_table(mean = df1, sd = df2)
    composite_table <- comp_table_list(list(mean = df1, sd = df2))  # same as above

    title(composite_table) <- 'A composite table'
    subtitle(composite_table) <-
      'Two or more tables put side by side, with multi-column-headings'

    print(composite_table)

    ## A composite table
    ## Two or more tables put side by side, with multi-column-headings
    ## ..........mean...........  ...........sd............
    ##    Species  length  width     Species  length  width
    ## setosa        5.01   3.43  setosa        0.35   0.38
    ## versicolor    5.94   2.77  versicolor    0.52   0.31
    ## virginica     6.59   2.97  virginica     0.64   0.32

When creating a Composite table, the `id_vars` argument can be used to combine the tables via merge, rather than via cbind.

    comp_table(mean = df1, sd = df2, id_vars = 'Species')

    ## ..........  ....mean.....  .....sd......
    ##    Species  length  width  length  width
    ## setosa        5.01   3.43    0.35   0.38
    ## versicolor    5.94   2.77    0.52   0.31
    ## virginica     6.59   2.97    0.64   0.32

# Stacked tables

several tables on one excel sheet

Stacked tables simply stack two tables above each other. The only meaningful usecase for this at the moment is to put several tables above each other on the same .xlsx sheet. A stack table can be consist of an arbitrary number of data.frames or Tatoo_tables – except other Stacked_tables.

    stacked_table <- stack_table(df1, mashed_table, composite_table)
    stacked_table <- stack_table_list(list(df1, mashed_table, composite_table))  # same as above

    title(stacked_table) <- 'A stacked table'
    subtitle(stacked_table) <-
      'A list of multiple tables, mainly useful for xlsx export'

    print(stacked_table)

    ## A stacked table
    ## A list of multiple tables, mainly useful for xlsx export
    ## ```````````````````````````````````````````````````````````````````````
    ## `  A table with a title
    ## `  Species    length width
    ## `  setosa     5.01   3.43
    ## `  versicolor 5.94   2.77
    ## `  virginica  6.59   2.97
    ## ____________________________________________________________________
    ## `  A mashed table
    ## `  Two or more tables mashed together so that rows or columns alternate
    ## `  ..........  ..length..  ..width...
    ## `     Species  mean    sd  mean    sd
    ## `  setosa      5.01  0.35  3.43  0.38
    ## `  versicolor  5.94  0.52  2.77  0.31
    ## `  virginica   6.59  0.64  2.97  0.32
    ## ____________________________________________________________________
    ## `  A composite table
    ## `  Two or more tables put side by side, with multi-column-headings
    ## `  ..........mean...........  ...........sd............
    ## `     Species  length  width     Species  length  width
    ## `  setosa        5.01   3.43  setosa        0.35   0.38
    ## `  versicolor    5.94   2.77  versicolor    0.52   0.31
    ## `  virginica     6.59   2.97  virginica     0.64   0.32
    ## `
    ## ```````````````````````````````````````````````````````````````````````

# Tatoo Report

one excel sheet per table

A tatoo report is a list of an arbitrary number of Tatoo tables. When exported to xlsx, a separate worksheet will be created for each element table.

    tatoo_report <- compile_report(
      tagged = tagged_table,
      mashed_row = mashed_table_row,
      mashed_col = mashed_table_col,
      composite = composite_table,
      stacked = stacked_table
    )

    print(tatoo_report)

    ## tagged <Tagged_table> <Tatoo_table>
    ## ::   T01: Example Table - This is an example for tables created with the tatool package
    ## ::   It features a lot of titles and very little data
    ## ::   Species    length width
    ## ::   setosa     5.01   3.43
    ## ::   versicolor 5.94   2.77
    ## ::   virginica  6.59   2.97
    ## ::   This table was created from the iris dataset
    ## ::   It consists of 3 different types of irises’
    ## ::   (Setosa, Versicolour, and Virginica)
    ##
    ##
    ## mashed_row <Tagged_table> <Mashed_table>
    ## ::   A row-mashed table
    ## ::   Species    length width
    ## ::   setosa     5.01   3.43
    ## ::   setosa     0.35   0.38
    ## ::   versicolor 5.94   2.77
    ## ::   versicolor 0.52   0.31
    ## ::   virginica  6.59   2.97
    ## ::   virginica  0.64   0.32
    ##
    ##
    ## mashed_col <Tagged_table> <Mashed_table>
    ## ::   A col-mashed table
    ## ::   ..........  ..length..  ..width...
    ## ::      Species  mean    sd  mean    sd
    ## ::   setosa      5.01  0.35  3.43  0.38
    ## ::   versicolor  5.94  0.52  2.77  0.31
    ## ::   virginica   6.59  0.64  2.97  0.32
    ##
    ##
    ## composite <Tagged_table> <Composite_table>
    ## ::   A composite table
    ## ::   Two or more tables put side by side, with multi-column-headings
    ## ::   ..........mean...........  ...........sd............
    ## ::      Species  length  width     Species  length  width
    ## ::   setosa        5.01   3.43  setosa        0.35   0.38
    ## ::   versicolor    5.94   2.77  versicolor    0.52   0.31
    ## ::   virginica     6.59   2.97  virginica     0.64   0.32
    ##
    ##
    ## stacked <Tagged_table> <Stacked_table>
    ## ::   A stacked table
    ## ::   A list of multiple tables, mainly useful for xlsx export
    ## ::   ```````````````````````````````````````````````````````````````````````
    ## ::   `  A table with a title
    ## ::   `  Species    length width
    ## ::   `  setosa     5.01   3.43
    ## ::   `  versicolor 5.94   2.77
    ## ::   `  virginica  6.59   2.97
    ## ::   ____________________________________________________________________
    ## ::   `  A mashed table
    ## ::   `  Two or more tables mashed together so that rows or columns alternate
    ## ::   `  ..........  ..length..  ..width...
    ## ::   `     Species  mean    sd  mean    sd
    ## ::   `  setosa      5.01  0.35  3.43  0.38
    ## ::   `  versicolor  5.94  0.52  2.77  0.31
    ## ::   `  virginica   6.59  0.64  2.97  0.32
    ## ::   ____________________________________________________________________
    ## ::   `  A composite table
    ## ::   `  Two or more tables put side by side, with multi-column-headings
    ## ::   `  ..........mean...........  ...........sd............
    ## ::   `     Species  length  width     Species  length  width
    ## ::   `  setosa        5.01   3.43  setosa        0.35   0.38
    ## ::   `  versicolor    5.94   2.77  versicolor    0.52   0.31
    ## ::   `  virginica     6.59   2.97  virginica     0.64   0.32
    ## ::   `
    ## ::   ```````````````````````````````````````````````````````````````````````

# Excel export

For further processing with openxlsx.

    wb <- as_workbook(tatoo_report)

For direct xlsx export

    # save_xlsx(tatoo_report, paste(tempfile(), ".xlsx"), overwrite = TRUE)