Equations in R Markdown and Quarto

Source: vignettes/markdown-quarto.Rmd

This vignette demonstrates how to include equations in R Markdown and Quarto documents using the {equatiomatic} package and the new functions equation(), eq_() and eq__() in version >= 0.4.0.

Display equations from an R chunk

The most natural way to include equations in R Markdown or Quarto documents is to just print the equation generated by extract_eq() in an R chunk. The knit_print() method of {knitr} will then be used to generate a display equation (a LaTeX equation surrounded by double dollars $$...$$). Now, the equation() function can now be used in place of extract_eq(). It can use label and units attributes set to variables in the dataset used in the model. This is a convenient way to use friendlier variable names (and possibly units) in the equation.

Here is an example using the (overused) iris dataset. We add label and units attributes to our variables inside the data.frame:

data(iris)
# Attach `label` and `units` attributes to the variables
# Note, this is done manually, but there are functions in various packages to
# ease the process (see packages {Hmisc}, {labelled}, {LabelR}, {labelVector})
attr(iris$Sepal.Length, "label") <- "Sepal length"
attr(iris$Sepal.Length, "units") <- "cm"
attr(iris$Sepal.Width, "label") <- "Sepal width"
attr(iris$Sepal.Width, "units") <- "cm"
attr(iris$Petal.Length, "label") <- "Petal length"
attr(iris$Petal.Length, "units") <- "cm"
attr(iris$Petal.Width, "label") <- "Petal width"
attr(iris$Petal.Width, "units") <- "cm"

str(iris)
#> 'data.frame':    150 obs. of  5 variables:
#>  $ Sepal.Length: num  5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
#>   ..- attr(*, "label")= chr "Sepal length"
#>   ..- attr(*, "units")= chr "cm"
#>  $ Sepal.Width : num  3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
#>   ..- attr(*, "label")= chr "Sepal width"
#>   ..- attr(*, "units")= chr "cm"
#>  $ Petal.Length: num  1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
#>   ..- attr(*, "label")= chr "Petal length"
#>   ..- attr(*, "units")= chr "cm"
#>  $ Petal.Width : num  0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
#>   ..- attr(*, "label")= chr "Petal width"
#>   ..- attr(*, "units")= chr "cm"
#>  $ Species     : Factor w/ 3 levels "setosa","versicolor",..: 1 1 1 1 1 1 1 1 1 1 ...

Now, let’s fit a simple linear model to those “label-augmented” iris data:

lm1 <- lm(Sepal.Length ~ Sepal.Width, data = iris)
lm1
#> 
#> Call:
#> lm(formula = Sepal.Length ~ Sepal.Width, data = iris)
#> 
#> Coefficients:
#> (Intercept)  Sepal.Width  
#>      6.5262      -0.2234

If we use extract_eq(), we got the equation using variable names (unless we specify the swap_var_names= argument, of course):

Sepal.Length=α+β1(Sepal.Width)+ϵ \operatorname{Sepal.Length} = \alpha + \beta_{1}(\operatorname{Sepal.Width}) + \epsilon

Now, using equation() instead, we use the labels and units attributes of the variables in the dataset:

Sepallength[cm]=α+β(Sepalwidth[cm])+ϵ \operatorname{Sepal\ length \ [cm]} = \alpha + \beta_{}(\operatorname{Sepal\ width \ [cm]}) + \epsilon

In case the model does not retain the original data with their labels, one can use the origdata= argument to pass the original data set to the equation() function. Also the auto.labs= argument can be set to FALSE to avoid using the labels and units attributes (it is TRUE by default).

Inline equations in R Markdown or Quarto documents

Now, if you want an inline equation (an equation inside the text), you can easily use an inline R chunk calling the eq_() function like this: `r eq_(lm1)`. This produces Sepallength[cm]=α+β(Sepalwidth[cm])+ϵ\operatorname{Sepal\ length \ [cm]} = \alpha + \beta_{}(\operatorname{Sepal\ width \ [cm]}) + \epsilon, thus right inside the text. Note that eq_() also handles label and units attributes, the same way equation() does. Moreover, if you issue eq_(lm1) in the R console or terminal (at the R prompt), you got a preview of your equation in a temporary HTML document, or in the Viewer pane if you work in RStudio. This is convenient to check the appearance of your equation without having to render the whole document.

Display equations with labels

The extract_eq() function has a label= argument that allows you to set a label for the equation, but in LaTeX documents only (thus for PDF but not for HTML final documents). It does not ease cross-referencing of the equation because the label is not known from within Markdown and your Markdown editor (RStudio, VSCode, Positron…). The eq__() function allows to insert an equation generated with {equatiomatic} inside a $$...$$ construct in a Markdown text. The construct can potentially have a label, like $$...$${#eq-model1} that can be easily cross-referenced. You just have to place an R chunk with your equation inside the $$...$$ construct, very similarly to what you did with the inline R chunk. Thus, you would have something like this in your document:

$$
`r eq__(lm1)`
$${#eq-model1}

which translates into:

Sepallength[cm]=α+β(Sepalwidth[cm])+ϵ \operatorname{Sepal\ length \ [cm]} = \alpha + \beta_{}(\operatorname{Sepal\ width \ [cm]}) + \epsilon {#eq-model1}

In documents that support cross-referencing (unfortunately not this vignette document), the equation is numbered at the right and you can reference it in the text with @eq-model1. The eq__() function is also aware of label and units attributes and it also allows to preview the equation when its code is issued at the R prompt.

Customizing equations

All three functions equation(), eq_() and eq__() also support all the arguments of extract_eq() (for colors, parameters change, line wrapping, etc.). Here is an example:

equation(lm1, var_colors = c(Sepal.Width  = "red"),
  ital_vars = TRUE, use_coefs = TRUE, coef_digits = 3)

$$ \widehat{Sepal\ length \ [cm]} = 6.526 - 0.223({\color{red}{Sepal\ width \ [cm]}}) $$