---
title: "Equations in R Markdown and Quarto"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Equations in R Markdown and Quarto}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
library(equatiomatic)
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

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:

```{r iris}
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)
```

Now, let's fit a simple linear model to those "label-augmented" `iris` data:

```{r}
lm1 <- lm(Sepal.Length ~ Sepal.Width, data = iris)
lm1
```

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

```{r extracteq}
extract_eq(lm1)
```

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

```{r equation-iris}
equation(lm1)
```

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 `r eq_(lm1)`, 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:

$$
`r eq__(lm1)`
$${#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:

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