vignettes/v01-introduction.Rmd
v01-introduction.RmdThe basictabler package enables rich tables to be created and rendered/exported with just a few lines of R.
The basictabler package:
The tables are rendered as htmlwidgets or plain text. The HTML/text can be exported for use outside of R.
The tables can also be exported to Excel, including the styling/formatting. The formatting/styling is specified once and can then be used when rendering to both HTML and Excel - i.e. it is not necessary to specify the formatting/styling separately for each output format.
basictabler is a companion package to the pivottabler package. pivottabler is focussed on generating pivot tables and can aggregate data. basictabler does not aggregate data but offers more control of table structure.
The latest version of the basictabler package can be obtained directly from the package repository. Please log any questions not answered by the vignettes or any bug reports here.
To build some example tables, we will use the bhmsummary data frame. This summarises the 83,710 trains that arrived into and/or departed from Birmingham New Street railway station between 1st December 2016 and 28th February 2017. As an example, the following are the first four rows from this sample data - note the data has been transposed (otherwise the table would be very wide).
# the qhtbl() function is explained later in this vignette
library(basictabler)
qhtbl(t(bhmsummary[1:4,]), rowNamesAsRowHeaders=TRUE)Each row in this sample data summarises different types of trains running through Birmingham.
The first row from the sample data (column 1 above) represents:
To construct basic tables quickly, two functions are provided that can construct tables with one line of R:
qtbl() returns a basic table. Setting a variable equal to the return value, e.g. tbl <- qtbl(...), allows further operations to be carried out on the table. Otherwise, using qtbl(...) alone will simply print the table to the console and then discard it.qhtbl() returns a HTML widget that when used alone will render a HTML representation of the table (e.g. in the R-Studio “Viewer” pane).The arguments to both functions are the same:
dataFrameOrMatrix specifies the data frame or matrix to construct the basic table from.columnNamesAsColumnHeaders specifies whether the names of the columns in the data frame or matrix should be rendered as column headings in the table (TRUE by default).explicitColumnHeaders is a character vector that allows the column headings to be explicitly specified.rowNamesAsRowHeaders specifies whether the names of the rows in the data frame or matrix should be rendered as row headings in the table.firstColumnAsRowHeaders specifies whether the first column of a data frame should be rendered as row headings in the table (is ignored for matrices).explicitRowHeaders is a character vector that allows the row headings to be explicitly specified.numberOfColumnsAsRowHeaders specifies the number of columns to be set as row headers. Only applies when generating a table from a data frame.columnFormats is a list containing format specifiers, each of which is either an sprintf() character value, a list of arguments for the format() function or an R function that provides custom formatting logic.columnCellTypes is a vector that is the same length as the number of columns in the data frame, where each element is one of the following values that specifies the type of cell: root, rowHeader, columnHeader, cell, total. The cellType controls the default styling that is applied to the cell. Typically only rowHeader, cell or total would be used. Only applies when generating a table from a data frame.theme specifies the name of a built in theme or a simple list of colours and fonts.replaceExistingStyles specifies whether the default styles are partially overwritten or wholly replaced by the styles specified in the following arguments.tableStyle, headingStyle, cellStyle and totalStyle are lists of CSS declarations that provide more granular control of styling and formatting settings.A basic example of quickly printing a table to the console using the qtbl() function:
library(basictabler)
qtbl(data.frame(a=1:2, b=3:4))a b
1 3
2 4 The qtbl() function is a concise version of a more verbose syntax, i.e.
library(basictabler)
tbl <- qtbl(data.frame(a=1:2, b=3:4))… is equivalent to …
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(a=1:2, b=3:4))Other operations can be carried out on the table object, e.g. rendering it as a HTML widget:
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(a=1:2, b=3:4))
tbl$renderTable()The qhtbl() function renders the table immediately as html widget:
library(basictabler)
qhtbl(data.frame(a=1:2, b=3:4))When creating tables from data frames or matrices, it is possible to specify how values should be formatted for display in the table. The following example makes use of the sample data and illustrates how to specify formatting:
# aggregate the sample data to make a small data frame
library(basictabler)
library(dplyr)
tocsummary <- bhmsummary %>%
group_by(TOC) %>%
summarise(OnTimeArrivals=sum(OnTimeArrivals),
OnTimeDepartures=sum(OnTimeDepartures),
TotalTrains=sum(TrainCount)) %>%
ungroup() %>%
mutate(OnTimeArrivalPercent=OnTimeArrivals/TotalTrains*100,
OnTimeDeparturePercent=OnTimeDepartures/TotalTrains*100) %>%
arrange(TOC)
# To specify formatting, a list is created which contains one element for each column in
# the data frame, i.e. tocsummary contains six columns so the columnFormats list has six elements.
# The values in the first column in the data frame won't be formatted since NULL has been specified.
# The values in the 2nd, 3rd and 4th columns will be formatted using format(value, big.mark=",")
# The values in the 5th and 6th columns will be formatted using sprintf(value, "%.1f")
columnFormats=list(NULL, list(big.mark=","), list(big.mark=","), list(big.mark=","), "%.1f", "%.1f")
# render the table directly as a html widget
qhtbl(tocsummary, firstColumnAsRowHeaders=TRUE,
explicitColumnHeaders=c("TOC", "On-Time Arrivals", "On-Time Departures",
"Total Trains", "On-Time Arrival %", "On-Time Departure %"),
columnFormats=columnFormats)The examples in this vignette illustrate constructing tables from data frames. This populates a table quickly with just one line of R.
Tables can also be constructed row-by-row, column-by-column and/or cell-by-cell. For more details, please see the Working with Cells vignette.
Further operations on the basic table object tbl can be carried out to modify the table. For example, to add a total row:
# aggregate the sample data to make a small data frame
library(basictabler)
library(dplyr)
tocsummary <- bhmsummary %>%
group_by(TOC) %>%
summarise(OnTimeArrivals=sum(OnTimeArrivals),
OnTimeDepartures=sum(OnTimeDepartures),
TotalTrains=sum(TrainCount)) %>%
ungroup() %>%
mutate(OnTimeArrivalPercent=OnTimeArrivals/TotalTrains*100,
OnTimeDeparturePercent=OnTimeDepartures/TotalTrains*100) %>%
arrange(TOC)
# calculate the data for the total row
totalsummary <- bhmsummary %>%
summarise(OnTimeArrivals=sum(OnTimeArrivals),
OnTimeDepartures=sum(OnTimeDepartures),
TotalTrains=sum(TrainCount)) %>%
mutate(OnTimeArrivalPercent=OnTimeArrivals/TotalTrains*100,
OnTimeDeparturePercent=OnTimeDepartures/TotalTrains*100)
# specify formatting
columnFormats=list(NULL, list(big.mark=","), list(big.mark=","), list(big.mark=","), "%.1f", "%.1f")
# generate the table
tbl <- qtbl(tocsummary, firstColumnAsRowHeaders=TRUE,
explicitColumnHeaders=c("TOC", "On-Time Arrivals", "On-Time Departures",
"Total Trains", "On-Time Arrival %", "On-Time Departure %"),
columnFormats=columnFormats)
# get the values for the totals row
values <- list("All TOC", totalsummary[1, ]$OnTimeArrivals, totalsummary[1, ]$OnTimeDepartures,
totalsummary[1, ]$TotalTrains, totalsummary[1, ]$OnTimeArrivalPercent,
totalsummary[1, ]$OnTimeDeparturePercent)
# add the totals row
tbl$cells$setRow(6, cellTypes=c("rowHeader", "total", "total", "total", "total", "total"),
rawValues=values, formats=columnFormats)
# render the table
tbl$renderTable()For more information and examples regarding manipulating the structure and content of tables see the Working with Cells vignette.
This section shows some examples from the other vignettes as a quick overview of some of the other capabilities of the basictabler package. The R scripts to create each example below can be found in the other vignettes.
See the Styling vignette for more details.
See the Finding and Formatting vignette for more details.