Rich-formatted Tables with Tabularise

Example table

Let’s use the ToothGrowth from {datasets} for this example. You can directly add labels and units, or use data.io::labellise() (optional step):

data("ToothGrowth", package = "datasets")
# Add labels and units
ToothGrowth <- data.io::labelise(ToothGrowth,
  label = list(len = "Tooth growth", supp = "Supplement", dose = "Vitamin C"),
  units = list(len = "mm", dose = "mg/d"))
#> Registered S3 method overwritten by 'tsibble':
#>   method               from 
#>   as_tibble.grouped_df dplyr
#> Registered S3 method overwritten by 'data.io':
#>   method             from  
#>   $.subsettable_type svMisc

The usual output of a data frame in R (here, a short version with only the first 6 lines) is quite basic in terms of formatting:

head(ToothGrowth)
#>    len supp dose
#> 1  4.2   VC  0.5
#> 2 11.5   VC  0.5
#> 3  7.3   VC  0.5
#> 4  5.8   VC  0.5
#> 5  6.4   VC  0.5
#> 6 10.0   VC  0.5

These outputs are acceptable in an R script, or may be in a notebook, but not in a more polished document (report, presentation, paper, book…) Several packages provide functions to better format such outputs for reporting and publications, such as {flextable}, {gt} or {tinytable} among others.

{tabularise} uses and enhances {flextable} to nicely format various tables and allow to output them in HTML, LaTeX/PDF, Word or PowerPoint. The tabularise() function automatically uses the labels and units of variables if they are present in the data frame (note that tabularise$<type>(....) is a variant of tabularise(...., type = headtail)).

library(tabularise)
tabularise$headtail(ToothGrowth) 
#> Warning in set2(resolve(...)): The object is read-only and cannot be modified.
#> If you have to modify it for a legitimate reason, call the method $lock(FALSE)
#> on the object before $set(). Using $lock(FALSE) to modify the object will be
#> enforced in future versions of knitr and this warning will become an error.

Of course, as the output of tabularise() is a flextable object, you can further customize it using the functions provided by {flextable}.

tabularise$headtail(ToothGrowth) |>
  flextable::add_header_lines(
    values = "Effect of Vitamin C on Tooth Growth in Guinea Pigs")
#> Warning in set2(resolve(...)): The object is read-only and cannot be modified.
#> If you have to modify it for a legitimate reason, call the method $lock(FALSE)
#> on the object before $set(). Using $lock(FALSE) to modify the object will be
#> enforced in future versions of knitr and this warning will become an error.

There are a couple of tables provided in {tabularise} for data.frame, matrix, and Correlation objects. However, its coverage is intentionally low. Many other tables are provided in packages that depend or import {tabularise}, like:

• inferit formats tables produced for htest objects from the {stats} package

• modelit includes a set of practical functions for formatting tables of various models in lm, glm, nls, anova; aov objects from the {stats} package.

• exploreit (coming soon…)

• and more to come…

You should explore these packages to see what they can do for you. For other examples of use, you can browse the biological data science course inline (in French).

Equations

For several tables (like those for models in the {modelit} package), LaTeX equations are created and displayed in the table. {tabularise} provides the equation() generic function to create that LaTeX code. One can also provide directly a LaTeX instruction to equation():

eq <- equation("y = \\alpha + \\beta_1 \\cdot x + \\beta_2 \\cdot x^2")
eq

y = α + β₁ ⋅ x + β₂ ⋅ x²

Of course, the function is more useful when a,n equation is constructed for a model (using the {equatiomatic} package).

tg_lm <- lm(len ~ dose * supp, data = ToothGrowth)
tg_eq <- equation(tg_lm, terms_per_line = 3, wrap = TRUE)
tg_eq

$$ \begin{aligned} \operatorname{Tooth\ growth \ [mm]} &= \alpha + \beta_{1}(\operatorname{Vitamin\ C \ [mg/d]}) + \beta_{2}(\operatorname{Supplement}_{\operatorname{VC}})\ + \\ &\quad \beta_{3}(\operatorname{Vitamin\ C \ [mg/d]} \times \operatorname{Supplement}_{\operatorname{VC}}) + \epsilon \end{aligned} $$

Note that equation() also automatically uses labels and units, but that can be turned off by the argument auto.labs = FALSE. See ?tabularise::equation and ?equatiomatic::extract_eq for the various arguments.

{tabularise} also provides eq_() and eq__() functions to ease the inclusion of such equations in R Markdown or Quarto documents. The eq_() function, when used at the R console in RStudio outputs a formatted version of the equation in the Viewer pane. This is useful to preview the final version of the equation from R. It is also useful to produce equations in inline R chunks like len  = α + β₁(dose ) + β₂(supp_VC) + β₃(dose  × supp_VC) + ϵ.

The eq__() function is used in R Markdown or Quarto documents to produce the LaTeX code of the equation to be integrated in an equation display markdown tag like this:

$$\begin{aligned} \operatorname{Tooth\ growth \ [mm]} &= \alpha + \beta_{1}(\operatorname{Vitamin\ C \ [mg/d]}) + \beta_{2}(\operatorname{Supplement}_{\operatorname{VC}})\ + \\ &\quad \beta_{3}(\operatorname{Vitamin\ C \ [mg/d]} \times \operatorname{Supplement}_{\operatorname{VC}}) + \epsilon \end{aligned}$$

These functions can be used independently of tabularise() to manage your model equations in various documents.