R/info_tables.R
In rstudio/gt: Easily Create Presentation-Ready Display Tables
Defines functions
info_unit_conversions
info_icons
info_flags
info_google_fonts
info_paletteer
info_locales
info_currencies
info_time_style
info_date_style
Documented in
info_currencies
info_date_style
info_flags
info_google_fonts
info_icons
info_locales
info_paletteer
info_time_style
info_unit_conversions
#------------------------------------------------------------------------------#
#
# /$$
# | $$
# /$$$$$$ /$$$$$$
# /$$__ $$|_ $$_/
# | $$ \ $$ | $$
# | $$ | $$ | $$ /$$
# | $$$$$$$ | $$$$/
# \____ $$ \___/
# /$$ \ $$
# | $$$$$$/
# \______/
#
# This file is part of the 'rstudio/gt' project.
#
# Copyright (c) 2018-2024 gt authors
#
# For full copyright and license information, please look at
# https://gt.rstudio.com/LICENSE.html
#
#------------------------------------------------------------------------------#
# info_date_style() ------------------------------------------------------------
#' View a table with info on date styles
#'
#' @description
#'
#' [fmt_date()] lets us format date-based values in a convenient manner using
#' preset styles. The table generated by `info_date_style()` provides a quick
#' reference to all styles, with associated format names and example outputs
#' using a fixed date (`2000-02-29`).
#'
#' @param locale *Locale identifier*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' An optional locale identifier that can be used for displaying formatted
#' date values according the locale's rules. Examples include `"en"` for
#' English (United States) and `"fr"` for French (France). We can call
#' [info_locales()] for a useful reference for all of the locales that are
#' supported.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on the different date-formatting styles (which are used
#' by supplying a number code to [fmt_date()]).
#'
#' ```r
#' info_date_style()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_date_style_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-1
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_date_style <- function(locale = NULL) {
if (is.null(locale)) {
locale <- "en"
}
date_df <- date_formats()
date_df$date <- "2000-02-29"
flexible_rows <- date_df[, "flexible"][["flexible"]]
date_df$flexible[flexible_rows] <- "FLEXIBLE"
date_df$flexible[!flexible_rows] <- ""
gt_tbl <- gt(date_df, rowname_col = "format_number", locale = locale)
gt_tbl <- cols_hide(gt_tbl, columns = format_code)
gt_tbl <-
fmt_date(
gt_tbl,
columns = date,
date_style = from_column(column = "format_name")
)
gt_tbl <-
text_transform(
gt_tbl,
locations = cells_body(
columns = flexible,
rows = flexible == "FLEXIBLE"
),
fn = function(x) {
paste0(
"<span style='",
"color: darkslategray; font-weight: 700; font-size: 12px; ",
"border: solid 1px; background: aliceblue; border-color: steelblue; ",
"border-width: 2px; border-radius: 4px; padding: 0px 8px 0px 8px;",
"'>", x, "</span>"
)
}
)
gt_tbl <-
cols_label(
gt_tbl,
format_name = "Format Name",
flexible = "",
date = html(
paste0(
"Formatted Date (<span style=\"text-transform:none;\">",
locale,
"</span>)"
)
)
)
gt_tbl <-
cols_width(
gt_tbl,
format_number ~ px(60),
format_name ~ px(220),
flexible ~ px(100),
date ~ px(315)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- cols_align(gt_tbl, align = "center", columns = flexible)
gt_tbl <- cols_align(gt_tbl, align = "left", columns = date)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
locations = cells_body(columns = format_name)
)
gt_tbl <-
tab_style(
gt_tbl,
style =
cell_borders(
sides = "r",
color = "lightblue",
weight = px(1.5)
),
locations = cells_body(columns = format_name)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden"
)
gt_tbl <-
tab_header(
gt_tbl,
title = "Date Formatting Options",
subtitle = md(
"Usable in the `fmt_date()` and `fmt_datetime()` functions.<br><br>"
)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.7)
gt_tbl
}
# info_time_style() ------------------------------------------------------------
#' View a table with info on time styles
#'
#' @description
#'
#' [fmt_time()] lets us format time-based values in a convenient manner using
#' preset styles. The table generated by `info_time_style()` provides a quick
#' reference to all styles, with associated format names and example outputs
#' using a fixed time (`14:35`).
#'
#' @param locale *Locale identifier*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' An optional locale identifier that can be used for displaying formatted
#' time values according the locale's rules. Examples include `"en"` for
#' English (United States) and `"fr"` for French (France). We can call
#' [info_locales()] for a useful reference for all of the locales that are
#' supported.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on the different time-formatting styles (which are used
#' by supplying a number code to `fmt_time()`).
#'
#' ```r
#' info_time_style()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_time_style_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-2
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_time_style <- function(locale = NULL) {
if (is.null(locale)) {
locale <- "en"
}
time_df <- time_formats()
time_df$time <- "14:35"
flexible_rows <- time_df[, "flexible"][["flexible"]]
time_df$flexible[flexible_rows] <- "FLEXIBLE"
time_df$flexible[!flexible_rows] <- ""
gt_tbl <- gt(time_df, rowname_col = "format_number", locale = locale)
gt_tbl <- cols_hide(gt_tbl, columns = format_code)
gt_tbl <-
fmt_time(
gt_tbl,
columns = time,
time_style = from_column(column = "format_name")
)
gt_tbl <-
text_transform(
gt_tbl,
locations = cells_body(
columns = flexible,
rows = flexible == "FLEXIBLE"
),
fn = function(x) {
paste0(
"<span style='",
"color: darkslategray; font-weight: 700; font-size: 12px; ",
"border: solid 1px; background: aliceblue; border-color: steelblue; ",
"border-width: 2px; border-radius: 4px; padding: 0px 8px 0px 8px;",
"'>", x, "</span>"
)
}
)
gt_tbl <-
cols_label(
gt_tbl,
format_name = "Format Name",
time_type = "12/24h",
flexible = "",
time = html(
paste0(
"Formatted Time (<span style=\"text-transform:none;\">",
locale,
"</span>)"
)
)
)
gt_tbl <-
cols_width(
gt_tbl,
format_number ~ px(60),
format_name ~ px(140),
time_type ~ px(80),
flexible ~ px(100),
time ~ px(315)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- sub_missing(gt_tbl, columns = time_type)
gt_tbl <-
cols_align(
gt_tbl,
align = "center",
columns = c(time_type, flexible)
)
gt_tbl <- cols_align(gt_tbl, align = "left", columns = time)
gt_tbl <- tab_style(
gt_tbl,
style = cell_text(size = "smaller"),
locations = cells_body(columns = time_type)
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
locations = cells_body(columns = format_name)
)
gt_tbl <-
tab_style(
gt_tbl,
style =
cell_borders(
sides = "r",
color = "lightblue",
weight = px(1.5)
),
locations = cells_body(columns = format_name)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden"
)
gt_tbl <-
tab_header(
gt_tbl,
title = "Time Formatting Options",
subtitle = md(
"Usable in the `fmt_time()` and `fmt_datetime()` functions.<br><br>"
)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.7)
gt_tbl
}
# info_currencies() ------------------------------------------------------------
#' View a table with info on supported currencies
#'
#' @description
#'
#' [fmt_currency()] lets us format numeric values as currencies. The table
#' generated by `info_currencies()` provides a quick reference to all the
#' available currencies. The currency identifiers are provided (name, 3-letter
#' currency code, and 3-digit currency code) along with the each currency's
#' exponent value (number of digits of the currency subunits). A formatted
#' example is provided (based on the value of `49.95`) to demonstrate the
#' default formatting of each currency.
#'
#' @details
#'
#' There are 172 currencies, which can lead to a verbose display table. To make
#' this presentation more focused on retrieval, we can provide an initial letter
#' corresponding to the 3-letter currency code to `begins_with`. This will
#' filter currencies in the info table to just the set beginning with the
#' supplied letter.
#'
#' @param type *Type of currency*
#'
#' `singl-kw:[code|symbol]` // *default:* `"code"`
#'
#' The type of currency information provided. Can either be `"code"` where
#' currency information corresponding to 3-letter/3-number currency codes is
#' provided, or `"symbol"` where currency info for common currency
#' names/symbols (e.g., dollar, pound, yen, etc.) is returned.
#'
#' @param begins_with *Show currencies beginning with a specific letter*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' Providing a single letter will filter currencies to only those that begin
#' with that letter in their currency code. The default (`NULL`) will produce
#' a table with all currencies displayed. This option only constrains the
#' information table where `type == "code"`.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all of the currencies where the three-letter code
#' begins with an `"h"`.
#'
#' ```r
#' info_currencies(begins_with = "h")
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_currencies_1.png")`
#' }}
#'
#' Get a table of info on all of the common currency name/symbols that can be
#' used with [fmt_currency()].
#'
#' ```r
#' info_currencies(type = "symbol")
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_currencies_2.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-3
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_currencies <- function(
type = c("code", "symbol"),
begins_with = NULL
) {
# Get the correct `type` value
type <- rlang::arg_match0(type, values = c("code", "symbol"))
if (type == "code") {
if (!is.null(begins_with)) {
starting <- toupper(substr(begins_with, 1, 1))
curr <-
dplyr::filter(currencies, grepl(paste0("^", starting, ".*"), curr_code))
} else {
curr <- currencies
}
curr_df <- curr[, c(4, 1, 2, 3)]
curr_df$value <- 49.95
gt_tbl <- gt(curr_df, id = "currencies")
gt_tbl <-
fmt_currency(
gt_tbl,
columns = "value",
currency = from_column(column = "curr_code")
)
gt_tbl <-
cols_label(
gt_tbl,
curr_name = md("Currency<br>Name"),
curr_code = md("Alpha<br>Code"),
curr_number = md("Numeric<br>Code"),
exponent = md("No. of<br>Subunits"),
value = md("Formatted<br>Currency"),
)
gt_tbl <-
cols_width(
gt_tbl,
curr_name ~ px(325),
curr_code ~ px(75),
curr_number ~ px(85),
exponent ~ px(85),
value ~ px(125)
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
locations = cells_body(columns = c(curr_code, curr_number))
)
gt_tbl <-
tab_header(
gt_tbl,
title = md("Currencies Supported in **gt**"),
subtitle = md(
"Currency codes are used in the `fmt_currency()` function<br><br>"
)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.8)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden",
container.height = px(620)
)
gt_tbl <-
tab_style(
gt_tbl,
style = css(position = "sticky", top = "-1em", `z-index` = 10),
locations = cells_column_labels()
)
} else {
curr_df <- currency_symbols
curr_df$symbol <- NULL
curr_df$value <- 49.95
gt_tbl <- gt(curr_df, id = "currency_symbols")
gt_tbl <-
fmt_currency(
gt_tbl,
columns = "value",
currency = from_column(column = "curr_symbol")
)
gt_tbl <-
cols_label(
gt_tbl,
curr_symbol = "Currency Symbol Keyword",
value = "Formatted Currency"
)
gt_tbl <-
cols_width(
gt_tbl,
curr_symbol ~ px(300),
value ~ px(300)
)
gt_tbl <-
tab_style(
gt_tbl,
style = list(
cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
cell_borders(
sides = "r",
color = "lightblue",
weight = px(1.5))
),
locations = cells_body(columns = curr_symbol)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden"
)
gt_tbl <-
tab_header(
gt_tbl,
title = md("Currencies Supported in **gt**"),
subtitle = md(
"Currency symbols are used in the `fmt_currency()` function.<br><br>"
)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.7)
}
gt_tbl
}
# info_locales() ------------------------------------------------------------
#' View a table with info on supported locales
#'
#' @description
#'
#' Many of the `fmt_*()` functions have a `locale` argument that makes
#' locale-based formatting easier. The table generated by the `info_locales()`
#' function provides a quick reference to all the available locales. The locale
#' identifiers are provided (base locale ID, common display name) along with the
#' each locale's group and decimal separator marks. A formatted numeric example
#' is provided (based on the value of `11027`) to demonstrate the default
#' formatting of each locale.
#'
#' @details
#'
#' There are `r nrow(locales)` locales, which means that a very long display
#' table is provided by default. To trim down the output table size, we can
#' provide an initial letter corresponding to the base locale ID to
#' `begins_with`. This will filter locales in the info table to just the set
#' that begins with the supplied letter.
#'
#' @param begins_with *Show locales beginning with a specific letter*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' Providing a single letter will filter locales to only those that begin
#' with that letter in their locale ID. The default (`NULL`) will produce
#' a table with all locales displayed
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all of the locales supported by **gt**.
#'
#' ```r
#' info_locales()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_locales_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-4
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_locales <- function(begins_with = NULL) {
locale <- lang_desc <- script_desc <- territory_desc <- NULL
variant_desc <- group <- decimal <- NULL
if (!is.null(begins_with)) {
starting <- tolower(substr(begins_with, 1, 1))
regex_starting <- paste0("^", starting, ".*")
loc <- vctrs::vec_slice(locales, grepl(regex_starting, locales$locale))
} else {
loc <- locales
}
tab_1 <-
dplyr::select(
loc, "locale", "lang_desc", "script_desc",
"territory_desc", "variant_desc", "group", "decimal"
)
tab_1$display_name <- paste0(
tab_1$lang_desc,
paste0(
" (",
tab_1$territory_desc, ", ",
tab_1$script_desc, ", ",
tab_1$variant_desc,
")"
)
)
tab_1$group <-
dplyr::case_match(
tab_1$group,
c("\u00a0", "\u202f") ~ "space",
.default = tab_1$group
)
tab_1 <- tab_1[c("locale", "display_name", "group", "decimal")]
tab_1$display_name <- gsub(" (NA, NA, NA)", "", tab_1$display_name, fixed = TRUE)
tab_1$display_name <- gsub(", NA, NA", "", tab_1$display_name, fixed = TRUE)
tab_1$display_name <- gsub("NA, ", "", tab_1$display_name, fixed = TRUE)
tab_1$display_name <- gsub(", NA)", ")", tab_1$display_name, fixed = TRUE)
tab_1$value <- 11027
gt(tab_1) %>%
tab_header(
title = md("Locales Supported in **gt**"),
subtitle = md("Locale codes are used in several `fmt_*()` functions.<br><br>")
) %>%
fmt_number(
columns = "value",
locale = from_column("locale")
) %>%
text_transform(
fn = function(x) sub("space", "\U02420", x),
locations = cells_body(columns = "group")
) %>%
cols_merge(
columns = c("locale", "display_name"),
pattern = "<code>{1}</code><br><span style=font-size:11px>{2}</span>"
) %>%
cols_label(
locale = "Locale",
group = "Group",
decimal = "Decimal",
value = html("Formatted<br>Value")
) %>%
cols_align(
align = "center",
columns = c("group", "decimal")
) %>%
tab_style(
style = css(position = "sticky", top = "-1em", `z-index` = 10),
locations = cells_column_labels()
) %>%
tab_style(
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
) %>%
tab_style(
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
) %>%
tab_style(
style = cell_text(size = px(32)),
locations = cells_body(columns = c(group, decimal))
) %>%
opt_all_caps() %>%
opt_stylize(style = 6) %>%
opt_align_table_header(align = "left") %>%
opt_table_lines(extent = "none") %>%
opt_horizontal_padding(scale = 2) %>%
opt_css(
css = "
#unit_conversion .gt_group_heading {
padding-top: 18px;
padding-bottom: 4px;
padding-left: 10px;
text-decoration: underline;
text-underline-offset: 2px;
}"
) %>%
tab_options(
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden",
container.height = px(620),
data_row.padding = "5px",
table.width = px(600)
)
}
# info_paletteer() -------------------------------------------------------------
#' View a table with info on color palettes
#'
#' @description
#'
#' While [data_color()] allows us to flexibly color data cells in our **gt**
#' table, the harder part of this process is discovering and choosing color
#' palettes that are suitable for the table output. We can make this process
#' much easier in two ways: (1) by using the **paletteer** package, which makes
#' a wide range of palettes from various R packages readily available, and (2)
#' calling `info_paletteer()` to give us an information table that serves as a
#' quick reference for all of the discrete color palettes available in
#' **paletteer**.
#'
#' @details
#'
#' The palettes displayed are organized by package and by palette name. These
#' values are required when obtaining a palette (as a vector of hexadecimal
#' colors), from `paletteer::paletteer_d()`. Once we are familiar with the names
#' of the color palette packages (e.g., **RColorBrewer**, **ggthemes**,
#' **wesanderson**), we can narrow down the content of this information table by
#' supplying a vector of such package names to `color_pkgs`.
#'
#' Colors from the following color packages (all supported by **paletteer**)
#' are shown by default with `info_paletteer()`:
#' \itemize{
#' \item **awtools**, 5 palettes
#' \item **dichromat**, 17 palettes
#' \item **dutchmasters**, 6 palettes
#' \item **ggpomological**, 2 palettes
#' \item **ggsci**, 42 palettes
#' \item **ggthemes**, 31 palettes
#' \item **ghibli**, 27 palettes
#' \item **grDevices**, 1 palette
#' \item **jcolors**, 13 palettes
#' \item **LaCroixColoR**, 21 palettes
#' \item **NineteenEightyR**, 12 palettes
#' \item **nord**, 16 palettes
#' \item **ochRe**, 16 palettes
#' \item **palettetown**, 389 palettes
#' \item **pals**, 8 palettes
#' \item **Polychrome**, 7 palettes
#' \item **quickpalette**, 17 palettes
#' \item **rcartocolor**, 34 palettes
#' \item **RColorBrewer**, 35 palettes
#' \item **Redmonder**, 41 palettes
#' \item **wesanderson**, 19 palettes
#' \item **yarrr**, 21 palettes
#' }
#'
#' @param color_pkgs *Filter to specific color packages*
#'
#' `vector<character>` // *default:* `NULL` (`optional`)
#'
#' A vector of color packages that determines which sets of palettes should be
#' displayed in the information table. If this is `NULL` (the default) then
#' all of the discrete palettes from all of the color packages represented in
#' **paletteer** will be displayed.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on just the `"ggthemes"` color palette (easily accessible
#' from the **paletteer** package).
#'
#' ```r
#' info_paletteer(color_pkgs = "ggthemes")
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_paletteer_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-5
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_paletteer <- function(color_pkgs = NULL) {
if (is.null(color_pkgs)) {
return(readRDS(system_file("gt_tables/info_paletteer.rds")))
}
palettes_strips_df <-
dplyr::filter(palettes_strips, package %in% color_pkgs)
palettes_strips <- palettes_strips_df$colors
palettes_strips_df %>%
dplyr::select("package", "palette", "length") %>%
dplyr::mutate(`Color Count and Palette` = NA) %>%
gt(groupname_col = "package", rowname_col = "palette") %>%
text_transform(
locations = cells_body("Color Count and Palette"),
fn = function(x) {
palettes_strips
}
) %>%
cols_label(length = "") %>%
tab_stubhead(label = "Package and Palette Name") %>%
tab_header(
title = md("Palettes Made Easily Available with **paletteer**"),
subtitle = md("Palettes like these are useful with the `data_color()` function")
) %>%
tab_style(
style = cell_text(align = "left"),
locations = list(
cells_title(groups = "title"),
cells_title(groups = "subtitle")
)
) %>%
tab_style(
style = list(
cell_fill(color = "#E3E3E3"),
cell_text(font = "Courier", size = "smaller", weight = "bold")
),
locations = cells_stub(rows = TRUE)
) %>%
tab_style(
style = cell_text(font = "Courier"),
locations = cells_body(columns = "length")
) %>%
tab_options(
row_group.background.color = "#FFFFF0",
column_labels.background.color = "#666660",
row_group.font.weight = "600",
row_group.font.size = "smaller"
) %>%
tab_source_note(
source_note = md(
paste0(
"The **paletteer** package is maintained by Emil Hvitfeldt. More ",
"information can be found on [the **paletteer** site]",
"(https://emilhvitfeldt.github.io/paletteer/) and on the ",
"[**CRAN** info page]",
"(https://cran.r-project.org/web/packages/paletteer/index.html)."
)
)
)
}
# info_google_fonts() ----------------------------------------------------------
#' View a table on recommended Google Fonts
#'
#' @description
#'
#' The [google_font()] helper function can be used wherever a font name should
#' be specified. There are two instances where this helper can be used: the
#' `name` argument in [opt_table_font()] (for setting a table font) and in that
#' of [cell_text()] (used with [tab_style()]). Because there is an overwhelming
#' number of fonts available in the *Google Fonts* catalog, the
#' `info_google_fonts()` provides a table with a set of helpful font
#' recommendations. These fonts look great in the different parts of a **gt**
#' table. Why? For the most part they are suitable for body text, having large
#' counters, large x-height, reasonably low contrast, and open apertures. These
#' font features all make for high legibility at smaller sizes.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on some of the recommended *Google Fonts* for tables.
#'
#' ```r
#' info_google_fonts()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_google_fonts_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-6
#'
#' @section Function Introduced:
#' `v0.2.2` (August 5, 2020)
#'
#' @export
info_google_fonts <- function() {
readRDS(system_file("gt_tables/info_google_fonts.rds"))
}
# info_flags() -----------------------------------------------------------------
#' View a table with all available flags for `fmt_flag()`
#'
#' @description
#'
#' [fmt_flag()] can be used to render flag icons within body cells that have
#' 2-letter country codes. There are a lot of countries, so, calling
#' `info_flags()` can be helpful in showing all of the valid and supported
#' country codes along with their flag icons.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all the available flag icons.
#'
#' ```r
#' info_flags()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_flags_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-7
#'
#' @section Function Introduced:
#' `v0.10.0` (October 7, 2023)
#'
#' @export
info_flags <- function() {
readRDS(system_file("gt_tables/info_flags.rds"))
}
# info_icons() -----------------------------------------------------------------
#' View a table with all available Font Awesome icons for `fmt_icon()`
#'
#' @description
#'
#' [fmt_icon()] can be used to render *Font Awesome* icons within
#' body cells that reference the icon names. Further to this, the text
#' transformation functions (e.g., [text_case_match()]) allow for the insertion
#' of these icons as replacement text (so long as you use the `fa()` function
#' from the **fontawesome** package). Because there is a very large number of
#' icons available to use in *Font Awesome*, `info_icons()` can be used to
#' provide us with a table that lists all the icons along with their short and
#' full names (either can be used with [fmt_icon()]). It also contains
#' acceptable codes for [fmt_country()]
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all the available *Font Awesome* icons.
#'
#' ```r
#' info_icons()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_icons_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-8
#'
#' @section Function Introduced:
#' `v0.10.0` (October 7, 2023)
#'
#' @export
info_icons <- function() {
readRDS(system_file("gt_tables/info_icons.rds"))
}
# info_unit_conversions() ------------------------------------------------------
#' View a table with all units that can be converted by `unit_conversion()`
#'
#' @description
#'
#' [unit_conversion()] can be used to yield conversion factors across compatible
#' pairs of units. This is useful for expressing values in different units and
#' the conversion can be performed via the `scale_by` argument available in
#' several formatting functions. When calling [unit_conversion()], one must
#' supply two string-based keywords to specify the value's current units and the
#' desired units. All of these keywords are provided in the table shown by
#' calling `info_unit_conversions()`.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all the available keywords for unit conversions.
#'
#' ```r
#' info_unit_conversions()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_unit_conversions_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-9
#'
#' @section Function Introduced:
#' `v0.11.0` (July 9, 2024)
#'
#' @export
info_unit_conversions <- function() {
readRDS(system_file("gt_tables/info_conversions.rds"))
}
rstudio/gt documentation built on Nov. 2, 2024, 5:53 p.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.
Defines functions info_unit_conversions info_icons info_flags info_google_fonts info_paletteer info_locales info_currencies info_time_style info_date_style
Documented in info_currencies info_date_style info_flags info_google_fonts info_icons info_locales info_paletteer info_time_style info_unit_conversions
#------------------------------------------------------------------------------#
#
# /$$
# | $$
# /$$$$$$ /$$$$$$
# /$$__ $$|_ $$_/
# | $$ \ $$ | $$
# | $$ | $$ | $$ /$$
# | $$$$$$$ | $$$$/
# \____ $$ \___/
# /$$ \ $$
# | $$$$$$/
# \______/
#
# This file is part of the 'rstudio/gt' project.
#
# Copyright (c) 2018-2024 gt authors
#
# For full copyright and license information, please look at
# https://gt.rstudio.com/LICENSE.html
#
#------------------------------------------------------------------------------#
# info_date_style() ------------------------------------------------------------
#' View a table with info on date styles
#'
#' @description
#'
#' [fmt_date()] lets us format date-based values in a convenient manner using
#' preset styles. The table generated by `info_date_style()` provides a quick
#' reference to all styles, with associated format names and example outputs
#' using a fixed date (`2000-02-29`).
#'
#' @param locale *Locale identifier*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' An optional locale identifier that can be used for displaying formatted
#' date values according the locale's rules. Examples include `"en"` for
#' English (United States) and `"fr"` for French (France). We can call
#' [info_locales()] for a useful reference for all of the locales that are
#' supported.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on the different date-formatting styles (which are used
#' by supplying a number code to [fmt_date()]).
#'
#' ```r
#' info_date_style()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_date_style_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-1
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_date_style <- function(locale = NULL) {
if (is.null(locale)) {
locale <- "en"
}
date_df <- date_formats()
date_df$date <- "2000-02-29"
flexible_rows <- date_df[, "flexible"][["flexible"]]
date_df$flexible[flexible_rows] <- "FLEXIBLE"
date_df$flexible[!flexible_rows] <- ""
gt_tbl <- gt(date_df, rowname_col = "format_number", locale = locale)
gt_tbl <- cols_hide(gt_tbl, columns = format_code)
gt_tbl <-
fmt_date(
gt_tbl,
columns = date,
date_style = from_column(column = "format_name")
)
gt_tbl <-
text_transform(
gt_tbl,
locations = cells_body(
columns = flexible,
rows = flexible == "FLEXIBLE"
),
fn = function(x) {
paste0(
"<span style='",
"color: darkslategray; font-weight: 700; font-size: 12px; ",
"border: solid 1px; background: aliceblue; border-color: steelblue; ",
"border-width: 2px; border-radius: 4px; padding: 0px 8px 0px 8px;",
"'>", x, "</span>"
)
}
)
gt_tbl <-
cols_label(
gt_tbl,
format_name = "Format Name",
flexible = "",
date = html(
paste0(
"Formatted Date (<span style=\"text-transform:none;\">",
locale,
"</span>)"
)
)
)
gt_tbl <-
cols_width(
gt_tbl,
format_number ~ px(60),
format_name ~ px(220),
flexible ~ px(100),
date ~ px(315)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- cols_align(gt_tbl, align = "center", columns = flexible)
gt_tbl <- cols_align(gt_tbl, align = "left", columns = date)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
locations = cells_body(columns = format_name)
)
gt_tbl <-
tab_style(
gt_tbl,
style =
cell_borders(
sides = "r",
color = "lightblue",
weight = px(1.5)
),
locations = cells_body(columns = format_name)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden"
)
gt_tbl <-
tab_header(
gt_tbl,
title = "Date Formatting Options",
subtitle = md(
"Usable in the `fmt_date()` and `fmt_datetime()` functions.<br><br>"
)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.7)
gt_tbl
}
# info_time_style() ------------------------------------------------------------
#' View a table with info on time styles
#'
#' @description
#'
#' [fmt_time()] lets us format time-based values in a convenient manner using
#' preset styles. The table generated by `info_time_style()` provides a quick
#' reference to all styles, with associated format names and example outputs
#' using a fixed time (`14:35`).
#'
#' @param locale *Locale identifier*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' An optional locale identifier that can be used for displaying formatted
#' time values according the locale's rules. Examples include `"en"` for
#' English (United States) and `"fr"` for French (France). We can call
#' [info_locales()] for a useful reference for all of the locales that are
#' supported.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on the different time-formatting styles (which are used
#' by supplying a number code to `fmt_time()`).
#'
#' ```r
#' info_time_style()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_time_style_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-2
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_time_style <- function(locale = NULL) {
if (is.null(locale)) {
locale <- "en"
}
time_df <- time_formats()
time_df$time <- "14:35"
flexible_rows <- time_df[, "flexible"][["flexible"]]
time_df$flexible[flexible_rows] <- "FLEXIBLE"
time_df$flexible[!flexible_rows] <- ""
gt_tbl <- gt(time_df, rowname_col = "format_number", locale = locale)
gt_tbl <- cols_hide(gt_tbl, columns = format_code)
gt_tbl <-
fmt_time(
gt_tbl,
columns = time,
time_style = from_column(column = "format_name")
)
gt_tbl <-
text_transform(
gt_tbl,
locations = cells_body(
columns = flexible,
rows = flexible == "FLEXIBLE"
),
fn = function(x) {
paste0(
"<span style='",
"color: darkslategray; font-weight: 700; font-size: 12px; ",
"border: solid 1px; background: aliceblue; border-color: steelblue; ",
"border-width: 2px; border-radius: 4px; padding: 0px 8px 0px 8px;",
"'>", x, "</span>"
)
}
)
gt_tbl <-
cols_label(
gt_tbl,
format_name = "Format Name",
time_type = "12/24h",
flexible = "",
time = html(
paste0(
"Formatted Time (<span style=\"text-transform:none;\">",
locale,
"</span>)"
)
)
)
gt_tbl <-
cols_width(
gt_tbl,
format_number ~ px(60),
format_name ~ px(140),
time_type ~ px(80),
flexible ~ px(100),
time ~ px(315)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- sub_missing(gt_tbl, columns = time_type)
gt_tbl <-
cols_align(
gt_tbl,
align = "center",
columns = c(time_type, flexible)
)
gt_tbl <- cols_align(gt_tbl, align = "left", columns = time)
gt_tbl <- tab_style(
gt_tbl,
style = cell_text(size = "smaller"),
locations = cells_body(columns = time_type)
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
locations = cells_body(columns = format_name)
)
gt_tbl <-
tab_style(
gt_tbl,
style =
cell_borders(
sides = "r",
color = "lightblue",
weight = px(1.5)
),
locations = cells_body(columns = format_name)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden"
)
gt_tbl <-
tab_header(
gt_tbl,
title = "Time Formatting Options",
subtitle = md(
"Usable in the `fmt_time()` and `fmt_datetime()` functions.<br><br>"
)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.7)
gt_tbl
}
# info_currencies() ------------------------------------------------------------
#' View a table with info on supported currencies
#'
#' @description
#'
#' [fmt_currency()] lets us format numeric values as currencies. The table
#' generated by `info_currencies()` provides a quick reference to all the
#' available currencies. The currency identifiers are provided (name, 3-letter
#' currency code, and 3-digit currency code) along with the each currency's
#' exponent value (number of digits of the currency subunits). A formatted
#' example is provided (based on the value of `49.95`) to demonstrate the
#' default formatting of each currency.
#'
#' @details
#'
#' There are 172 currencies, which can lead to a verbose display table. To make
#' this presentation more focused on retrieval, we can provide an initial letter
#' corresponding to the 3-letter currency code to `begins_with`. This will
#' filter currencies in the info table to just the set beginning with the
#' supplied letter.
#'
#' @param type *Type of currency*
#'
#' `singl-kw:[code|symbol]` // *default:* `"code"`
#'
#' The type of currency information provided. Can either be `"code"` where
#' currency information corresponding to 3-letter/3-number currency codes is
#' provided, or `"symbol"` where currency info for common currency
#' names/symbols (e.g., dollar, pound, yen, etc.) is returned.
#'
#' @param begins_with *Show currencies beginning with a specific letter*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' Providing a single letter will filter currencies to only those that begin
#' with that letter in their currency code. The default (`NULL`) will produce
#' a table with all currencies displayed. This option only constrains the
#' information table where `type == "code"`.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all of the currencies where the three-letter code
#' begins with an `"h"`.
#'
#' ```r
#' info_currencies(begins_with = "h")
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_currencies_1.png")`
#' }}
#'
#' Get a table of info on all of the common currency name/symbols that can be
#' used with [fmt_currency()].
#'
#' ```r
#' info_currencies(type = "symbol")
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_currencies_2.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-3
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_currencies <- function(
type = c("code", "symbol"),
begins_with = NULL
) {
# Get the correct `type` value
type <- rlang::arg_match0(type, values = c("code", "symbol"))
if (type == "code") {
if (!is.null(begins_with)) {
starting <- toupper(substr(begins_with, 1, 1))
curr <-
dplyr::filter(currencies, grepl(paste0("^", starting, ".*"), curr_code))
} else {
curr <- currencies
}
curr_df <- curr[, c(4, 1, 2, 3)]
curr_df$value <- 49.95
gt_tbl <- gt(curr_df, id = "currencies")
gt_tbl <-
fmt_currency(
gt_tbl,
columns = "value",
currency = from_column(column = "curr_code")
)
gt_tbl <-
cols_label(
gt_tbl,
curr_name = md("Currency<br>Name"),
curr_code = md("Alpha<br>Code"),
curr_number = md("Numeric<br>Code"),
exponent = md("No. of<br>Subunits"),
value = md("Formatted<br>Currency"),
)
gt_tbl <-
cols_width(
gt_tbl,
curr_name ~ px(325),
curr_code ~ px(75),
curr_number ~ px(85),
exponent ~ px(85),
value ~ px(125)
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
locations = cells_body(columns = c(curr_code, curr_number))
)
gt_tbl <-
tab_header(
gt_tbl,
title = md("Currencies Supported in **gt**"),
subtitle = md(
"Currency codes are used in the `fmt_currency()` function<br><br>"
)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.8)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden",
container.height = px(620)
)
gt_tbl <-
tab_style(
gt_tbl,
style = css(position = "sticky", top = "-1em", `z-index` = 10),
locations = cells_column_labels()
)
} else {
curr_df <- currency_symbols
curr_df$symbol <- NULL
curr_df$value <- 49.95
gt_tbl <- gt(curr_df, id = "currency_symbols")
gt_tbl <-
fmt_currency(
gt_tbl,
columns = "value",
currency = from_column(column = "curr_symbol")
)
gt_tbl <-
cols_label(
gt_tbl,
curr_symbol = "Currency Symbol Keyword",
value = "Formatted Currency"
)
gt_tbl <-
cols_width(
gt_tbl,
curr_symbol ~ px(300),
value ~ px(300)
)
gt_tbl <-
tab_style(
gt_tbl,
style = list(
cell_text(
font = system_fonts(name = "monospace-code"),
size = px(12)
),
cell_borders(
sides = "r",
color = "lightblue",
weight = px(1.5))
),
locations = cells_body(columns = curr_symbol)
)
gt_tbl <- opt_all_caps(gt_tbl)
gt_tbl <- opt_stylize(gt_tbl, style = 6)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
)
gt_tbl <-
tab_style(
gt_tbl,
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
)
gt_tbl <-
tab_options(
gt_tbl,
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden"
)
gt_tbl <-
tab_header(
gt_tbl,
title = md("Currencies Supported in **gt**"),
subtitle = md(
"Currency symbols are used in the `fmt_currency()` function.<br><br>"
)
)
gt_tbl <- opt_align_table_header(gt_tbl, align = "left")
gt_tbl <- opt_table_lines(gt_tbl, extent = "none")
gt_tbl <- opt_horizontal_padding(gt_tbl, scale = 2)
gt_tbl <- opt_vertical_padding(gt_tbl, scale = 0.7)
}
gt_tbl
}
# info_locales() ------------------------------------------------------------
#' View a table with info on supported locales
#'
#' @description
#'
#' Many of the `fmt_*()` functions have a `locale` argument that makes
#' locale-based formatting easier. The table generated by the `info_locales()`
#' function provides a quick reference to all the available locales. The locale
#' identifiers are provided (base locale ID, common display name) along with the
#' each locale's group and decimal separator marks. A formatted numeric example
#' is provided (based on the value of `11027`) to demonstrate the default
#' formatting of each locale.
#'
#' @details
#'
#' There are `r nrow(locales)` locales, which means that a very long display
#' table is provided by default. To trim down the output table size, we can
#' provide an initial letter corresponding to the base locale ID to
#' `begins_with`. This will filter locales in the info table to just the set
#' that begins with the supplied letter.
#'
#' @param begins_with *Show locales beginning with a specific letter*
#'
#' `scalar<character>` // *default:* `NULL` (`optional`)
#'
#' Providing a single letter will filter locales to only those that begin
#' with that letter in their locale ID. The default (`NULL`) will produce
#' a table with all locales displayed
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all of the locales supported by **gt**.
#'
#' ```r
#' info_locales()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_locales_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-4
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_locales <- function(begins_with = NULL) {
locale <- lang_desc <- script_desc <- territory_desc <- NULL
variant_desc <- group <- decimal <- NULL
if (!is.null(begins_with)) {
starting <- tolower(substr(begins_with, 1, 1))
regex_starting <- paste0("^", starting, ".*")
loc <- vctrs::vec_slice(locales, grepl(regex_starting, locales$locale))
} else {
loc <- locales
}
tab_1 <-
dplyr::select(
loc, "locale", "lang_desc", "script_desc",
"territory_desc", "variant_desc", "group", "decimal"
)
tab_1$display_name <- paste0(
tab_1$lang_desc,
paste0(
" (",
tab_1$territory_desc, ", ",
tab_1$script_desc, ", ",
tab_1$variant_desc,
")"
)
)
tab_1$group <-
dplyr::case_match(
tab_1$group,
c("\u00a0", "\u202f") ~ "space",
.default = tab_1$group
)
tab_1 <- tab_1[c("locale", "display_name", "group", "decimal")]
tab_1$display_name <- gsub(" (NA, NA, NA)", "", tab_1$display_name, fixed = TRUE)
tab_1$display_name <- gsub(", NA, NA", "", tab_1$display_name, fixed = TRUE)
tab_1$display_name <- gsub("NA, ", "", tab_1$display_name, fixed = TRUE)
tab_1$display_name <- gsub(", NA)", ")", tab_1$display_name, fixed = TRUE)
tab_1$value <- 11027
gt(tab_1) %>%
tab_header(
title = md("Locales Supported in **gt**"),
subtitle = md("Locale codes are used in several `fmt_*()` functions.<br><br>")
) %>%
fmt_number(
columns = "value",
locale = from_column("locale")
) %>%
text_transform(
fn = function(x) sub("space", "\U02420", x),
locations = cells_body(columns = "group")
) %>%
cols_merge(
columns = c("locale", "display_name"),
pattern = "<code>{1}</code><br><span style=font-size:11px>{2}</span>"
) %>%
cols_label(
locale = "Locale",
group = "Group",
decimal = "Decimal",
value = html("Formatted<br>Value")
) %>%
cols_align(
align = "center",
columns = c("group", "decimal")
) %>%
tab_style(
style = css(position = "sticky", top = "-1em", `z-index` = 10),
locations = cells_column_labels()
) %>%
tab_style(
style = cell_text(size = px(24)),
locations = cells_title(groups = "title")
) %>%
tab_style(
style = cell_text(size = px(18)),
locations = cells_title(groups = "subtitle")
) %>%
tab_style(
style = cell_text(size = px(32)),
locations = cells_body(columns = c(group, decimal))
) %>%
opt_all_caps() %>%
opt_stylize(style = 6) %>%
opt_align_table_header(align = "left") %>%
opt_table_lines(extent = "none") %>%
opt_horizontal_padding(scale = 2) %>%
opt_css(
css = "
#unit_conversion .gt_group_heading {
padding-top: 18px;
padding-bottom: 4px;
padding-left: 10px;
text-decoration: underline;
text-underline-offset: 2px;
}"
) %>%
tab_options(
table.border.top.style = "hidden",
column_labels.border.bottom.style = "hidden",
container.height = px(620),
data_row.padding = "5px",
table.width = px(600)
)
}
# info_paletteer() -------------------------------------------------------------
#' View a table with info on color palettes
#'
#' @description
#'
#' While [data_color()] allows us to flexibly color data cells in our **gt**
#' table, the harder part of this process is discovering and choosing color
#' palettes that are suitable for the table output. We can make this process
#' much easier in two ways: (1) by using the **paletteer** package, which makes
#' a wide range of palettes from various R packages readily available, and (2)
#' calling `info_paletteer()` to give us an information table that serves as a
#' quick reference for all of the discrete color palettes available in
#' **paletteer**.
#'
#' @details
#'
#' The palettes displayed are organized by package and by palette name. These
#' values are required when obtaining a palette (as a vector of hexadecimal
#' colors), from `paletteer::paletteer_d()`. Once we are familiar with the names
#' of the color palette packages (e.g., **RColorBrewer**, **ggthemes**,
#' **wesanderson**), we can narrow down the content of this information table by
#' supplying a vector of such package names to `color_pkgs`.
#'
#' Colors from the following color packages (all supported by **paletteer**)
#' are shown by default with `info_paletteer()`:
#' \itemize{
#' \item **awtools**, 5 palettes
#' \item **dichromat**, 17 palettes
#' \item **dutchmasters**, 6 palettes
#' \item **ggpomological**, 2 palettes
#' \item **ggsci**, 42 palettes
#' \item **ggthemes**, 31 palettes
#' \item **ghibli**, 27 palettes
#' \item **grDevices**, 1 palette
#' \item **jcolors**, 13 palettes
#' \item **LaCroixColoR**, 21 palettes
#' \item **NineteenEightyR**, 12 palettes
#' \item **nord**, 16 palettes
#' \item **ochRe**, 16 palettes
#' \item **palettetown**, 389 palettes
#' \item **pals**, 8 palettes
#' \item **Polychrome**, 7 palettes
#' \item **quickpalette**, 17 palettes
#' \item **rcartocolor**, 34 palettes
#' \item **RColorBrewer**, 35 palettes
#' \item **Redmonder**, 41 palettes
#' \item **wesanderson**, 19 palettes
#' \item **yarrr**, 21 palettes
#' }
#'
#' @param color_pkgs *Filter to specific color packages*
#'
#' `vector<character>` // *default:* `NULL` (`optional`)
#'
#' A vector of color packages that determines which sets of palettes should be
#' displayed in the information table. If this is `NULL` (the default) then
#' all of the discrete palettes from all of the color packages represented in
#' **paletteer** will be displayed.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on just the `"ggthemes"` color palette (easily accessible
#' from the **paletteer** package).
#'
#' ```r
#' info_paletteer(color_pkgs = "ggthemes")
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_paletteer_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-5
#'
#' @section Function Introduced:
#' `v0.2.0.5` (March 31, 2020)
#'
#' @export
info_paletteer <- function(color_pkgs = NULL) {
if (is.null(color_pkgs)) {
return(readRDS(system_file("gt_tables/info_paletteer.rds")))
}
palettes_strips_df <-
dplyr::filter(palettes_strips, package %in% color_pkgs)
palettes_strips <- palettes_strips_df$colors
palettes_strips_df %>%
dplyr::select("package", "palette", "length") %>%
dplyr::mutate(`Color Count and Palette` = NA) %>%
gt(groupname_col = "package", rowname_col = "palette") %>%
text_transform(
locations = cells_body("Color Count and Palette"),
fn = function(x) {
palettes_strips
}
) %>%
cols_label(length = "") %>%
tab_stubhead(label = "Package and Palette Name") %>%
tab_header(
title = md("Palettes Made Easily Available with **paletteer**"),
subtitle = md("Palettes like these are useful with the `data_color()` function")
) %>%
tab_style(
style = cell_text(align = "left"),
locations = list(
cells_title(groups = "title"),
cells_title(groups = "subtitle")
)
) %>%
tab_style(
style = list(
cell_fill(color = "#E3E3E3"),
cell_text(font = "Courier", size = "smaller", weight = "bold")
),
locations = cells_stub(rows = TRUE)
) %>%
tab_style(
style = cell_text(font = "Courier"),
locations = cells_body(columns = "length")
) %>%
tab_options(
row_group.background.color = "#FFFFF0",
column_labels.background.color = "#666660",
row_group.font.weight = "600",
row_group.font.size = "smaller"
) %>%
tab_source_note(
source_note = md(
paste0(
"The **paletteer** package is maintained by Emil Hvitfeldt. More ",
"information can be found on [the **paletteer** site]",
"(https://emilhvitfeldt.github.io/paletteer/) and on the ",
"[**CRAN** info page]",
"(https://cran.r-project.org/web/packages/paletteer/index.html)."
)
)
)
}
# info_google_fonts() ----------------------------------------------------------
#' View a table on recommended Google Fonts
#'
#' @description
#'
#' The [google_font()] helper function can be used wherever a font name should
#' be specified. There are two instances where this helper can be used: the
#' `name` argument in [opt_table_font()] (for setting a table font) and in that
#' of [cell_text()] (used with [tab_style()]). Because there is an overwhelming
#' number of fonts available in the *Google Fonts* catalog, the
#' `info_google_fonts()` provides a table with a set of helpful font
#' recommendations. These fonts look great in the different parts of a **gt**
#' table. Why? For the most part they are suitable for body text, having large
#' counters, large x-height, reasonably low contrast, and open apertures. These
#' font features all make for high legibility at smaller sizes.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on some of the recommended *Google Fonts* for tables.
#'
#' ```r
#' info_google_fonts()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_google_fonts_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-6
#'
#' @section Function Introduced:
#' `v0.2.2` (August 5, 2020)
#'
#' @export
info_google_fonts <- function() {
readRDS(system_file("gt_tables/info_google_fonts.rds"))
}
# info_flags() -----------------------------------------------------------------
#' View a table with all available flags for `fmt_flag()`
#'
#' @description
#'
#' [fmt_flag()] can be used to render flag icons within body cells that have
#' 2-letter country codes. There are a lot of countries, so, calling
#' `info_flags()` can be helpful in showing all of the valid and supported
#' country codes along with their flag icons.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all the available flag icons.
#'
#' ```r
#' info_flags()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_flags_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-7
#'
#' @section Function Introduced:
#' `v0.10.0` (October 7, 2023)
#'
#' @export
info_flags <- function() {
readRDS(system_file("gt_tables/info_flags.rds"))
}
# info_icons() -----------------------------------------------------------------
#' View a table with all available Font Awesome icons for `fmt_icon()`
#'
#' @description
#'
#' [fmt_icon()] can be used to render *Font Awesome* icons within
#' body cells that reference the icon names. Further to this, the text
#' transformation functions (e.g., [text_case_match()]) allow for the insertion
#' of these icons as replacement text (so long as you use the `fa()` function
#' from the **fontawesome** package). Because there is a very large number of
#' icons available to use in *Font Awesome*, `info_icons()` can be used to
#' provide us with a table that lists all the icons along with their short and
#' full names (either can be used with [fmt_icon()]). It also contains
#' acceptable codes for [fmt_country()]
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all the available *Font Awesome* icons.
#'
#' ```r
#' info_icons()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_icons_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-8
#'
#' @section Function Introduced:
#' `v0.10.0` (October 7, 2023)
#'
#' @export
info_icons <- function() {
readRDS(system_file("gt_tables/info_icons.rds"))
}
# info_unit_conversions() ------------------------------------------------------
#' View a table with all units that can be converted by `unit_conversion()`
#'
#' @description
#'
#' [unit_conversion()] can be used to yield conversion factors across compatible
#' pairs of units. This is useful for expressing values in different units and
#' the conversion can be performed via the `scale_by` argument available in
#' several formatting functions. When calling [unit_conversion()], one must
#' supply two string-based keywords to specify the value's current units and the
#' desired units. All of these keywords are provided in the table shown by
#' calling `info_unit_conversions()`.
#'
#' @return An object of class `gt_tbl`.
#'
#' @section Examples:
#'
#' Get a table of info on all the available keywords for unit conversions.
#'
#' ```r
#' info_unit_conversions()
#' ```
#'
#' \if{html}{\out{
#' `r man_get_image_tag(file = "man_info_unit_conversions_1.png")`
#' }}
#'
#' @family information functions
#' @section Function ID:
#' 11-9
#'
#' @section Function Introduced:
#' `v0.11.0` (July 9, 2024)
#'
#' @export
info_unit_conversions <- function() {
readRDS(system_file("gt_tables/info_conversions.rds"))
}
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.