tt – tinytable

Draw a Tiny Table

Description

The tt function renders a table in different formats with various styling options: HTML, Markdown, LaTeX, Word, PDF, PNG, or Typst. The table can be customized with additional functions:

style_tt(): style fonts, colors, alignment, etc.
format_tt(): format numbers, dates, strings, etc.
group_tt(): row or column group labels.
theme_tt(): apply a collection of transformations to a tinytable.
save_tt(): save the table to a file or return the table as a string.
print(): print to a specific format, ex: print(x, “latex”)

tinytable attempts to determine the appropriate way to print the table based on interactive use, RStudio availability, and output format in RMarkdown or Quarto documents. Users can call print(x, output=“markdown”) to print the table in a specific format. Alternatively, they can set a global option: options(“tinytable_print_output”=“markdown”)

Usage

tt(
  x,
  digits = get_option("tinytable_tt_digits", default = NULL),
  caption = get_option("tinytable_tt_caption", default = NULL),
  notes = get_option("tinytable_tt_notes", default = NULL),
  width = get_option("tinytable_tt_width", default = NULL),
  theme = get_option("tinytable_tt_theme", default = "default"),
  rownames = get_option("tinytable_tt_rownames", default = FALSE),
  escape = get_option("tinytable_tt_escape", default = FALSE),
  ...
)

Arguments

`x`	A data frame or data table to be rendered as a table.
`digits`	Number of significant digits to keep for numeric variables. When `digits` is an integer, `tt()` calls `format_tt(x, digits = digits)` before proceeding to draw the table. Note that this will apply all default argument values of `format_tt()`, such as replacing `NA` by "". Users who need more control can use the `format_tt()` function instead.
`caption`	A string that will be used as the caption of the table. This argument should not be used in Quarto or Rmarkdown documents. In that context, please use the appropriate chunk options.
`notes`	Notes to append to the bottom of the table. This argument accepts several different inputs: Single string insert a single note: `“blah blah”` Multiple strings insert multiple notes sequentially: `list(“Hello world”, “Foo bar”)` A named list inserts a list with the name as superscript: `list(“a” = list(“Hello World”))` A named list with positions inserts markers as superscripts inside table cells: `list(“a” = list(i = 0:1, j = 2, text = “Hello World”))`
`width`	Table or column width. Single numeric value smaller than or equal to 1 determines the full table width, in proportion of line width. Numeric vector of length equal to the number of columns in `x` determines the width of each column, in proportion of line width. If the sum of `width` exceeds 1, each element is divided by `sum(width)`. This makes the table full-width with relative column sizes.
`theme`	Function or string. String: bootstrap, grid, multipage, placement, revealjs, resize, rotate, spacing, striped, tabular, void Function: Applied to the `tinytable` object.
`rownames`	Logical. If `TRUE`, rownames are included as the first column
`escape`	Logical. If `TRUE`, escape special characters in the table. Equivalent to `format_tt(tt(x), escape = TRUE)`.
`…`	Additional arguments are ignored

Value

An object of class tt representing the table.

The table object has S4 slots which hold information about the structure of the table. Relying on or modifying the contents of these slots is strongly discouraged. Their names and contents could change at any time, and the tinytable developers do not consider changes to the internal structure of the output object to be a "breaking change" for versioning or changelog purposes.

Dependencies

.pdf output requires a full LaTeX installation on the local computer.
.png output requires the webshot2 package.
.html self-contained files require the base64enc package.

LaTeX preamble

tinytable uses the tabularray package from your LaTeX distribution to draw tables. tabularray, in turn, uses the special tblr, talltblr, and longtblr environments.

When rendering a document from Quarto or Rmarkdown directly to PDF, tinytable will populate the LaTeX preamble automatically with all the required packages. For standalone LaTeX documents, these commands should be inserted in the preamble manually:

Note: Your document will fail to compile to PDF in Quarto if you enable caching and you use tinytable due to missing LaTeX headers. To avoid this problem, set the option #| cache: false for the chunk(s) where you use tinytable.

\usepackage{tabularray}
\usepackage{float}
\usepackage{graphicx}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\UseTblrLibrary{booktabs}
\UseTblrLibrary{siunitx}
\newcommand{\tinytableTabularrayUnderline}[1]{\underline{#1}}
\newcommand{\tinytableTabularrayStrikeout}[1]{\sout{#1}}
\NewTableCommand{\tinytableDefineColor}[3]{\definecolor{#1}{#2}{#3}}

Word and Markdown limitations

Markdown and Word tables only support these styles: italic, bold, strikeout. The width argument is also unavailable Moreover, the style_tt() function cannot be used to style headers inserted by the group_tt() function; instead, you should style the headers directly in the header definition using markdown syntax: group_tt(i = list(“italic header” = 2)). These limitations are due to the fact that there is no markdown syntax for the other options, and that we create Word documents by converting a markdown table to .docx via the Pandoc software.

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

tt()

tinytable_tt_digits
tinytable_tt_caption
tinytable_tt_notes
tinytable_tt_width
tinytable_tt_theme
tinytable_tt_rownames

format_tt()

tinytable_format_digits
tinytable_format_num_fmt
tinytable_format_num_zero
tinytable_format_num_suffix
tinytable_format_num_mark_big
tinytable_format_num_mark_dec
tinytable_format_date
tinytable_format_bool
tinytable_format_other
tinytable_format_replace
tinytable_format_escape
tinytable_format_markdown
tinytable_format_quarto
tinytable_format_fn
tinytable_format_sprintf

save_tt()

tinytable_save_overwrite

theme_tt()

Placement:

tinytable_theme_placement_float
tinytable_theme_placement_horizontal

Resize:

tinytable_theme_resize_width
tinytable_theme_resize_direction

Multipage:

tinytable_theme_multipage_rowhead
tinytable_theme_multipage_rowfoot

Tabular:

tinytable_theme_tabular_style

print.tinytable()

tinytable_print_output

Output-specific options

HTML

tinytable_html_mathjax: Insert MathJax scripts (warning: may conflict if MathJax is loaded elsewhere)
tinytable_html_portable: Insert base64 encoded images directly in HTML for plot_tt()

PDF

tinytable_pdf_clean: Delete temporary and log files
tinytable_pdf_engine: Choose between "xelatex", "pdflatex", "lualatex"

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
tinytable_print_rstudio_notebook: Display tables "inline" or in "viewer" for RStudio notebooks
tinytable_quarto_figure: Control Typst figure environment in Quarto

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")

library(tinytable)
x <- mtcars[1:4, 1:5]

tt(x)

mpg	cyl	disp	hp	drat
21.0	6	160	110	3.90
21.0	6	160	110	3.90
22.8	4	108	93	3.85
21.4	6	258	110	3.08

tt(x,
  theme = "striped",
  width = 0.5,
  caption = "Data about cars.")

Data about cars.
mpg	cyl	disp	hp	drat
21.0	6	160	110	3.90
21.0	6	160	110	3.90
22.8	4	108	93	3.85
21.4	6	258	110	3.08

tt(x, notes = "Hello World!")

mpg	cyl	disp	hp	drat
Hello World!
21.0	6	160	110	3.90
21.0	6	160	110	3.90
22.8	4	108	93	3.85
21.4	6	258	110	3.08

fn <- list(i = 0:1, j = 2, text = "Hello World!")
tab <- tt(x, notes = list("*" = fn))
print(tab, "latex")

\begin{table}
\centering
\begin{talltblr}[         %% tabularray outer open
entry=none,label=none,
note{*}={Hello World!},
]                     %% tabularray outer close
{                     %% tabularray inner open
colspec={Q[]Q[]Q[]Q[]Q[]},
}                     %% tabularray inner close
\toprule
mpg & cyl\textsuperscript{*} & disp & hp & drat \\ \midrule %% TinyTableHeader
21.0 & 6\textsuperscript{*} & 160 & 110 & 3.90 \\
21.0 & 6 & 160 & 110 & 3.90 \\
22.8 & 4 & 108 & 93 & 3.85 \\
21.4 & 6 & 258 & 110 & 3.08 \\
\bottomrule
\end{talltblr}
\end{table}

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

x
0.00012
12.43568