tblEntries: Assemble Information About Each Entry in a Table into a Data...

In tablesgg: Presentation-Quality Tables, Displayed Using 'ggplot2'

Assemble Information About Each Entry in a Table into a Data Frame

Description

Assemble information about each entry in a table into a data frame with one row per entry, and columns for entry content and position in the table. This is an internal function, not intended to be called by package users.

Usage

tblEntries(x, mergeRuns=c(TRUE, TRUE), rowheadInside=FALSE)

Arguments

x	A textTable object, or something that can be coerced to one.
mergeRuns	Two-element logical vector, the first element applying to row headers, the second to column headers. If TRUE (the default) then header cells that contain runs of the same value will be merged into a single entry that spans multiple rows or columns. Note that runs in the outermost row header layer are always merged when rowheadInside is TRUE, even if mergeRuns[1] is FALSE.
rowheadInside	Logical scalar. If TRUE, the outermost layer of row headers is moved inside the table by using its levels to divide the table into groups of rows, with each group labeled by their level.

Details

Entries include all parts of the table: the body of the table, row and column headers, titles, subtitles, and foot lines. This function calls textTable(x) to convert table entries to character strings if necessary.

If the text for an entry is missing (NA) the entry will be disabled, with a warning. If the text is an empty string (""), the entry will be disabled by default; this is so that blocks containing only empty cells will not have hvrules generated for them.

Row and column numbers used in creating default entry ID's are partrow and partcol, and thus with respect to the dimensions of the table part the entry belongs to, not the augmented row-column grid. If an entry spans more than one row or column, the minimum row/column number of the spanned cells is used.

The rowhier and colhier attributes are included primarily to assist creation of table blocks by function tblBlocks.

The inclusion of the hjust column is not tidy, since it is really a graphical display property. However it is needed to carry forward justification information that x may have inherited from a tabular object.

The tblEntries method for textTable is the inverse of this function: it will re-create a textTable from a tblEntries object.

Value

An object of S3 class tblEntries. This is a data frame with one row per entry in the table. It contains descriptors with information about the nature and position of each entry within the table. Column descriptions are in the documentation for the elements function. Additional details for certain columns are:

subpart	For row and column headers, the subpart will be the name of the corresponding column in x$rowhead or row in x$colhead.
level_in_layer	Numbering of entries within a given part and headlayer. For row and column headers this is based their hierarchical structure (see tblBlocks), and assumes mergeRuns is TRUE (so multiple entries within a layer may have the same level number). For other table parts it is just an integer from 1 to the number of entries in that layer of that part.
type	Character string identifying the type of value the entry represents (e.g., "numeric"). This is taken from the type attributes of components of x, and may be NA for unknown or unspecified type. 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". The default is "plain", but any entry whose text begins with "MATH_" or "MKDN_" will have textspec set to "plotmath" or "markdown", respectively, and the prefix will be removed from text.
enabled	Logical indicating whether the entry is to be displayed. This function sets enabled to FALSE for entries whose text is NA (with a warning) or the empty string "", and to TRUE for all other entries.
hjust	Numeric horizontal justification specification for entry text (0=left, 0.5=center, 1=right, NA=unspecified). This is set based on the justification attributes of components of x if present, NA if not.

Row names for the data frame are set equal to id. The data frame has attributes mergeRuns and rowheadInside, based on the arguments. It also has attributes rowhier and colhier, containing information about the row and column header hierarchies. They are lists of data frames, copied from the corresponding components of x. They reflect the logical structure of the headers and are unaffected by display choices such as mergeRuns and rowheadInside.

See Also

textTable, tblParts; as.tblEntries, elements.

tablesgg documentation built on June 22, 2024, 11:02 a.m.