tt {tinytable} | R Documentation |
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 atinytable.
-
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 |
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:
|
width |
Table or column width.
|
theme |
Function or string.
|
rownames |
Logical. If |
escape |
Logical. If |
... |
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. For example, the table@group_index_i
slot includes the row indices for grouping labels added by group_tt()
.
Warning: 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 thewebshot2
package. -
.html
self-contained files require thebase64enc
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 forplot_tt()
-
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
\QuartoMarkdownBase64{}
LaTeX macro may not process references and markdown as expectedQuarto 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)
x <- mtcars[1:4, 1:5]
tt(x)
tt(x,
theme = "striped",
width = 0.5,
caption = "Data about cars.")
tt(x, notes = "Hello World!")
fn <- list(i = 0:1, j = 2, text = "Hello World!")
tab <- tt(x, notes = list("*" = fn))
print(tab, "latex")
k <- data.frame(x = c(0.000123456789, 12.4356789))
tt(k, digits = 2)