Vignette "Equations in R Markdown and Quarto" added

Author: phgrosjean

NEWS.md

@@ -1,5 +1,9 @@
 # equatiomatic 0.4.2
 
+* New vignette "Equations in R Markdown and Quarto" that explain how to use the
+    three functions `equation()`, `eq_()` and `eq__()` to ease inclusion of
+    equations in R Markdown and Quarto documents.
+
 * `extract_eq()` can now extract equations from a list of models. There is an
     example of an application at the end of the "Introduction to {equatiomatic}"
     vignette.

R/shiny.R

@@ -8,7 +8,7 @@
 #' @param outputId The identifier of the output from the server. Should be
 #'   passed as a string.
 #' @param env The environment
-#' @param quoted Is the expresion quoted?
+#' @param quoted Is the expression quoted?
 #' @param outputArgs list of output arguments
 #' 
 #' @return Render the equation in a suitable way for Shiny for [renderEq()] in

inst/WORDLIST

@@ -48,7 +48,6 @@ docx
 edu
 eq
 equatiomatic’
-expresion
 frac
 gelman
 geoms
@@ -86,5 +85,6 @@ texPreview
 tibble
 tidymodels
 ver
+VSCode
 www
 yonicd

man/renderEq.Rd

@@ -0,0 +1,90 @@
+---
+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)
+```