Text transforming in gt is the act of modifying formatted strings in
targeted cells. The text_transform()
function provides the most flexibility
of all the text_*()
functions in their family of functions. With it, you
target the cells to undergo modification in the locations
argument while
also supplying a function to the fn
argument. The function given to fn
should ideally at the very least take x
as an input (it stands for the
character vector that is essentially the targeted cells) and return a
character vector of the same length as the input. Using the construction
function(x) { .. }
for the function is recommended.
Usage
text_transform(data, fn, locations = cells_body())
Arguments
- data
The gt table data object
obj:<gt_tbl>
--- requiredThis is the gt table object that is commonly created through use of the
gt()
function.- fn
Function for text transformation
<function>
--- requiredThe function to use for text transformation. It should include
x
as an argument and return a character vector of the same length as the inputx
.- locations
Locations to target
<locations expressions>
--- default:cells_body()
The cell or set of cells to be associated with the text transformation. Only the
cells_body()
,cells_stub()
,cells_row_groups()
,cells_column_labels()
, andcells_column_spanners()
helper functions can be used here. We can enclose several of these calls within alist()
if we wish to make the transformation happen at different locations.
Examples
Use a subset of the sp500
dataset to create a gt table. Transform the
text in the date
column using a function supplied to text_transform()
(via the fn
argument). Note that the x
in the fn = function (x)
part
consists entirely of ISO 8601 date strings (which are acceptable as input to
the vec_fmt_date()
and vec_fmt_datetime()
functions).
sp500 |>
dplyr::slice_head(n = 10) |>
dplyr::select(date, open, close) |>
dplyr::arrange(-dplyr::row_number()) |>
gt() |>
fmt_currency() |>
text_transform(
fn = function(x) {
paste0(
"<strong>",
vec_fmt_date(x, date_style = "m_day_year"),
"</strong>",
"—W",
vec_fmt_datetime(x, format = "w")
)
},
locations = cells_body(columns = date)
) |>
cols_label(
date = "Date and Week",
open = "Opening Price",
close = "Closing Price"
)
Let's use a summarized version of the gtcars
dataset to create a gt
table. First, the numeric values in the n
column are formatted as
spelled-out numbers with fmt_spelled_num()
. The output values are indeed
spelled out but exclusively with lowercase letters. We actually want these
words to begin with a capital letter and end with a period. To make this
possible, the text_transform()
function will be used since it can modify
already-formatted text. Through the fn
argument, we provide a custom
function that uses R's toTitleCase()
operating on x
(the numbers-as-text
strings) within a paste0()
so that a period can be properly placed.
gtcars |>
dplyr::select(mfr, ctry_origin) |>
dplyr::filter(ctry_origin %in% c("Germany", "Italy", "Japan")) |>
dplyr::group_by(mfr, ctry_origin) |>
dplyr::count() |>
dplyr::ungroup() |>
dplyr::arrange(ctry_origin, desc(n)) |>
gt(rowname_col = "mfr", groupname_col = "ctry_origin") |>
cols_label(n = "No. of Entries") |>
tab_stub_indent(rows = everything(), indent = 2) |>
cols_align(align = "center", columns = n) |>
fmt_spelled_num() |>
text_transform(
fn = function(x) {
paste0(tools::toTitleCase(x), ".")
},
locations = cells_body(columns = n)
)
See also
Other text transforming functions:
text_case_match()
,
text_case_when()
,
text_replace()