Save a Tiny Table to File

Description

This function saves an object of class tinytable to a specified file and format, with an option to overwrite existing files.

Usage

save_tt(
  x,
  output = get_option("tinytable_save_output", default = NULL),
  overwrite = get_option("tinytable_save_overwrite", default = FALSE)
)

Arguments

x The tinytable object to be saved.
output

String or file path.

  • If output is "markdown", "latex", "html", "html_portable", "typst", or "tabulator", the table is returned in a string as an R object.

  • If output is a valid file path, the table is saved to file. The supported extensions are: .docx, .html, .png, .pdf, .tex, .typ, and .md (with aliases .txt, .Rmd and .qmd).

  • If output is "html_portable" or the global option tinytable_html_portable is TRUE, the images are included in the HTML as base64 encoded string instead of link to a local file.
overwrite A logical value indicating whether to overwrite an existing file.

Value

A string with the table when output is a format, and the file path when output is a valid path.

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}}

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.

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

  • tinytable_html_engine: Default HTML engine (default: "bootstrap"). Set to "tabulator" to use interactive tables by default in HTML documents instead of static Bootstrap tables.

PDF

  • tinytable_pdf_clean: Delete temporary and log files

  • tinytable_pdf_engine: Choose between "xelatex", "pdflatex", "lualatex"

Color processing

  • 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:

  1. The LaTeX macro may not process references and markdown as expected

  2. 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]

fn <- file.path(tempdir(), "test.html")
tt(x) |> save_tt(fn, overwrite = TRUE)

library(tinytable)
filename <- file.path(tempdir(), "table.tex")
tt(mtcars[1:4, 1:4]) |> save_tt(filename)