Introduction
tatoo is designed for creating excel reports from lists ofdata.frames with minimal effort, while still providing somebasic formatting capabilities. tatoo functions can combine data.framesin ways that require additional effort in base R, and to add metadata(id, title, …) that can be used for printing and xlsx export. TheTatoo_report class is provided as a convenient helper to write severalsuch tables to a workbook, one table per worksheet.
Tatoo tables and reports can directly be saved to .xlsx files, orconvert toWorkbook objects withas_workbook()so that you can process them further using theopenxlsxpackage. While tatoo implements convenient print methods so that you canpreview the tables you created in the console, most of the functionalityprovided 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 ofcaptioning to a data.frame or Tatoo_table. Those captions are used forprinting and .xlsx export.
# Create metadata objectex_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 objecttagged_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_tabletitle(df1)<-'A table with a title'table_id(df1)<-NULLlongtitle(df1)<-NULLsubtitle(df1)<-NULLfooter(df1)<-NULLprint(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 columnsCombine two data.frames in such a way that you and up withalternating rows or columns. Internally, a Mashed_table is just a listof two or more tables, and metadata on how to combine them.
Mashed_tables can be constructed from individual data.frames or alist of data.frames
mashed_table<-mash_table(df1, df2)mashed_table<-mash_table_list(list(df1, df2))# same as abovetitle(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 mashtable. Those attributes honored by the print and (more significantly)theas_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 bemodified conveniently via set functions. Named mashed tables will havetwo 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 theMashed_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 viaas_workbook(). Examples for finished.xlsx filesare 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() andcmash() are convenient shortcutfunctions if you just need to quickly mash together a data.frame(similar torbind() andcbind()). Note thatthe result is a data.table and not a data.frame, so if you are notfamiliar with the data.table package you might want to manually convertthe result to a data.frame to prevent headaches.
rmash
rmash() can be used on several data.frames or on anexisting Mashed table.
rmash(df1, df2)rmash(mashed_table)
## Species length width## <char> <num> <num>## 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 theinsert_blank_rowargument ofMashed_table() for consistency.
rmash(df1, df2,insert_blank_row =TRUE)
## Species length width## <char> <char> <char>## 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 ofcmash() is very similar tormash()
cmash(df1, df2)cmash(mashed_table)
## Species Species length length width width## <char> <char> <num> <num> <num> <num>## 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 usingtheid_vars argument.
cmash(mean = df1,sd = df2,id_vars ='Species')
## Species length.mean length.sd width.mean width.sd## <char> <num> <num> <num> <num>## 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 likecbind(), butseparate super-headings are preserved for each table. Names for eachtable can be provided directly, or alternatively thecomp_table_list() constructor can be used as above withmash_table.
composite_table<-comp_table(mean = df1,sd = df2)composite_table<-comp_table_list(list(mean = df1,sd = df2))# same as abovetitle(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, theid_vars argumentcan 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 onlymeaningful usecase for this at the moment is to put several tables aboveeach other on the same.xlsx sheet. A stack table can beconsist of an arbitrary number of data.frames or Tatoo_tables – exceptother Stacked_tables.
stacked_table<-stack_table(df1, mashed_table, composite_table)stacked_table<-stack_table_list(list(df1, mashed_table, composite_table))# same as abovetitle(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. Whenexported to xlsx, a separate worksheet will be created for each elementtable.
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## :: ` ## :: ```````````````````````````````````````````````````````````````````````