elements {tablesgg}

Extract Table Elements from a Plotted Table

Description

Extract table elements (entries, blocks, or hvrules) from a plotted table, as a simple data frame with one row per element.

Usage

elements(x, type=c("entry", "block", "hvrule"), enabledOnly=TRUE)

Arguments

x

A pltdTable object, containing a plotted table.

type

Character scalar indicating the type of elements to extract: one of "entry", "block", or "hvrule".

enabledOnly

Logical scalar. If TRUE, only elements that are currently enabled in x are returned.

Details

A plotted table (pltdTable object) has three types of elements: entries, blocks, and hvrules. Entries are the text strings (and associated properties) displayed in table cells. Blocks are rectangular sets of contiguous table cells. And hvrules are spacers, with or without a visible line (or "rule"), used to separate or group table rows and columns. See the package vignette for more information.

This function allows one to inspect these elements. The purpose is primarily informational: an easy way to view all the elements of a table, their descriptors (e.g., as used by styles and the propsd<- function), and the graphical properties they have been assigned. It is not intended as a way to edit or modify elements. For that, see update methods for textTable and pltdTable objects, the props<- set of functions, and section 4 of the package vignette.

The remainder of this section describes the columns in the returned data frame, for each element type.

Columns in elements(x, type="entry")

Entry descriptors:

id

Character string that uniquely identifies the entry. The format is <part>,<partrow>,<partcol> for table parts that are matrices (rowhead, rowheadLabels, colhead, and body), and <part>,<partrow> for table parts that are vectors (annotation parts title, subtitle, and foot).

part

Character string identifying the part of the table to which the entry belongs: one of "body", "rowhead", "colhead", "rowheadLabels", "title", "subtitle", or "foot".

subpart

Character string with further information about the nature of of the entry within its part of the table. May be NA.

partrow, partcol

Row number, column number of the entry within its table part. For parts that are vectors rather than matrices, partrow will be the element number within the vector, and partcol will be NA. If an entry spans more than one row or column, the minimum row/column number of the spanned cells is used.

headlayer

How far (in number of rows or columns) from the body of the table the entry is. By definition this is 0 for entries in the body of the table. It is 1 for row/column headers immediately adjacent to the body, 2 for headers one row/column further out, and so on. The layer numbers for row header labels match those for the corresponding columns of row headers. The layers for titles, subtitles, and foot lines are the number of _rows_ from the body of the table. When a table is created with rowheadInside set to TRUE, the headlayer value for the outermost layer of row headers (and for its label, if any) is changed to 0, since the headers become interleaved with the table body.

level_in_layer

Numbering of entries within a given part and headlayer. For row and column headers this is based their hierarchical structure (see the descriptors for blocks, below). For other table parts it is just an integer from 1 to the number of entries in that layer of that part.

multirow, multicolumn

Logicals indicating whether the entry spans multiple rows or columns of the table.

text

Character string containing the formatted content of the entry, for display. It may use plotmath notation for mathematical notation, or markdown/HTML tags; see textspec below.

type

Character string identifying the type of value the entry represents (e.g., "numeric"). May be NA. The default for table annotation (title, subtitle, foot) and rowheadLabels is "character".

textspec

Character string indicating any special features of the text in text. Currently supported values are "plain", "plotmath", and "markdown". "plotmath" indicates that the entry text contains mathematical notation as described in ?plotmath. "markdown" means the text may contain markdown or HTML tags to control its appearance; this requires the ggtext package.

enabled

Logical indicating whether the entry is to be displayed when the table is plotted. If FALSE the entry is ignored when laying out the table or determining its size.

arow1, arow2, acol1, acol2

Range of row and column numbers occupied by an entry, with respect to the augmented row-column grid for the table. arow1 < arow2 and/or acol1 < acol2 means the entry spans multiple rows and/or columns.

Graphical properties for entries. Values for these are assigned by a style, either a default style (see ?tablesggOpt) or user-specified.

hjust

Numeric horizontal justification for entry text (0=left, 0.5=center, 1=right).

vjust

Numeric vertical justification for entry text (0=top, 0.5=center, 1=bottom).

color

Character string; color for entry text.

alpha

Numeric value in [0, 1] specifying transparency of entry text (0=transparent, 1=opaque).

size

Font size for entry text, in points (72.27 points = 1 inch, 2.845 points = 1 mm).

family

Character string, the font to use for entry text. "serif", "sans", and "mono" will work for all graphics devices. Other fonts may or may not be available on a particular device.

fontface

Numeric indicating 1=plain, 2=bold, 3=italic, 4=bold and italic.

lineheight

Numeric multiplier that adjusts interline spacing for multi-line entry text. 1.0 gives the default spacing.

angle

Rotation angle for entry text, in degrees counter-clockwise from horizontal.

hpad, vpad

Padding added around the sides of entry text to keep it from touching cell borders, in millimeters. hpad is added on both the left and right sides of the text, and vpad is added on both the top and bottom.

fill

Character string; background color for the cell(s) containing the entry. NA means no background color.

fill_alpha

Numeric value in [0, 1] specifying transparency of the cell background color (0=transparent, 1=opaque).

border_size

Thickness of the border to draw around the cell(s) containing the entry text, in millimeters.

border_color

Character string; color for the border around entry text. NA means no border.

minwidth, maxwidth

Minimum and maximum width for the cell(s) spanned by the entry. (Here width is with respect to the text itself; i.e., the direction of reading for English text, and therefore measured vertically if the text is rotated by 90 or 270 degrees.) They may be expressed in two forms. Positive values are interpreted as absolute widths in millimeters, and should include the amount of padding specified by hpad (when angle is 0 or 180 degrees) or vpad (when angle is 90 or 270 degrees). Negative values are interpreted as multiples of the natural width of the text itself, without including padding. Thus setting minwidth for an entry to -1 will guarantee that the width of the spanned cell(s) will be at least enough to contain the text without wrapping.

• An NA value for minwidth means there is no constraint on minimum width, and is equivalent to 0. An Inf value for maxwidth means there is no constraint on maximum width. (However in the absence of constraints, the internal algorithm favors widths as close as possible to the natural width of the entry text, without wrapping.)

• An NA value for maxwidth means the maximum width will be determined passively from the maxwidth values of other entries in the same table column(s) (if angle is 0 or 180) or row(s) (if angle is 90 or 270). (It will never be less than minwidth.) This may be useful for table titles and footnotes, where long text should be wrapped to fit widths implied by the other table entries.

• Setting maxwidth to NA or to a finite value > -1 and < Inf means the spanned cell(s) may not be wide enough to hold the text without wrapping it into multiple lines. Therefore option tablesggOpt("allowWrap") must be TRUE, and a warning will be raised and maxwidth will be ignored if not.

• The general effect of setting minwidth to a non-zero value is to reduce or prevent text wrapping, while the general effect of setting maxwidth to NA or a finite value is to encourage wrapping. Settings for one entry may affect the width and wrapping of other entries, because column widths and row heights for the table as a whole must satisfy the constraints for all their entries.

• Text representing plotmath expressions cannot be wrapped, so maxwidth should be Inf or <= -1 for such entries.

Columns in elements(x, type="block")

Block descriptors:

id

Character string that uniquely identifies the block. The format is just <type> for blocks types that are unique. For blocks associated with row or column headers, or with row groups formed by the plot option rowgroupSize, ID's begin with <type>/<subtype>/<headlayer>/<level_in_layer>. See Appendix B of the package vignette for details about the definitions and ID's of these blocks.

type

Character string that specifies the nature or structural role of the block. One of

"table"

The whole table (all cells).

"title", "subtitle", "colhead", "rowhead", "rowheadLabels", "body", "foot"

The standard table parts. (If there are interior row header entries, "rowhead" and "body" are omitted because the interleaving of headers and body means neither are valid blocks.)

"titles"

The union of the title and subtitle parts.

"stub"

If we exclude the title/subtitle and foot annotations, a table has four quadrants: the body at the lower right, the row headers at the lower left, the column headers at the upper right, and a stub at the upper left. That is, the stub consists of the cells above the row headers and to the left of the column headers. (If there are row header labels–block "rowheadLabels"–they will be in the bottom row of the stub.)

"colhead_and_stub", "rowhead_and_stub"

The unions of "stub" with "colhead" and "rowhead", respectively.

"colhead_and_body", "rowhead_and_body"

The unions of "body" with "colhead" and "rowhead", respectively.

"rowblock", "colblock"

Collections of blocks associated with row and column headers, reflecting their hierarchical structure. "rowblock" is also the type for blocks representing row groups formed by plot option rowgroupSize. See Appendix B of the package vignette for details.

subtype

Character string refining block type. For types "rowblock" and "colblock", subtypes are "A", "B", "C", and (for "rowblock" only) "G". See Appendix B of the package vignette for their meaning. For other block types the subtype is set to missing (NA).

headlayer

For "rowblock" and "colblock" blocks, the header layer number with which the block is associated. (Layer numbers increase from innermost to outermost layer.) For other block types, headlayer is NA.

level_in_layer

For "rowblock" and "colblock" blocks, the level number (within the header layer) with which the block is associated. Levels are numbered from 1 to the maximum number of levels in that layer. For other block types, level_in_layer is NA.

group_in_level

For "rowblock" blocks of subtype "G" (representing sets of rows grouped according to rowgroupSize), the group number within a header layer and level. NA for other block types/subtypes.

had_enabled_entries

Logical, set to TRUE if there were _enabled_ table entries in x that intersect the block. This is set at the time the plotted table (pltdTable object) is created. It is not updated if entries are later enabled/disabled using props<-, for example.

nr, nc

The number of rows and columns, respectively, that the block spans. May be 0 for empty blocks.

arow1, arow2, acol1, acol2

First and last row and column numbers spanned by the block, with respect to the augmented row-column grid for the table. Empty blocks, with no rows or no columns (nr or nc equal to 0), will have the corresponding arow* or acol* set to NA.

enabled

Logical indicating whether the block is to be displayed when the table is plotted. This applies only to highlighting the rectangular region occupied by the block using a fill color or border. It has no effect on display of entries or hvrules contained within the block.

Graphical properties for blocks. Values for these are assigned by a style, either a default style (see ?tablesggOpt) or user-specified.

fill

Character string; color used to fill the rectangular region contained in the block. NA means the region is not colored. (Blocks are drawn before table entries or hvrules, so the block fill color will not hide those elements even if it is opaque.)

fill_alpha

Numeric value in [0, 1] specifying transparency of the block fill color (0=transparent, 1=opaque).

border_size

Thickness of the border to draw around the block, in millimeters.

border_color

Character string; color for the border around the block. NA means no border.

Columns in elements(x, type="hvrules")

hvrule descriptors:

id

Character string that uniquely identifies the hvrule. The format is <block>_<side>.

direction

Character string, either "hrule" for a horizontal rule or "vrule" for a vertical rule.

block

The ID of the block along the side of which the hvrule runs.

side

Which side of the block the hvrule runs along, "top", "bottom", "left", or "right".

adjacent_blocks

Character string containing the IDs of blocks that are adjacent to block on the same side as the hvrule. (I.e., blocks that are separated from block by the hvrule.) Block IDs within the string are separated by semicolons. If there are no adjacent blocks the string will be empty ("").

arow1, arow2, acol1, acol2

Location of the hvrule with respect to the augmented row-column grid of the table. An hrule is inserted between table rows, and therefore arow1 and arow2 are the same and equal to a half-integer. For example, an hrule inserted between rows 3 and 4 has arow1 = arow2 = 3.5. acol1 and acol2 for the hrule are integers indicating the range of columns that it spans. Analogously, a vrule is inserted between table columns, so acol1 and acol2 are identical and equal to a half-integer, while arow1 and arow2 are integers that indicate the range of rows spanned by the vrule.

enabled

Logical indicating whether the hvrule is to be displayed when the table is plotted. If FALSE the hvrule is ignored when laying out the table or determining its size.

Graphical properties for hvrules. Values for these are assigned by a style, either a default style (see ?tablesggOpt) or user-specified.

linetype

Integer indicating the type of line to display. 1 = solid line; 2 = dashed; 3 = dotted. (See the documentation of lty in ?par for the full set of choices.) A line type of 0 means no line will be drawn, so the hvrule just inserts empty space between table rows or columns.

size

Thickness of the line, in millimeters.

color

Character string; the color of the line.

alpha

Numeric value in [0, 1] specifying transparency of the line color (0=transparent, 1=opaque).

space

The width (for a vertical rule) or height (for a horizontal rule) of the rectangle inserted between columns or rows by the hvrule. (A line, if any, is drawn within this rectangle.) This is the amount of space the rule adds to the width or height of the table, in millimeters.

fill

Character string; color used to fill the rectangle containing the hvrule. NA means the region is not colored.

fill_alpha

Numeric value in [0, 1] specifying transparency of the fill color (0=transparent, 1=opaque).

Value

A data frame with one row per element. Columns include element descriptors and graphical properties assigned to each element. The row names of the data frame will be the element ID's.

See Also

tablesggOpt, styleObj, ids

Examples

plt <- plot(iris2_tab)
str(elements(plt, type="entry"))
str(elements(plt, type="block"))  # 0 rows, none are enabled for display
str(elements(plt, type="block", enabledOnly=FALSE))
str(elements(plt, type="hvrule"))