styleObj: Create a Style Object
In tablesgg: Presentation-Quality Tables, Displayed Using 'ggplot2'
View source: R/styleObj.bare.R
styleObj R Documentation
Create a Style Object
Description
Create a style object that can be used to assign graphical properties to
table elements (entries, hvrules, or blocks). The properties are used
when displaying the elements. Styles allow assignment of graphical
properties to be based on element descriptors.
Usage
styleObj(x, type, match_columns=character(0))
Arguments
x
Data frame with (a) column(s) that specify patterns to be used to identify
and select a subset of table elements; and (b) columns specifying the
graphical properties to be used for elements in the selected subset. See
DETAILS. May also be a string with the path to a .csv file that
will be read to create such a data frame.
type
Character string, one of "entry", "hvrule", or "block". This specifies
the type of element to which the style will apply.
match_columns
Optional character vector (possibly empty) with the names of element
descriptors that are required in order to evaluate the subset selector
expressions in x. See DETAILS.
Details
A style specifies graphical properties to be used in displaying one of the
element types in a table (i.e., entries, hvrules, or blocks). A style is
similar to a theme in ggplot2 in that it can be applied to any
table, not just a particular table.
A styleObj object is a data frame. Each row can be thought of as a
pattern plus a set of graphical properties. Table elements that are to be
styled are compared to the patterns. If the pattern in a style row
matches a table element, the graphical properties in that row are assigned
to the element. If more than one style row matches an element, the
properties from the last matching row override the earlier ones.
The graphical property columns that must be present in a styleObj
data frame are described in ?elements.
Specification of style patterns and how they are matched to elements is
similar for table entries and blocks, and is described first. The process
for hvrules is more complicated and is described second. It will be
easier to follow the descriptions if one also looks at an example, such as
View(styles_pkg$entryStyle_pkg_1) and
View(styles_pkg$hvruleStyle_pkg_1).
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 the element descriptors mentioned in the previous
paragraph. 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.) Examples of such strings are part ==
"rowhead" & multirow for entries and type == "colblock" & subtype
== "A" & headlayer > 1 for blocks.
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.
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.
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.
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", "bottom", "left", or
"right"); 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 and 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.
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).
Value
An object of S3 classes styleObj and data.frame. It will
have the same number of rows and all the columns in x.
The object will have attributes element_type and
match_columns, equal to the corresponding arguments.
See Also
styles_pkg contains predefined styles provided by the
package. They can be examined as illustrations of how styles are
specified, or edited to create new styles. elements lists
the descriptors and graphical properties available for each element type.
Examples
# Built-in default styles:
if (interactive()) {
View(styles_pkg$entryStyle_pkg_1)
View(styles_pkg$blockStyle_pkg_1)
View(styles_pkg$hvruleStyle_pkg_1)
}
tablesgg documentation built on June 22, 2024, 11:02 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/styleObj.bare.R
| styleObj | R Documentation |
Create a Style Object
Description
Create a style object that can be used to assign graphical properties to table elements (entries, hvrules, or blocks). The properties are used when displaying the elements. Styles allow assignment of graphical properties to be based on element descriptors.
Usage
styleObj(x, type, match_columns=character(0))
Arguments
x |
Data frame with (a) column(s) that specify patterns to be used to identify
and select a subset of table elements; and (b) columns specifying the
graphical properties to be used for elements in the selected subset. See
DETAILS. May also be a string with the path to a |
type |
Character string, one of "entry", "hvrule", or "block". This specifies the type of element to which the style will apply. |
match_columns |
Optional character vector (possibly empty) with the names of element
descriptors that are required in order to evaluate the subset selector
expressions in |
Details
A style specifies graphical properties to be used in displaying one of the
element types in a table (i.e., entries, hvrules, or blocks). A style is
similar to a theme in ggplot2 in that it can be applied to any
table, not just a particular table.
A styleObj object is a data frame. Each row can be thought of as a
pattern plus a set of graphical properties. Table elements that are to be
styled are compared to the patterns. If the pattern in a style row
matches a table element, the graphical properties in that row are assigned
to the element. If more than one style row matches an element, the
properties from the last matching row override the earlier ones.
The graphical property columns that must be present in a styleObj
data frame are described in ?elements.
Specification of style patterns and how they are matched to elements is
similar for table entries and blocks, and is described first. The process
for hvrules is more complicated and is described second. It will be
easier to follow the descriptions if one also looks at an example, such as
View(styles_pkg$entryStyle_pkg_1) and
View(styles_pkg$hvruleStyle_pkg_1).
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 the element descriptors mentioned in the previous
paragraph. 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.) Examples of such strings are part ==
"rowhead" & multirow for entries and type == "colblock" & subtype
== "A" & headlayer > 1 for blocks.
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.
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.
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.
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", "bottom", "left", or
"right"); 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 and 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.
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).
Value
An object of S3 classes styleObj and data.frame. It will
have the same number of rows and all the columns in x.
The object will have attributes element_type and
match_columns, equal to the corresponding arguments.
See Also
styles_pkg contains predefined styles provided by the
package. They can be examined as illustrations of how styles are
specified, or edited to create new styles. elements lists
the descriptors and graphical properties available for each element type.
Examples
# Built-in default styles:
if (interactive()) {
View(styles_pkg$entryStyle_pkg_1)
View(styles_pkg$blockStyle_pkg_1)
View(styles_pkg$hvruleStyle_pkg_1)
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.