Package features

• A full set of tools is provided to control the appearance of tables, including titles, footnotes and reference marks, horizontal and vertical rules, and spacing of rows and columns. Many properties can be set automatically by specifying styles, such as the default styles used above. The user can also define custom styles.

• There are tools for low-level manipulation of the appearance of individual table elements if desired.

• All sizes and dimensions in displayed tables are specified in physical units (points for font size, millimeters for everything else). Therefore a plotted table has a well-defined physical size, independent of the size of the graphics device on which it is displayed. The user can easily increase or decrease the displayed size by a scale factor, maintaining the relative proportions of table elements.

• Table entries can use markdown/HTML tags to mix different fonts, font faces, colors, and text sizes within a single entry. (Requires the ggtext package [Wilke, 2020].)

• Automatic wrapping of entry text to a user-specified width is available. (Requires the ggtext [Wilke, 2020] and quadprog [Turlach, 2019] packages.)

• Since the plotted tables are ordinary ggplot objects, the facilities of ggplot2 and its various extension packages are available to modify or manipulate the table. For example, the table can be inserted as an image within another plot.

• Any table-like object can be displayed just by writing a textTable method for the object class. See Appendix A.

Some limitations

• Splitting a very long or wide table into multiple, smaller subtables is currently not supported.

• Mathematical symbols and notation in table entries are implemented using R’s plotmath facility. This is more limited than what is available through LaTeX or HTML. A particular limitation is that plotmath ignores line breaks in text strings, so math notation cannot be used in multi-line entries. Also plotmath and markdown/HTML cannot mixed within the same entry.

Logical structure of a data summary table

The conceptual model for tables used by this package is similar to that used in the tables package [Murdoch, 2020]. The table of summary statistics for the iris data, shown above, will be used as an example.

The rows of a table are defined by combinations of one or more discrete variables (here, species and type of summary statistic—mean or standard deviation). The columns are defined by combinations of one or more other discrete variables (here, flower part and measurement direction). The table body contains the values associated with each combination of row and column variables (e.g., each unique combination of species, flower part, direction, and summary statistic), formatted as character strings.

The idea that a table consists of row variables, column variables, and a text string associated with each combination of values of those variables is quite general. For example, consider the first table above, a simple listing of the first few observations in a data frame. The row variable of this table is just the row or observation number. The column variable is more subtle: it is a categorical variable that takes values in the set c("plant", "Species", "flower_part", "direction", "value"), corresponding to the column names of the data frame. And the table body entries are the formatted values associated with each combination of row number and column name. Note that table entries are always treated as character strings, so the fact that the original values in the data frame had different types (numeric or factor) does not matter.

When there is more than one row variable, or more than one column variable, they are treated as nested from outermost to innermost. So in the second table above, summary statistic types are nested within species, and measurement directions are nested within flower part. Nesting implies a hierarchical or tree structure for the table rows and columns, and this structure is used in styling the table. Note for example the extra space inserted between levels of the outermost row and column variables (between the different species and between the two flower parts), and how horizontal rules (lines) are used to group the columns associated with each flower part. This can be done automatically by the tablesgg package because it is aware of this hierarchical structure.

Remainder of this vignette

Section 2 describes how to get started with tablesgg and illustrates some of the main features. Section 3 discusses the model and terminology for tables used by tablesgg in more detail. This material is important for users who wish to customize the appearance of their tables. Customization of table display for individual tables is discussed in section 4, and section 5 describes how to define custom styles that can be applied to any table.

textTables and pltdTables

The starting point for all displays generated by this package is a textTable object. These objects are created by the generic function of the same name. The package includes methods to create textTables from a variety of table-like objects. For example the data.frame method creates a textTable that represents a simple listing of a data frame. The tabular method creates a textTable from the data summary tables produced by the tables package. To see all the methods currently available, enter

methods(textTable)

## [1] textTable.data.frame textTable.default*   textTable.ftable    
## [4] textTable.matrix     textTable.table      textTable.tabular   
## [7] textTable.xtable     textTable.xtableList
## see '?methods' for accessing help and source code

Appendix A describes how to write methods for other types of objects.

As the name suggests, all parts of a table in a textTable object—the table body, row and column headers, and any annotation such as titles or footnotes—are text strings. That is, the process of converting any object to a textTable includes formatting numbers or other non-text into the character strings that are to be displayed in the final table.

The package defines a plot method for textTables. Plotting a textTable creates a pltdTable object, which is also a ggplot. As with any other graph created by ggplot2, printing the object causes it to be displayed on the currently active graphics device.

To illustrate, let’s return to the tables shown in the Introduction. The listing of the first few rows of the iris2 data frame was produced by

plot(textTable(head(iris2)))

The row.names argument to the data.frame method of textTable controls whether row names are displayed (FALSE suppresses them), and if so, what label is used for the column containing them:

plot(textTable(head(iris2), row.names="Obs. #"))

The second table in the Introduction was created using the tables package:

iris2_tab <- tabular(Species*Heading()*value*Format(digits=2)*(mean + sd) ~ 
                     Heading("Flower part")*flower_part*Heading()*direction, 
                     data=iris2)

iris2_tab is an object of class tabular, which is converted to a textTable and displayed as follows.

plot(textTable(iris2_tab))

(In fact, tablesgg includes a plot method for tabular objects, which does the conversion to textTable automatically. So just plot(iris2_tab) would also work.)

We now consider some options and enhancements to these basic tables. See the help pages for the functions mentioned for more details and additional capabilities.

Table annotation

Annotation can be added to a table in the form of title, subtitle, and foot lines, via the title, subtitle, and foot arguments to textTable. Each of these is a character vector, with each element in a vector generating a new entry that spans the full width of the table. Title lines appear at the top, followed by subtitle lines. Footlines appear at the bottom of the table. For example,

ttbl <- textTable(iris2_tab, title="The iris data", 
                  subtitle=c("Summary statistics by species", 
                             "A second subtitle line"), 
                  foot="sd = standard deviation")

plot(ttbl)

The same arguments can be used in the call to plot to add or replace existing annotation in a textTable.

# Change the main title, remove the subtitles.
plot(ttbl, title="A new title", subtitle=character(0))

Table size and scaling

Plotted tables (pltdTable objects) have a well-defined physical size, which can be extracted using the pltdSize function. By default the size is reported in millimeters, but inches or centimeters can be requested using the units argument. The first value is the width and the second is the height.

plt <- plot(iris2_tab, title="The iris data")
pltdSize(plt)

## [1] 77.04089 52.58743
## attr(,"device")
## [1] "pdf"
## attr(,"units")
## [1] "mm"

If desired, this can be used to open a graphics device or grid viewport of exactly the right size to hold the table. For example

sz <- pltdSize(plt, units="in")   # R expects device dimensions in inches
dev.new(width=sz[1], height=sz[2])
plt

The size is determined by the fonts used for table entries, the amount of space allocated for horizontal and vertical rules, and other graphical parameters. These are set by styles, which are discussed in sections 3 and 5 below. The result is called the natural size of the table. However the physical size can be modified by two arguments to plot. scale is a multiplier that increases or decreases the size of all table elements proportionally.

plt2 <- plot(iris2_tab, scale=0.8, title="The iris data (scale=0.8)")
plt2

Argument plot.margin is a numeric vector of length 4 that specifies how much extra empty space should be added around the sides of the table, in millimeters (as always). This is equivalent to the theme element of the same name in ggplot2, and sides follow same order: top, right, bottom, left. plot.margin is added after any scaling by scale, and is included in the table size reported by pltdSize.

Note that if the active graphics device or viewport is smaller than the physical size of the plotted table, then parts of the table will be clipped off and not visible.

Positioning the table on the graphics device

As mentioned previously, a pltdTable object must be “printed” in order for it to be displayed on the currently active graphics device. There is a special print method for these objects which ensures that the table is displayed at the correct size. In addition, it allows specifying where on the device surface the table should appear.

The default is that the table is drawn centered in the current graphics viewport (usually the whole graphics device surface). This can be changed using either the position or the just, vpx and vpy arguments to print. See the documentation for print.pltdTable for details.

Grouping rows: rowheadInside and rowgroupSize

Two arguments to the plot method for textTables allow visual grouping of table rows. Setting rowheadInside to TRUE moves the outermost row header column inside the table, making the table narrower and longer. Setting rowgroupSize to a positive integer causes extra space to be inserted after every rowgroupSize rows.

plt1 <- plot(iris2_tab, title="The iris data", subtitle="With rowheadInside = TRUE", 
             rowheadInside=TRUE)
plt2 <- plot(textTable(iris2[1:9, ]), title="The first 9 rows of 'iris2'", 
             subtitle="In groups of 4 (rowgroupSize=4)", rowgroupSize=4)

print(plt1, position=c("left", "center"))
print(plt2, position=c("right", "center"), newpage=FALSE)

Mathematical notation in table entries

Mathematical notation can be included in table entries, including annotation. This is done by setting the entry text in a textTable to a string representing a plotmath expression (see ?plotmath), and prefixing it with the characters ‘MATH_’. For example, to include math in the title,

ttbl <- textTable(iris2_tab, title=paste0("MATH_plain('The length of vector')~", 
                                    "group('(', list(a, b), ')')~plain('is ')~", 
                                    "sqrt(a^2 + b^2)"))

plot(ttbl)

See ?plotmath for a full description of the available symbols and notation. plotmath expressions can be included in a textTable when it is created, as above, or can be added or edited afterward using the props functions discussed in section 4.2.3. Note that plotmath ignores control characters such as newline (\n) in expressions.

Markdown/HTML in table entries

If the ggtext package [Wilke, 2020] has been installed, entry text can include markdown/HTML tags. These allow one to mix different fonts, font faces and sizes, and colors within a single entry. To indicate that entry text is to be interpreted as markdown/HTML, prefix it with MKDN_. For example,

txt1 <- paste0(
          "MKDN_Some <span style='color:blue'>blue text **in bold.**</span><br>", 
          "And *italic text.*<br>", 
          "And some <span style='font-size:18pt; color:black'>large</span> text.")
txt2 <- "MKDN_Super- and subscripts: *x*<sup>2</sup> + 5*x* + *C*<sub>*i*</sub>"
plt <- plot(textTable(matrix(c(txt1, txt2), ncol=1)), 
            title="Illustrate markdown", scale=1.2)

print(plt)

• This feature can be turned on and off using the package option allowMarkdown (see ?tablesggSetOpt). By default the option is set to TRUE if ggtext is installed and FALSE if not.

• Not all HTML tags are supported. See ?ggtext::geom_richtext for examples of what is available. Note that line breaks are indicated by \n in plain text, but by the <br> tag in HTML.

• Markdown/HTML and plotmath cannot be mixed in the same entry.

Reference marks

A reference mark is a symbol placed before or after entry text to indicate a cross-reference; e.g. for footnotes. Reference marks can be added to either a textTable or pltdTable using the addRefmark function. The following adds a footnote to explain the abbreviation “sd”, and cross-references entries containing the abbreviation to the footnote:

ttbl <- textTable(iris2_tab, foot="sd = standard deviation")
ttbl <- addRefmark(ttbl, mark="a", before="sd =", after="sd$", raise=TRUE)

plot(ttbl)

Argument mark is the character or symbol to be used as the reference mark. before and after are regular expressions (see ?regex) that identify which table entries are to have the mark placed at their beginning or end, respectively. raise indicates whether the reference mark is to be displayed as a superscript (using plotmath or markdown).

In the example the after regular expression matches all three row headers corresponding to standard deviations, since they all have the same entry text. For finer control, such as to mark only the first appearance, the props functions can be used with a pltdTable object, as described in section 4.2.3.

Setting minimum and maximum widths for table entries

The graphical properties minwidth and maxwidth, set either by a style or with one of the props functions, can be used to control the width of individual table entries (and thereby the widths of the columns they span). For example, setting the minimum or maximum width of a table’s title will control the width of the whole table, since the title spans all columns. See Appendix C for details.

Use with table objects from other packages

Packages like tables and xtable do two things: they create table-like objects (with classes tabular and xtable, respectively), and they generate LaTeX or HTML code to style those objects for rendering to a PDF viewer or browser. This package provides methods to convert the table-like objects from the first step into textTables. Then the styling and rendering (to a graphics device) are done using the facilities of this package, not those of the original package.

Next steps

The next section describes the model and terminology that the tablesgg package uses for tables. It is important to understand these concepts in order to fine-tune or customize the appearance of your tables.

Table parts

A table has seven parts, illustrated by the shaded regions here.

• Parts title, subtitle, and foot are collectively referred to as the table annotation. Each is optional. They can each contain multiple entries, which will be displayed on separate lines. They span the full width of the table.

• Parts rowhead and colhead contain the row headers and column headers of the table, respectively. Visually they simply provide labels for rows and columns of the table body. Conceptually they represent combinations of values of row and column variables, which are discussed further below.

• Part body contains the body of the table: the values associated with each combination of row and column variables, formatted as text strings.

• Part rowheadLabels is optional and contains labels for the row header variables; that is, labels for each column of rowhead.

body, rowhead, and colhead can be thought of as matrices that fit together into a larger matrix, with body in the lower right quadrant, rowhead in the lower left quadrant, and colhead in the upper right quadrant. The upper left quadrant is called the stub of the table; part rowheadLabels occupies the bottom row of the stub.

The number of rows and columns in each table part can be obtained with the summary function, applied to either a textTable or pltdTable:

summary(ttbl)

## 'textTable' with augmented row-column grid dimensions: (13, 6)
## Table parts:
##               nr nc
## title          1 NA
## subtitle       2 NA
## rowhead        6  2
## rowheadLabels  1  2
## colhead        3  4
## body           6  4
## foot           1 NA

The number of columns for annotation parts is reported as NA because they don’t have a fixed number of columns; they span however many columns are required by the other parts. Not every part needs to be present in a given table, and nr and/or nc will be 0 for empty parts.

The augmented row-column grid; table cells

When we speak of the rows and columns of a table, we are typically referring to the rows and columns of the table body. However it is clear from the figure in section 3.1 that the arrangement of the other table parts can be thought of as adding additional rows and columns, creating an augmented row-column grid for the table:

• Each row header variable (column of rowhead) adds a column.

• Each column header variable (row of colhead) adds a row.

• Each line of annotation (in title, subtitle, or foot) adds a row.

The adim function reports the number of rows and columns in this augmented grid:

adim(ttbl)

## [1] 13  6

In the tablesgg package all references to positions within a plotted table are with respect to the augmented row-column grid. Each location in the grid is called a cell of the table.

The hierarchical structure of headers

As mentioned in the introduction, the model for a data summary table used by this package is one in which:

• There are one or more discrete variables in a data set. These are arbitrarily partitioned into row variables and column variables. (In the iris data table above, the column variables are flower part (Sepal or Petal) and measurment type (Length or Width). The row variables are Species and summary statistic type (mean or sd).)

• Each combination of values of row variables corresponds to one row of the table body, and each combination of values of column variables corresponds to one column of the body.

• For each combination of values of the row and column variables, a single text string is generated, representing the value associated with that combination. These text strings form the entries in the body of the table.

The combinations of values of the row variables are displayed in the table as the row header, and the combinations of values of the column variables as the column header. Each column of rowhead corresponds to one row variable and is called a layer of the header. Layers are numbered from innermost (closest to the table body) to outermost. Thus in the iris table, statistic type is layer 1 of the row header and species is layer 2. Similarly each row of colhead corresponds to one column variable, with a layer number that increases from innermost (measurement type) to outermost (flower part).

Within a header, the variables are treated as nested, inner (lower numbered) layers within outer layers. (This is independent of whether the variables would be considered nested or crossed for statistical modeling purposes.) Thus in the iris data table, measurement type is considered nested within flower part, and statistic type is considered nested within species.

Nesting implies a hierarchical or tree structure for the rows of rowhead and the columns of colhead. Layer number indicates how close to the bottom of the hierarchy a row or column variable is. The level then numbers the nodes within a layer. In the example, species, at layer 2, has three nodes or levels: 1 (setosa), 2 (versicolor), and 3 (virginica). Statistic type, at layer 1, has six nodes or levels: 1 (mean), 2 (sd), 3 (mean), 4 (sd), etc. Note that because of the nesting structure, “mean” for species versicolor is not assumed to have any relation to “mean” for setosa; for the purposes of displaying the table, they are entirely different levels of statistic type and have different node/level numbers.

This structure can be used to help style the appearance of the table. For example, by default additional space is inserted between different levels of the row or column header hierarchy at layers 2 or higher (e.g. between different species in the example). Similarly, horizontal rules are used to group columns at different levels of the column header hierarchy in layers 2 or higher (e.g., spanning the two measurement types for each flower part). The way this styling is specified is discussed in section 5.

Table elements: entries, blocks, hvrules

As implemented in this package, plotted tables have three types of elements, namely entries, blocks, and hvrules. Elements are the smallest pieces of a table whose display can be individually controlled. In a sense they are the “atoms” of the table display. Each type of element is described in more detail below, but elements of all types share the following characteristics:

• Each element has an ID, a character string that is unique within the element type. To see the ID’s of all the elements of a given type in a table, use the ids function.

• Each element has a set of graphical properties that specify how it is to be displayed. For example, the font, color, and border for a table entry; or the line type and thickness for an hvrule. ?elements documents the available graphical properties for each element type.

• Each element has a special property called enabled. This is either TRUE or FALSE, and controls whether the element is displayed at all.

• Elements have additional descriptors related to their role in the logical structure of the table, such as the table part they are associated with, and their position within that part. These additional descriptors vary depending on the element type, and are described in ?elements.

Styles

In processing a textTable into a pltdTable that is ready for display, graphical properties like font, text justification, color, etc., have to be assigned to each table element. The initial assignment of graphical properties is specified by a set of styles, one each for entries, blocks, and hvrules. Thus, as the name suggests, styles control the visual appearance of elements in the plotted table. Styles are specified via the entryStyle, blockStyle, and hvruleStyle arguments to plot.

Styles are implemented as styleObj objects. The package includes a few built-in styles that serve as defaults. Users can edit these or add additional styles as they choose. The way styles are defined and applied is described in section 5. As an illustration, the following shows the same table plotted twice. On the left the default entry style is used. Among other things it uses a serif font, a larger font size for the title, and sets horizontal and vertical justification of text according to each entry’s structural role in the table. On the right a “base” style is used, which just assigns the same generic graphical parameters to all entries.

plt1 <- plot(ttbl, title="Default style for entries")
plt2 <- plot(ttbl, entryStyle=styles_pkg$entryStyle_pkg_base, 
             title="The 'base' style for entries")

print(plt1, position=c("left", "center"))
print(plt2, position=c("right", "center"), newpage=FALSE)

Confusing conventions

A potential source of confusion in displaying tables as plots is the differing conventions about coordinate systems: origin, axis directions, and axis order.

• Tables follow the matrix convention in which the origin is at the upper left, with row numbers increasing from top to bottom and column numbers increasing from left to right. Dimensions and coordinates are in (row, column) order, that is, vertical coordinate first, then horizontal.

• The plot convention is to have the origin at the lower left, with the vertical coordinate increasing from bottom to top, and the horizontal from left to right. Dimensions and coordinates are in (horizontal, vertical) order.

In this package the matrix convention is followed in almost all cases: for the augmented row-column grid, the dimensions of tables and their parts, horizontal and vertical justification of entry text within cells, and descriptors for table elements. The plot convention is used only for the following two aspects of pltdTable objects:

• The pltdSize function returns physical dimensions in (horizontal, vertical) order.

• The position, just, vpx, and vpy arguments of the print method also expect values in (horizontal, vertical) order, with 0 meaning left/bottom and 1 meaning right/top.

The other difference in conventions to be aware of is that tablesgg uses millimeters for dimensions, whereas R graphics functions use inches. This should only matter to the user when opening a graphics device based on pltdSize; specify units="in" to get table size in inches.

Modifying a textTable

There is an update method for textTable objects. It allows one to change or remove the table’s annotation (titles, subtitles, foot lines) and labels for the row header columns (rowheadLabels).

A textTable can also be subscripted in the usual matrix way, to create a new textTable with fewer (or rearranged) rows or columns. The subscripts are applied to the augmented row-column grid. For example, the following will remove the first column header row (“Flower part”) from the example table, and reverse the order of the “Sepal” and “Petal” sets of columns:

subttbl <- ttbl[-4, c(1,2,5,6,3,4)]
# Also change annotation:
subttbl <- update(subttbl, title="Example of subscripting a 'textTable'")

plot(subttbl)

The above subscripting required us to count rows and columns of the augmented grid, and would have to be modified if, for example, we changed the number of title or subtitle lines in the table. The helper functions arow and acol allow the subscripts to be specified in a less fragile way:

i <- arow(ttbl, "colhead")[1]  # row number of first column header row
j1 <- acol(ttbl, "rowhead")  # column numbers for row header
j2 <- acol(ttbl, "colhead")  # column numbers for column header
subttbl2 <- ttbl[-i, c(j1, j2[c(3,4,1,2)])]
subttbl2 <- update(subttbl2, title="Example of subscripting a 'textTable'")
identical(subttbl, subttbl2)

## [1] TRUE

Subscripting cannot be used to move rows or columns between different table parts (e.g., between headers and the table body).

Modifying a pltdTable

It is possible to change the graphical properties of table elements in an existing plotted table, as well as shrink or expand its overall displayed size. One can also add additional blocks or hvrules to the table. However it is not possible to make changes that alter the table’s augmented row-column grid, such as adding new entries or annotation. For that one must go back to the starting textTable, or to the object from which the textTable was generated.

plt1 <- plot(ttbl)
plt2 <- update(plt1, scale=0.8)
plt3 <- update(plt2, scale=1.0)
rbind(pltdSize(plt1), pltdSize(plt2), pltdSize(plt3))

##          [,1]     [,2]
## [1,] 77.04089 62.69298
## [2,] 61.83271 50.26097
## [3,] 77.04089 62.69298

head(elements(plt1, type="entry"))

##                    id     part subpart partrow partcol headlayer level_in_layer
## title,1       title,1    title    <NA>       1      NA         6              1
## subtitle,1 subtitle,1 subtitle    <NA>       1      NA         4              1
## subtitle,2 subtitle,2 subtitle    <NA>       2      NA         5              1
## foot,1         foot,1     foot    <NA>       1      NA         1              1
## body,1,1     body,1,1     body    <NA>       1       1         0              1
## body,2,1     body,2,1     body    <NA>       2       1         0              2
##                                     text      type arow1 arow2 acol1 acol2
## title,1                    The iris data character     1     1     1     6
## subtitle,1 Summary statistics by species character     2     2     1     6
## subtitle,2        A second subtitle line character     3     3     1     6
## foot,1           sd = standard deviation character    13    13     1     6
## body,1,1                            5.01   numeric     7     7     3     3
## body,2,1                            0.35   numeric     8     8     3     3
##            enabled textspec multicolumn multirow hjust vjust color alpha size
## title,1       TRUE    plain        TRUE    FALSE     0     0 black     1   11
## subtitle,1    TRUE    plain        TRUE    FALSE     0     0 black     1    9
## subtitle,2    TRUE    plain        TRUE    FALSE     0     0 black     1    9
## foot,1        TRUE    plain        TRUE    FALSE     0     0 black     1    9
## body,1,1      TRUE    plain       FALSE    FALSE     1     1 black     1   10
## body,2,1      TRUE    plain       FALSE    FALSE     1     1 black     1   10
##            family fontface lineheight angle hpad vpad fill fill_alpha
## title,1     serif        1        0.9     0    1  0.7 <NA>          1
## subtitle,1  serif        1        0.9     0    1  0.7 <NA>          1
## subtitle,2  serif        1        0.9     0    1  0.7 <NA>          1
## foot,1      serif        1        0.9     0    1  0.5 <NA>          1
## body,1,1    serif        1        0.9     0    1  0.7 <NA>          1
## body,2,1    serif        1        0.9     0    1  0.7 <NA>          1
##            border_size border_color minwidth maxwidth
## title,1            0.5         <NA>     -0.4       NA
## subtitle,1         0.5         <NA>     -0.4       NA
## subtitle,2         0.5         <NA>     -0.4       NA
## foot,1             0.5         <NA>     -0.4       NA
## body,1,1           0.5         <NA>     -1.0      Inf
## body,2,1           0.5         <NA>     -1.0      Inf

plt <- plot(ttbl)
props(plt, id="body") <- element_entry(fontface=3, fill="gray85")
props(plt, id="subtitle,2") <- element_entry(text="Properties changed", 
                                            fill="gray85")
props(plt, id="rowhead_right") <- element_hvrule(linetype=1, color="black")

plt

plt <- plot(textTable(iris2_tab, foot="sd = standard deviation"))
props(plt, regex="^sd$") <- element_refmark(mark="*", side="after")
props(plt, regex="^sd =") <- element_refmark(mark="*", side="before")

plt

propsa(plt, arows=c(5, 7, 9), acols=5) <- element_entry(color="red")

plt

propsa(plt, arows=arow(plt, hpath=c(NA, "mean")), 
       acols=acol(plt, id="body")) <- element_entry(fontface=2)

plt

plt <- plot(textTable(iris2_tab))
propsd(plt, subset=(enabled)) <- element_hvrule(color="red")
propsd(plt, subset=(part == "colhead" & headlayer == 1)) <- 
       element_entry(angle=90, hjust=0.5, vjust=1.0)

plt

plt <- addBlock(plt, arows=c(6, 7), acols=c(3, 4), 
                props=element_block(border_color="red", border_size=1.0), 
                enabled=TRUE)

plt

plt <- addHvrule(plt, direction="vrule", acols=4.5, arows=arow(plt, "body"), 
                 props=element_hvrule(linetype=2, color="blue"), enabled=TRUE)

plt

plt + theme(plot.background=element_rect(fill=NA, color="black", size=1))

Setting default styles: tablesggSetOpt

The default element styles (and default plot.margin) can be accessed and changed using functions tablesggOpt and tablesggSetOpt. See their documentation for the details.

Style specification and matching: Entry and block styles

First note that table entries and blocks internally are stored in objects that are themselves data frames, with one row per element. (These data frames can be accessed using the elements function.) Columns include element descriptors such as the table part associated with the element, its position in the table, whether the element spans multiple rows or columns, and other information. See ?elements for lists of the standard descriptors.

In styles for table entries and blocks, the pattern part of the styleObj object consists of a single column named condition. condition should contain character strings that can be interpreted as expressions involving element descriptors. Each condition expression, when evaluated within an entries or blocks data frame, should produce a logical vector with one value per element. (Vectors of length 1 are recycled to the necessary length.) Elements for which the condition expression in a style row evaluates to TRUE are considered to match that row of the style, and are assigned the graphical properties in that row.

As an illustration, the following shows the package’s default style for table entries:

styles_pkg$entryStyle_pkg_1

##                             condition hjust vjust color alpha size family
## 1                      part == "body"   1.0   1.0 black     1   10  serif
## 2       part == "rowhead" & !multirow   0.0   1.0 black     1   10  serif
## 3        part == "rowhead" & multirow   0.0   0.0 black     1   10  serif
## 4  part == "rowhead" & headlayer == 0   0.5   0.5 black     1   10  serif
## 5    part == "colhead" & !multicolumn   1.0   1.0 black     1   10  serif
## 6     part == "colhead" & multicolumn   0.5   1.0 black     1   10  serif
## 7             part == "rowheadLabels"   0.0   1.0 black     1   10  serif
## 8                     part == "title"   0.0   0.0 black     1   11  serif
## 9                  part == "subtitle"   0.0   0.0 black     1    9  serif
## 10                     part == "foot"   0.0   0.0 black     1    9  serif
##    fontface lineheight angle hpad vpad fill fill_alpha border_size border_color
## 1         1        0.9     0    1  0.7   NA          1         0.5           NA
## 2         1        0.9     0    1  0.7   NA          1         0.5           NA
## 3         1        0.9     0    1  0.7   NA          1         0.5           NA
## 4         3        0.9     0    1  0.7   NA          1         0.5           NA
## 5         1        0.9     0    1  0.7   NA          1         0.5           NA
## 6         1        0.9     0    1  0.7   NA          1         0.5           NA
## 7         1        0.9     0    1  0.7   NA          1         0.5           NA
## 8         1        0.9     0    1  0.7   NA          1         0.5           NA
## 9         1        0.9     0    1  0.7   NA          1         0.5           NA
## 10        1        0.9     0    1  0.5   NA          1         0.5           NA
##    minwidth maxwidth
## 1      -1.0      Inf
## 2      -1.0      Inf
## 3      -1.0      Inf
## 4      -1.0      Inf
## 5      -1.0      Inf
## 6      -1.0      Inf
## 7      -1.0      Inf
## 8      -0.4       NA
## 9      -0.4       NA
## 10     -0.4       NA

The first style row has pattern part == "body", and so the graphical properties in that row will be assigned to every entry in the table body. The second and third rows assign graphical properties to row header entries, with a different vertical justification of text (vjust) depending on whether the entry spans more than one row. The fourth row applies when the table is plotted with rowheadInside=TRUE: the outermost row header entries are moved inside the table and assigned a header layer number of 0. These entries will be in italics (fontface equal to 3). part, multirow, headlayer, and so on are all standard entry descriptors.

The default style for blocks has a single row:

styles_pkg$blockStyle_pkg_1[, 1:5]

##   condition   fill fill_alpha border_size border_color
## 1        NA gray85          1         0.5           NA

An NA value (or equivalently an empty string) as a style row’s condition is treated specially: it matches any element. The row’s graphical properties will be applied to all elements, unless overridden by a later style row. So by default all blocks are assigned a light gray background (fill=gray85) and no border (border_color=NA). (However by default all standard blocks also have enabled=FALSE, and so this background will not be displayed.)

Style specification and matching: hvrule styles

The creation and styling of hvrules is closely tied to table blocks: by default, four hvrules are created for each block, one running along each side. (They are initially disabled.) Style specification for hvrules is more complicated than for table blocks because hvrules effectively separate blocks. Therefore one may want their appearance to depend on characteristics of the blocks on both sides of the hvrule. For example, one might want to insert extra space after a block of columns, but only if it is followed by another block of columns, not if it is the rightmost block in the table.

Similar to entries and blocks, hvrules are represented internally as a data frame with one row per hvrule. Columns include: block, the ID of the block that generated the hvrule; side, the side of block along which the hvrule runs (“top”, “right”, “bottom”, or “left”); and adjacent_blocks, a string listing the ID’s of all the blocks adjacent to block on the same side as the hvrule. That is, the hvrule separates block from the blocks in adjacent_blocks. Note that adjacent_blocks may be empty.

In styles for hvrules, the pattern part of the styleObj object consists of three columns: block_condition, side, and adjacent_condition. side is one of “top”, “bottom”, “left” or “right”. block_condition and adjacent_condition are like the condition column for block styles: they should contain character strings that can be interpreted as expressions involving block descriptors. Each expression will be evaluated within the data frame of blocks that generated the hvrules (not the data frame containing the hvrules themselves). It should produce a logical vector with one element per block; if the value is TRUE for a block, the block satisfies that expression. See styles_pkg$hvruleStyle_pkg_1 for examples of such expressions.

An hvrule matches a given style row if (a) its generating block satisfies the style row’s block_condition; (b) they have the same value of side; and (c) one or more of the hvrule’s adjacent_blocks satisfies the style row’s adjacent_condition.

Any of block_condition, side, and adjacent_condition in a style row may also be set to NA (or equivalently, to an empty string). In that case the corresponding criterion (a), (b), or (c) is considered to be satisfied for all hvrules, and so does not limit matches. Note that setting adjacent_condition to NA is the only way to satisfy criterion (c) if an hvrule’s adjacent_blocks is empty. In all other cases, an empty adjacent_blocks will never satisfy criterion (c).

Editing or creating styles

Package users can create new styles by editing an existing one, or creating one from scratch. For the former, see ?styles_pkg for a list of styles provided by the package. For the latter, prepare a data frame or .csv file with the appropriate columns for pattern and for graphical properties, and pass it as the first argument to function styleObj. The graphical property columns that must be present in the data frame are described in ?elements.