tblBlocks: Define Blocks of Cells that Reflect the Logical Structure of...
In tablesgg: Presentation-Quality Tables, Displayed Using 'ggplot2'

Description Usage Arguments Details Value See Also

Define a collection of rectangular blocks of cells that reflect the logical structure of a table. This is an internal function, not intended to be called by package users.

1	tblBlocks(x, rowgroupSize=0, ...)

`x`	A `tblEntries` object, or something that can be converted to one (e.g., a `textTable` object).
`rowgroupSize`	Numeric scalar. If greater than 0, blocks will be created by grouping consecutive rows of the table body into sets of this size. See DETAILS.
`...`	Additional arguments passed to `tblEntries` when `x` is not already a `tblEntries` object (e.g., `rowheadInside`).

A block is simply a rectangular set of contiguous table cells. Any number of blocks may be defined for a given table, and blocks may overlap. A block may be empty (nr and/or nc equal to 0, and corresponding arow* and acol* values set to NA.)

This function defines a standard set of blocks based on the logical structure of a table (but independent of the _content_ of table cells). The following blocks are defined:

"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.

Each of these blocks is unique and so their id and type are the same string. subtype, headlayer, and level_in_layer are set to NA for them.

Blocks representing the hierarchical structure of headers

Additional blocks, with types "rowblock" and "colblock", are defined to represent the hierarchical structure of row and column headers. To describe these blocks, some terminology is needed. For concreteness, the description is in terms of column headers; analogous comments apply to row headers.

When a table is displayed, each _row_ of column headers (corresponding to a row of the colhead matrix in a textTable object), defines one _layer_ of the header. Layers are numbered from innermost (closest to the table body) to outermost. Structurally, layers form a hierarchy: header values at a lower numbered (inner) layer are nested within values at higher numbered (outer) layers. This hierarchy implies a tree-structured partitioning of table columns according to values of the header variables. A set of contiguous columns that share the same header value for a layer, and for all layers above it in the hierarchy, belong to a single _level_ of that layer. Levels are numbered from 1 to the number of levels in a layer.

Then for each combination of layer number i and level number j in a header, three blocks are defined. A block with subtype "A" consists of just the cells in header layer i whose value corresponds to level number j. It will thus come from a single row in the column headers of the table. And since all the cells in the block have the same value, those cells will typically be merged into a single entry when displaying the table.

A block with subtype "B" is bigger: it consists of the cells in the subtype "A" block, plus the header cells with _smaller_ layer numbers in the same columns. So it extends from layer i down through the rest of the header rows. And finally a block with subtype "C" is bigger yet: it consists of the cells in the subtype "B" block plus the cells in the table body in the same columns. That is, it spans the same set of columns as the subtype "A" and "B" blocks but adds rows down through the table body. Block ID's have the form colblock/<subtype>/i/j.

Sets of blocks for the row headers are defined analogously. Each _column_ in the row headers of a displayed table (corresponding to a column in the rowhead matrix of a textTable object) represents one layer. The layer closest to the table body is numbered 1 and layer number increases toward the left edge of the table. A subtype "A" block consists of the cells in layer number i whose value corresponds to level number j in that layer. It will thus come from a single column in the row headers of the table. A subtype "B" block consists of the cells in the "A" block, plus the header cells with _smaller_ layer numbers in the same rows. A subtype "C" block further adds the cells in the table body in the same rows. That is, it spans the same set of rows as "A" and "B" blocks but adds columns across through the table body. Block ID's have the form rowblock/<subtype>/i/j.

Blocks when rowheadInside is TRUE

Moving the outermost layer of row header entries into the interior of the table, where they separate and label groups of rows, changes the shape of table parts. Specifically, since row headers and body are interleaved, neither forms a valid rectangular block. However their union is a valid block, with ID and type rowhead_and_body.

When a row header layer is moved inside, its layer number is set to 0. (Conceptually, since it is interleaved with the table body, it is interior even to header layer 1.) Blocks rowblock/<subtype>/i/j, where i indicates layer number, are different when i=0 than for other layers. Subtype "A", rowblock/A/0/j, has one row and spans all table columns. It contains the label for the j-th level. Subtype "B", rowblock/B/0/j, contains all row header entries (if any) nested within level j. Subtype "C", rowblock/C/0/j, combines rowblock/B/0/j with all the body rows associated with level j. Thus rowblock/C/0/j spans all table columns. Unlike when i is not equal to 0, neither rowblock/B/0/j nor rowblock/C/0/j contain rowblock/A/0/j.

Blocks representing groups of rows

When a table has many rows within a given level of the row header hierarchy, the table may be easier to read if rows are grouped into smaller sets of fixed size (groups of 5, for example), with some extra space inserted between groups. To facilitate this, this function creates blocks representing such groups when rowgroupSize is positive. The block type is "rowblock" and subtype is "G".

Grouping respects the row header hierarchy: the innermost header layer that has runs of repeated values is identified (layer i say), and grouping is done separately within each of its levels. The block representing a row group spans all columns of the table body as well as row header layers out to layer i-1. Block ID's have the form rowblock/G/i/j/k, where j is the level number (within layer i) that contains the group, and k is the group number within that level. Thus i, j, and k are the values of headlayer, level_in_layer, and group_in_level for the block.

However if the table has no row headers, or none of the row header layers have runs of repeated values, table rows are simply grouped into sets of size rowgroupSize. headlayer and level_in_layer will be NA for the group blocks, and block ID's will have the form rowblock/G///k, where k is the group number (and value of group_in_level).

An S3 object of class tblBlocks. This is a data frame with one row per block. It contains information about the nature and position of each block. Column descriptions are in the documentation for the elements function. Also see DETAILS for more information about columns id, type, and subtype.

Row names for the data frame are set equal to id. rowgroupSize and rowheadInside (the latter taken from x, after converting it to a tblEntries object if necessary) will be included as attributes.

tblEntries, tblParts, elements; as.tblBlocks converts a data frame to a tblBlocks object.