format_tt – tinytable

Format columns of a data frame

Description

This function formats the columns of a data frame based on the column type (logical, date, numeric). It allows various formatting options like significant digits, decimal points, and scientific notation. It also includes custom formatting for date and boolean values. If this function is applied several times to the same cell, the last transformation is retained and the previous calls are ignored, except for the escape argument which can be applied to previously transformed data.

Usage

format_tt(
  x,
  i = NULL,
  j = NULL,
  digits = get_option("tinytable_format_digits", default = NULL),
  num_fmt = get_option("tinytable_format_num_fmt", default = "significant"),
  num_zero = get_option("tinytable_format_num_zero", default = FALSE),
  num_suffix = get_option("tinytable_format_num_suffix", default = FALSE),
  num_mark_big = get_option("tinytable_format_num_mark_big", default = ""),
  num_mark_dec = get_option("tinytable_format_num_mark_dec", default =
    getOption("OutDec", default = ".")),
  date = get_option("tinytable_format_date", default = NULL),
  bool = get_option("tinytable_format_bool", default = NULL),
  math = get_option("tinytable_format_math", default = FALSE),
  other = get_option("tinytable_format_other", default = NULL),
  replace = get_option("tinytable_format_replace", default = FALSE),
  escape = get_option("tinytable_format_escape", default = FALSE),
  markdown = get_option("tinytable_format_markdown", default = FALSE),
  quarto = get_option("tinytable_format_quarto", default = FALSE),
  fn = get_option("tinytable_format_fn", default = NULL),
  sprintf = get_option("tinytable_format_sprintf", default = NULL),
  linebreak = get_option("tinytable_format_linebreak", default = NULL),
  output = get_option("tinytable_format_output", default = NULL)
)

tt_format(
  x,
  i = NULL,
  j = NULL,
  digits = get_option("tinytable_format_digits", default = NULL),
  num_fmt = get_option("tinytable_format_num_fmt", default = "significant"),
  num_zero = get_option("tinytable_format_num_zero", default = FALSE),
  num_suffix = get_option("tinytable_format_num_suffix", default = FALSE),
  num_mark_big = get_option("tinytable_format_num_mark_big", default = ""),
  num_mark_dec = get_option("tinytable_format_num_mark_dec", default =
    getOption("OutDec", default = ".")),
  date = get_option("tinytable_format_date", default = NULL),
  bool = get_option("tinytable_format_bool", default = NULL),
  math = get_option("tinytable_format_math", default = FALSE),
  other = get_option("tinytable_format_other", default = NULL),
  replace = get_option("tinytable_format_replace", default = FALSE),
  escape = get_option("tinytable_format_escape", default = FALSE),
  markdown = get_option("tinytable_format_markdown", default = FALSE),
  quarto = get_option("tinytable_format_quarto", default = FALSE),
  fn = get_option("tinytable_format_fn", default = NULL),
  sprintf = get_option("tinytable_format_sprintf", default = NULL),
  linebreak = get_option("tinytable_format_linebreak", default = NULL),
  output = get_option("tinytable_format_output", default = NULL)
)

Arguments

x A data frame or a vector to be formatted.

i

Numeric vector or string.

Numeric vector: Row indices where the styling should be applied. Can be a single value or a vector.
String: Table components to format "caption", "colnames", "groupi" (row group labels), "~groupi" (non-group rows), "groupj" (column group labels), "notes".
If both the i and j are omitted (default: NULL), formatting is applied to all table elements, including caption, notes, and group labels.

j

Column indices where the styling should be applied. Can be:

Integer vectors indicating column positions.
Character vector indicating column names.
A single string specifying a Perl-style regular expression used to match column names.
Unquoted expression: Non-standard evaluation is supported. When supplying an unquoted expression, it is first evaluated in the calling environment, then in an environment that includes the columns of the original data passed to tt(), and groupi indices. See examples below.

digits Number of significant digits or decimal places.

num_fmt The format for numeric values; one of ‘significant’, ‘significant_cell’, ‘decimal’, or ‘scientific’.

num_zero Logical; if TRUE, trailing zeros are kept in "decimal" format (but not in "significant" format).

num_suffix Logical; if TRUE display short numbers with digits significant digits and K (thousands), M (millions), B (billions), or T (trillions) suffixes.

num_mark_big Character to use as a thousands separator.

num_mark_dec Decimal mark character. Default is the global option ‘OutDec’.

date A string passed to the format() function, such as "%Y-%m-%d". See the "Details" section in ?strptime

bool A function to format logical columns. Defaults to title case.

math Logical. If TRUE, wrap cell values in math mode $..$ . This is useful for LaTeX output or with HTML MathJax options(tinytable_html_mathjax=TRUE).

other A function to format columns of other types. Defaults to as.character().

replace

Logical, String or Named list of vectors

TRUE: Replace NA and NaN by an empty string.
FALSE: Print NA and NaN as strings.
String: Replace NA and NaN entries by the user-supplied string.
Named list: Replace matching elements of the vectors in the list by theirs names. Example:
- list(“-” = c(NA, NaN), “Tiny” = -Inf, “Massive” = Inf)

escape

Logical or "latex" or "html". If TRUE, escape special characters to display them as text in the format of the output of a tt() table.

If i and j are both NULL, escape all cells, column names, caption, notes, and spanning labels created by group_tt().

markdown Logical; if TRUE, render markdown syntax in cells. Ex: italicized text is properly italicized in HTML and LaTeX.

quarto Logical. Enable Quarto data processing and wrap cell content in a data-qmd span (HTML) or macro (LaTeX). See warnings in the Global Options section below.

fn Function for custom formatting. Accepts a vector and returns a character vector of the same length.

sprintf String passed to the ?sprintf function to format numbers or interpolate strings with a user-defined pattern (similar to the glue package, but using Base R).

linebreak NULL or a single string. If it is a string, replaces that string with appropriate line break sequences depending on the output format (HTML: <br>, LaTeX: \\, Typst: \ ). Markdown output is excluded from line break replacement.

output Apply formatting only if the tt() object is rendered in the specified format. One of "latex", "html", "typst", or "markdown". If NULL (default), apply formatting regardless of the output format.

Value

A data frame with formatted columns.

Global options

Options can be set with options() and change the default behavior of tinytable. For example:

options(tinytable_tt_digits = 4)
tt(head(iris))

You can set options in a script or via .Rprofile. Note: be cautious with .Rprofile settings as they may affect reproducibility.

Default values for function arguments

Nearly all of the package’s functions retrieve their default values from global options. This allows you to set defaults once and apply them to all tables without needing to specify them each time. For example, to fix the the digits argument of the tt() function globally, call:

options(tinytable_tt_digits = 4)

In addition, some more specific options are available to control the behavior of the package in specific contexts.

tinytable_html_mathjax: Insert MathJax scripts (warning: may conflict if MathJax is loaded elsewhere)
tinytable_pdf_clean: Delete temporary and log files for pdf output in save_tt()
tinytable_color_name_normalization: Enable/disable automatic color name processing (default: TRUE). When enabled, R color names recognized by col2rgb() are converted to hex format for consistent rendering across HTML, LaTeX, and Typst formats. If R color conversion fails, LaTeX color names are used as fallback. Colors explicitly supplied as hex values with "#" prefix are passed through unchanged. Set to FALSE to disable processing and pass color names unchanged.

Quarto

The format_tt(quarto=TRUE) argument enables Quarto data processing with some limitations:

The LaTeX macro may not process references and markdown as expected
Quarto processing may conflict with tinytable styling/formatting

Options:

tinytable_quarto_disable_processing: Disable Quarto cell processing

Example of Quarto-specific code in cells:

x <- data.frame(Math = "x^2^", Citation = "@Lovelace1842")
fn <- function(z) sprintf("<span data-qmd='%s'></span>", z)
tt(x) |> format_tt(i = 1, fn = fn)

For more details on Quarto table processing: https://quarto.org/docs/authoring/tables.html#disabling-quarto-table-processing

Examples

library("tinytable")

dat <- data.frame(
  a = rnorm(3, mean = 10000),
  b = rnorm(3, 10000)
)
tab <- tt(dat)
format_tt(tab,
  digits = 2,
  num_mark_dec = ",",
  num_mark_big = " "
)

a	b
9 999	10 000
9 999	10 001
10 000	9 999

k <- tt(data.frame(x = c(0.000123456789, 12.4356789)))
format_tt(k, digits = 2, num_fmt = "significant_cell")

x
0.00012
12

dat <- data.frame(
  a = c("Burger", "Halloumi", "Tofu", "Beans"),
  b = c(1.43202, 201.399, 0.146188, 0.0031),
  c = c(98938272783457, 7288839482, 29111727, 93945)
)
tt(dat) |>
  format_tt(j = "a", sprintf = "Food: %s") |>
  format_tt(j = 2, digits = 1, num_fmt = "decimal", num_zero = TRUE) |>
  format_tt(j = "c", digits = 2, num_suffix = TRUE)

a	b	c
Food: Burger	1.4	99T
Food: Halloumi	201.4	7.3B
Food: Tofu	0.1	29M
Food: Beans	0.0	94K

y <- tt(data.frame(x = c(123456789.678, 12435.6789)))
format_tt(y, digits = 3, num_mark_big = " ")

x
123 456 790
12 436

x <- tt(data.frame(Text = c("_italicized text_", "__bold text__")))
format_tt(x, markdown = TRUE)

Text
italicized text
bold text

# Line breaks using linebreak argument
d <- data.frame(Text = "First line<br>Second line")
tt(d) |> format_tt(linebreak = "<br>")

Text
First line Second line

# Non-standard evaluation (NSE)
dat <- data.frame(
  w = c(143002.2092, 201399.181, 100188.3883),
  x = c(1.43402, 201.399, 0.134588),
  y = as.Date(c(897, 232, 198), origin = "1970-01-01"),
  z = c(TRUE, TRUE, FALSE)
)
tt(dat) |>
  format_tt(i = w > 150000, j = w, digits = 0, num_mark_big = ",")

w	x	y	z
143002.2	1.434020	1972-06-16	TRUE
201399.2	201.399000	1970-08-21	TRUE
100188.4	0.134588	1970-07-18	FALSE

tab <- data.frame(a = c(NA, 1, 2), b = c(3, NA, 5))
tt(tab) |> format_tt(replace = "-")

a	b
-	3
1	-
2	5

dat <- data.frame(
  "LaTeX" = c("Dollars $", "Percent %", "Underscore _"),
  "HTML" = c("<br>", "<sup>4</sup>", "<emph>blah</emph>")
)
tt(dat) |> format_tt(escape = TRUE)

LaTeX	HTML
Dollars $	<br>
Percent %	<sup>4</sup>
Underscore _	<emph>blah</emph>