Format numeric values

With numeric values in a gt table, we can perform number-based formatting so that the targeted values are rendered with a higher consideration for tabular presentation. Furthermore, there is finer control over numeric formatting with the following options:

decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol
digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol
scaling: we can choose to scale targeted values by a multiplier value
large-number suffixing: larger figures (thousands, millions, etc.) can be autoscaled and decorated with the appropriate suffixes
pattern: option to use a text pattern for decoration of the formatted values
locale-based formatting: providing a locale ID will result in number formatting specific to the chosen locale

fmt_number(
  data,
  columns,
  rows = NULL,
  decimals = 2,
  n_sigfig = NULL,
  drop_trailing_zeros = FALSE,
  drop_trailing_dec_mark = TRUE,
  use_seps = TRUE,
  scale_by = 1,
  suffixing = FALSE,
  pattern = "{x}",
  sep_mark = ",",
  dec_mark = ".",
  locale = NULL
)

Arguments

data	A table object that is created using the `gt()` function.
columns	The columns to format. Can either be a series of column names provided in `vars()`, a vector of column indices, or a helper function focused on selections. The select helper functions are: `starts_with()`, `ends_with()`, `contains()`, `matches()`, `one_of()`, and `everything()`.
rows	Optional rows to format. Not providing any value results in all rows in `columns` being formatted. Can either be a vector of row captions provided `c()`, a vector of row indices, or a helper function focused on selections. The select helper functions are: `starts_with()`, `ends_with()`, `contains()`, `matches()`, `one_of()`, and `everything()`. We can also use expressions to filter down to the rows we need (e.g., `[colname_1] > 100 & [colname_2] < 50`).
decimals	An option to specify the exact number of decimal places to use. The default number of decimal places is `2`.
n_sigfig	A option to format numbers to n significant figures. By default, this is `NULL` and thus number values will be formatted according to the number of decimal places set via `decimals`. If opting to format according to the rules of significant figures, `n_sigfig` must be a number greater than or equal to `1`. Any values passed to the `decimals` and `drop_trailing_zeros` arguments will be ignored.
drop_trailing_zeros	A logical value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).
drop_trailing_dec_mark	A logical value that determines whether decimal marks should always appear even if there are no decimal digits to display after formatting (e.g, `23` becomes `23.`). The default for this is `TRUE`, which means that trailing decimal marks are not shown.
use_seps	An option to use digit group separators. The type of digit group separator is set by `sep_mark` and overridden if a locale ID is provided to `locale`. This setting is `TRUE` by default.
scale_by	A value to scale the input. The default is `1.0`. All numeric values will be multiplied by this value first before undergoing formatting. This value will be ignored if using any of the `suffixing` options (i.e., where `suffixing` is not set to `FALSE`).
suffixing	An option to scale and apply suffixes to larger numbers (e.g., `1924000` can be transformed to `1.92M`). This option can accept a logical value, where `FALSE` (the default) will not perform this transformation and `TRUE` will apply thousands (`K`), millions (`M`), billions (`B`), and trillions (`T`) suffixes after automatic value scaling. We can also specify which symbols to use for each of the value ranges by using a character vector of the preferred symbols to replace the defaults (e.g., `c("k", "Ml", "Bn", "Tr")`). Including `NA` values in the vector will ensure that the particular range will either not be included in the transformation (e.g, `c(NA, "M", "B", "T")` won't modify numbers in the thousands range) or the range will inherit a previous suffix (e.g., with `c("K", "M", NA, "T")`, all numbers in the range of millions and billions will be in terms of millions). Any use of `suffixing` (where it is not set expressly as `FALSE`) means that any value provided to `scale_by` will be ignored.
pattern	A formatting pattern that allows for decoration of the formatted value. The value itself is represented by `{x}` and all other characters are taken to be string literals.
sep_mark	The mark to use as a separator between groups of digits (e.g., using `sep_mark = ","` with `1000` would result in a formatted value of `1,000`).
dec_mark	The character to use as a decimal mark (e.g., using `dec_mark = ","` with `0.152` would result in a formatted value of `0,152`).
locale	An optional locale ID that can be used for formatting the value according the locale's rules. Examples include `"en_US"` for English (United States) and `"fr_FR"` for French (France). The use of a valid locale ID will override any values provided in `sep_mark` and `dec_mark`. We can use the `info_locales()` function as a useful reference for all of the locales that are supported.

Value

An object of class gt_tbl.

Details

Targeting of values is done through columns and additionally by rows (if nothing is provided for rows then entire columns are selected). A number of helper functions exist to make targeting more effective. Conditional formatting is possible by providing a conditional expression to the rows argument. See the Arguments section for more information on this.

Figures

Function ID

3-1

Examples