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 = NULL),
  rownames = get_option("tinytable_tt_rownames", 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: grid, resize, multipage, placement, striped, void, bootstrap, tabular

  • Function: Applied to the tinytable object.
rownames Logical. If TRUE, rownames are included as the first column
… 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. This meta-data can be accessed with the usual @ accessor. In general, modifying the content of these slots is not recommended, but it can be useful to some developers, such as those who want to force print to a specific output format without calling print().

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 (except when code chunks are cached). For standalone LaTeX documents, these commands should be inserted in the preamble manually:

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

Global options

Quarto data processing

The format_tt(quarto=TRUE) argument activates Quarto data processing for specific cells. This funcationality comes with a few warnings:

  1. Currently, Quarto provides a LaTeX macro, but it does not appear to do anything with it. References and markdown codes may not be processed as expected in LaTeX.

  2. Quarto data processing can enter in conflict with tinytable styling or formatting options. See below for how to disable it.

options(tinytable_quarto_disable_processing = TRUE)

Disable Quarto processing of cell content. Setting this global option to FALSE may lead to conflicts with some tinytable features, but it also allows use of markdown and Quarto-specific code in table cells, such as cross-references.

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)

See this link for more details: https://quarto.org/docs/authoring/tables.html#disabling-quarto-table-processing

HTML

  • EXPERIMENTAL options(tinytable_html_mathjax = TRUE) inserts MathJax scripts in the HTML document. Warning: This may conflict with other elements of the page if MathJax is otherwise loaded.

PDF

  • options(tinytable_pdf_clean = TRUE) deletes temporary and log files.

  • options(tinytable_pdf_engine = “xelatex”): "xelatex", "pdflatex", "lualatex"

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