This is a function meant for advanced users to gain
more control over the characteristics of the resulting
gtsummary table by directly modifying .$table_styling
.
This function is primarily used in the development of other gtsummary
functions, and very little checking of the passed arguments is performed.
Usage
modify_table_styling(
x,
columns,
rows = NULL,
label = NULL,
spanning_header = NULL,
hide = NULL,
footnote = NULL,
footnote_abbrev = NULL,
align = NULL,
missing_symbol = NULL,
fmt_fun = NULL,
text_format = NULL,
undo_text_format = NULL,
indent = NULL,
text_interpret = c("md", "html"),
cols_merge_pattern = NULL
)
Arguments
- x
(
gtsummary
)
gtsummary object- columns
(
tidy-select
)
Selector of columns inx$table_body
- rows
(predicate
expression
)
Predicate expression to select rows inx$table_body
. Can be used to style footnote, formatting functions, missing symbols, and text formatting. Default isNULL
. See details below.- label
(
character
)
Character vector of column label(s). Must be the same length ascolumns
.- spanning_header
(
string
)
string with text for spanning header- hide
(scalar
logical
) Logical indicating whether to hide column from output- footnote
(
string
)
string with text for footnote- footnote_abbrev
(
string
)
string with abbreviation definition, e.g."CI = Confidence Interval"
- align
(
string
) String indicating alignment of column, must be one ofc("left", "right", "center")
- missing_symbol
(
string
)
string indicating how missing values are formatted.- fmt_fun
(
function
)
function that formats the statistics in the columns/rows incolumns
androws
- text_format, undo_text_format
(
string
)
String indicated which type of text formatting to apply/remove to the rows and columns. Must be one ofc("bold", "italic")
.- indent
(
integer
)
An integer indicating how many space to indent text- text_interpret
(
string
)
Must be one of"md"
or"html"
and indicates the processing function asgt::md()
orgt::html()
. Use this in conjunction with arguments for header and footnotes.- cols_merge_pattern
(
string
) experimental
glue-syntax string indicating how to merge columns inx$table_body
. For example, to construct a confidence interval use"{conf.low}, {conf.high}"
. The first column listed in the pattern string must match the single column name passed incolumns=
.
Details
Review the
gtsummary definition
vignette for information on .$table_styling
objects.
rows argument
The rows argument accepts a predicate expression that is used to specify
rows to apply formatting. The expression must evaluate to a logical when
evaluated in x$table_body
. For example, to apply formatting to the age rows
pass rows = variable == "age"
. A vector of row numbers is NOT acceptable.
A couple of things to note when using the rows
argument.
You can use saved objects to create the predicate argument, e.g.
rows = variable == letters[1]
.The saved object cannot share a name with a column in
x$table_body
. The reason for this is that intbl_merge()
the columns are renamed, and the renaming process cannot disambiguate thevariable
column from an external object namedvariable
in the following expressionrows = .data$variable = .env$variable
.
cols_merge_pattern argument
There are planned updates to the implementation of column merging.
Currently, this function replaces the numeric column with a
formatted character column following cols_merge_pattern=
.
Once gt::cols_merge()
gains the rows=
argument the
implementation will be updated to use it, which will keep
numeric columns numeric. For the vast majority of users,
the planned change will be go unnoticed.
If this functionality is used in conjunction with tbl_stack()
(which
includes tbl_uvregression()
), there is potential issue with printing.
When columns are stack AND when the column-merging is
defined with a quosure, you may run into issues due to the loss of the
environment when 2 or more quosures are combined. If the expression
version of the quosure is the same as the quosure (i.e. no evaluated
objects), there should be no issues. Regardless, this argument is used
internally with care, and it is not recommended for users.
See also
See gtsummary internals vignette
Other Advanced modifiers:
modify_column_indent()
,
modify_column_merge()