Package 'tinytable'

Description

Create highly customized tables with this simple and dependency-free package. Data frames can be converted to 'HTML', 'LaTeX', 'Markdown', 'Word', 'PNG', 'PDF', or 'Typst' tables. The user interface is minimalist and easy to learn. The syntax is concise. 'HTML' tables can be customized using the flexible 'Bootstrap' framework, and 'LaTeX' code with the 'tabularray' package.

Package Content

Index of help topics:

format_tt               Format columns of a data frame
group_tt                Spanning labels to identify groups of rows or
                        columns
plot_tt                 Insert images and inline plots into tinytable
                        objects
print.tinytable         Print, display, or convert a tinytable object
rbind2,tinytable,tinytable-method
                        Combine 'tinytable' objects by rows
                        (vertically)
save_tt                 Save a Tiny Table to File
style_tt                Style a Tiny Table
theme_tt                Themes for 'tinytable'
tinytable-package       Simple and Configurable Tables in 'HTML',
                        'LaTeX', 'Markdown', 'Word', 'PNG', 'PDF', and
                        'Typst' Formats
tt                      Draw a Tiny Table

Maintainer

Vincent Arel-Bundock <[email protected]>

Author(s)

Vincent Arel-Bundock [aut, cre] (<https://orcid.org/0000-0003-2042-7063>)

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 = "%Y-%m-%d"),
  bool = get_option("tinytable_format_bool", default = function(column)
    tools::toTitleCase(tolower(column))),
  math = get_option("tinytable_format_math", default = FALSE),
  other = get_option("tinytable_format_other", default = as.character),
  replace = get_option("tinytable_format_replace", default = TRUE),
  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),
  ...
)

Arguments

Value

A data frame with formatted columns.

Global options

Quarto

Figure environment

• options("tinytable_quarto_figure" = FALSE): Typst only. Normally, it is best to allow Quarto to define the figure environment, so the default behavior is to not include one.

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 ⁠\QuartoMarkdownBase64{}⁠ 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

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

• options(tinytable_html_portable = TRUE): plot_tt() inserts base 64 encoded images directly in the HTML file rather than use external links.

PDF

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

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

Examples

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 = " ")
 
k <- tt(data.frame(x = c(0.000123456789, 12.4356789)))
format_tt(k, digits = 2, num_fmt = "significant_cell")
 
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)
 
y <- tt(data.frame(x = c(123456789.678, 12435.6789)))
format_tt(y, digits=3, num_mark_big=" ")

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

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

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

Description

Spanning labels to identify groups of rows or columns

Usage

group_tt(x, i = NULL, j = NULL, indent = 1, ...)

Arguments

Details

Warning: The style_tt() can normally be used to style the group headers, as expected, but that feature is not available for Markdown and Word tables.

Value

An object of class tt representing the table.

Examples

# vector of row labels
dat <- data.frame(
    label = c("a", "a", "a", "b", "b", "c", "a", "a"),
    x1 = rnorm(8),
    x2 = rnorm(8))
tt(dat[, 2:3]) |> group_tt(i = dat$label)

# named lists of labels
tt(mtcars[1:10, 1:5]) |>
  group_tt(
    i = list(
      "Hello" = 3,
      "World" = 8),
    j = list(
      "Foo" = 2:3,
      "Bar" = 4:5))

dat <- mtcars[1:9, 1:8]
tt(dat) |>
  group_tt(i = list(
    "I like (fake) hamburgers" = 3,
    "She prefers halloumi" = 4,
    "They love tofu" = 7))

tt(dat) |>
  group_tt(
    j = list(
      "Hamburgers" = 1:3,
      "Halloumi" = 4:5,
      "Tofu" = 7))

x <- mtcars[1:5, 1:6]
tt(x) |>
  group_tt(j = list("Hello" = 1:2, "World" = 3:4, "Hello" = 5:6)) |>
  group_tt(j = list("Foo" = 1:3, "Bar" = 4:6))

Description

The plot_tt() function allows for the insertion of images and inline plots into tinytable objects. This function can handle both local and web-based images.

Usage

plot_tt(
  x,
  i = NULL,
  j = NULL,
  fun = NULL,
  data = NULL,
  color = "black",
  xlim = NULL,
  height = 1,
  asp = 1/3,
  images = NULL,
  assets = "tinytable_assets",
  ...
)

Arguments

Details

The plot_tt() can insert images and inline plots into tables.

Value

A modified tinytable object with images or plots inserted.

Description

This function is called automatically by R whenever a tinytable object is anprinted to the console or in an HTML viewer pane.

Usage

## S3 method for class 'tinytable'
print(x, output = get_option("tinytable_print_output", default = NULL), ...)

Arguments

Value

launch a browser window or cat() the table to console.

Description

Combine tinytable objects by rows (vertically)

Usage

## S4 method for signature 'tinytable,tinytable'
rbind2(x, y, use_names = TRUE, headers = TRUE, ...)

Arguments

Details

format_tt() calls applied to x or y are evaluated before binding, to allow distinct formatting for each panel.

Calls to other tinytable functions such as style_tt() or group_tt() are ignored when applied to x or y. These functions should be applied to the final table instead.

Information in these S4 slots is carried over from x to the combined table:

• x@output

• x@caption

• x@width

Information in these S4 slots is concatenated and carried over to the combined table:

• c(x@notes, y@notes)

This function relies on the rbindlist() function from the data.table package.

Examples

library(tinytable)
x = tt(mtcars[1:3, 1:2], caption = "Combine two tiny tables.")
y = tt(mtcars[4:5, 8:10]) 

# rbind() does not support additional aarguments
# rbind2() supports additional arguments

# basic combination
rbind(x, y)

rbind(x, y) |> format_tt(replace = "")

# omit y header
rbind2(x, y, headers = FALSE)

# bind by position rather than column names
rbind2(x, y, use_names = FALSE)

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, overwrite = FALSE)

Arguments

Value

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

Examples

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)

Description

Style a Tiny Table

Usage

style_tt(
  x,
  i = NULL,
  j = NULL,
  bold = FALSE,
  italic = FALSE,
  monospace = FALSE,
  underline = FALSE,
  strikeout = FALSE,
  color = NULL,
  background = NULL,
  fontsize = NULL,
  align = NULL,
  alignv = NULL,
  colspan = NULL,
  rowspan = NULL,
  indent = 0,
  line = NULL,
  line_color = "black",
  line_width = 0.1,
  finalize = NULL,
  tabularray_inner = NULL,
  tabularray_outer = NULL,
  bootstrap_class = NULL,
  bootstrap_css = NULL,
  bootstrap_css_rule = NULL,
  output = NULL,
  ...
)

Arguments

Details

This function applies styling to a table created by tt(). It allows customization of text style (bold, italic, monospace), text and background colors, font size, cell width, text alignment, column span, and indentation. The function also supports passing native instructions to LaTeX (tabularray) and HTML (bootstrap) formats.

Note: Markdown and Word tables only support these styles: italic, bold, strikeout. 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.

Value

An object of class tt representing the table.

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

Examples

if (knitr::is_html_output()) options(tinytable_print_output = "html")

library(tinytable)

tt(mtcars[1:5, 1:6])

# Alignment
tt(mtcars[1:5, 1:6]) |> 
  style_tt(j = 1:5, align = "lcccr")

# Colors and styles
tt(mtcars[1:5, 1:6]) |> 
  style_tt(i = 2:3, background = "black", color = "orange", bold = TRUE)

# column selection with `j``
tt(mtcars[1:5, 1:6]) |> 
  style_tt(j = 5:6, background = "pink")

tt(mtcars[1:5, 1:6]) |>
  style_tt(j = "drat|wt", background = "pink")

tt(mtcars[1:5, 1:6]) |>
  style_tt(j = c("drat", "wt"), background = "pink")

tt(mtcars[1:5, 1:6], theme = "void") |>
  style_tt(
    i = 2, j = 2,
    colspan = 3,
    rowspan = 2,
    align="c",
    alignv = "m",
    color = "white",
    background = "black",
    bold = TRUE)
  
tt(mtcars[1:5, 1:6], theme = "void") |>
  style_tt(
    i=0:3,
    j=1:3,
    line="tblr",
    line_width=0.4,
    line_color="teal")
    
tt(mtcars[1:5, 1:6], theme = "bootstrap") |>
    style_tt(
      i = c(2,5),
      j = 3,
      strikeout = TRUE,
      fontsize = 0.7)
      
tt(mtcars[1:5, 1:6]) |>
  style_tt(bootstrap_class = "table table-dark table-hover")


inner <- "
column{1-4}={halign=c},
hlines = {fg=white},
vlines = {fg=white},
cell{1,6}{odd} = {bg=teal7},
cell{1,6}{even} = {bg=green7},
cell{2,4}{1,4} = {bg=red7},
cell{3,5}{1,4} = {bg=purple7},
cell{2}{2} = {r=4,c=2}{bg=azure7},
"
tt(mtcars[1:5, 1:4], theme = "void") |>
  style_tt(tabularray_inner = inner)

Description

A theme is a function which applies a collection of transformations to a tinytable object. Whereas the other tinytable functions such as format_tt() and style_tt() aim to be output-agnostic, themes can be output-specific, only applying to LaTeX, HTML, or Typst, as needed.

Each theme can have specific arguments, which are passed to the theme_tt() function. See the "Arguments" section below.

Usage

theme_tt(x, theme, ...)

Arguments

Value

A modified tinytable object

Arguments

multipage

• rowhead: Non-negative integer. The number of header rows to repeat on each page.

  • Set globally with options("tinytable_theme_multipage_rowhead" = 1L)

• rowfoot: Non-negative integer. The number of footer rows to repeat on each page.

  • Set globally with options("tinytable_theme_multipage_rowfoot" = 1L)

tabular

• style:

  • "tabular": Drop all LaTeX dependencies and floating environments, except ⁠\\begin{tabular}⁠

  • "tabularray": Drop all LaTeX dependencies and floating environments, except ⁠\\begin{tblr}⁠

  • Set globally with options("tinytable_theme_tabular_style" = "tblr")

placement

• horizontal (Typst only): "l", "c", or "r" to align the table horizontally in the page.

  • Set globally with options("tinytable_theme_placement_horizontal" = "l")

• latex_float: String to insert in square brackets after the LaTeX table environment, ex: "H", "htbp". The default value is controlled by a global option:

  • Set globally with options("tinytable_theme_placement_latex_float" = "H")

resize

• width: A numeric value between 0.01 and 1, representing the proportion of the line width to use

  • Set globally with options("tinytable_theme_resize_width" = 0.9)

• direction: "down", "up", "both" A string indicating if the table should be scaled in one direction. For example, "down" will only resize the table if it exceeds ⁠\linewidth⁠

  • Set globally with options("tinytable_theme_resize_direction" = "down")

rotate

• angle: Angle of the rotation. For example, 'angle=90“ applies a half counter-clockwise turn.

• Caveats:

  • LaTeX and Typst only.

  • Typst: In Quarto documents, rotation does not work because Quarto takes over the figure environment.

  • LaTeX: In Quarto documents, captions must be specified using the caption argument in tt() rather than via Quarto chunk options.

Examples

library(tinytable)

x <- mtcars[1:4, 1:4]

# equivalent calls
tt(x, theme = "striped")

tt(x) |> theme_tt("striped")

# resize w/ argument
x <- cbind(mtcars[1:10,], mtcars[1:10,])
tt(x) |>
  theme_tt("resize", width = .9) |>
  print("latex")

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),
  escape = get_option("tinytable_tt_escape", default = FALSE),
  ...
)

Arguments

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

Quarto

Figure environment

• options("tinytable_quarto_figure" = FALSE): Typst only. Normally, it is best to allow Quarto to define the figure environment, so the default behavior is to not include one.

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 ⁠\QuartoMarkdownBase64{}⁠ 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

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

• options(tinytable_html_portable = TRUE): plot_tt() inserts base 64 encoded images directly in the HTML file rather than use external links.

PDF

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

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

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)