Format by simply passing data through

We can format values with fmt_passthrough(), which does little more than: (1) coercing to character (as all the fmt_*() functions do), and (2) applying decorator text via the pattern argument (the default is to apply nothing). This formatting function is useful when don't want to modify the input data other than to decorate it within a pattern.

Usage

fmt_passthrough(
  data,
  columns = everything(),
  rows = everything(),
  escape = TRUE,
  pattern = "{x}"
)

Arguments

data

The gt table data object

obj:<gt_tbl> // required

This is the gt table object that is commonly created through use of the gt() function.

columns

Columns to target

<column-targeting expression> // default: everything()

Can either be a series of column names provided in c(), a vector of column indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range() and everything()).

rows

Rows to target

<row-targeting expression> // default: everything()

In conjunction with columns, we can specify which of their rows should undergo formatting. The default everything() results in all rows in columns being formatted. Alternatively, we can supply a vector of row captions within c(), a vector of row indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()). We can also use expressions to filter down to the rows we need (e.g., [colname_1] > 100 & [colname_2] < 50).

escape

Text escaping

scalar<logical> // default: TRUE

An option to escape text according to the final output format of the table. For example, if a LaTeX table is to be generated then LaTeX escaping would be performed during rendering. By default this is set to TRUE but setting as FALSE would be useful in the case where text is crafted for a specific output format in mind.

pattern

Specification of the formatting pattern

scalar<character> // default: "{x}"

A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.

Value

An object of class gt_tbl.

Compatibility of arguments with the `from_column()` helper function

from_column() can be used with certain arguments of fmt_passthrough() to obtain varying parameter values from a specified column within the table. This means that each row could be formatted a little bit differently. These arguments provide support for from_column():

escape
pattern

Please note that for both of the aforementioned arguments, a from_column() call needs to reference a column that has data of the correct type (this is different for each argument). Additional columns for parameter values can be generated with cols_add() (if not already present). Columns that contain parameter data can also be hidden from final display with cols_hide(). Finally, there is no limitation to how many arguments the from_column() helper is applied so long as the arguments belong to this closed set.

Examples

Let's use the exibble dataset to create a single-column gt table (with only the char column). Now we can pass the data in that column through the 'non-formatter' that is fmt_passthrough(). While the function doesn't do any explicit formatting it has a feature common to all other formatting functions: the pattern argument. So that's what we'll use in this example, applying a simple pattern to the non-NA values that adds an "s" character.

exibble |>
  dplyr::select(char) |>
  gt() |>
  fmt_passthrough(
    rows = !is.na(char),
    pattern = "{x}s"
  )

This image of a table was generated from the first code example in the `fmt_passthrough()` help file.

Function ID

3-28

Function Introduced

v0.2.0.5 (March 31, 2020)