# Equations in R Markdown and Quarto

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

    extract_eq(lm1)

\[ \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:

    equation(lm1)

\[ \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 \(\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:

\[ \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]}}) \]