The Eqn function is designed to produce LaTeX expressions of mathematical
equations for writing.
The output can be copied/pasted into documents or
used directly in chunks in .Rmd, .Rnw, or .qmd
documents to compile to equations.
Eqn wraps the equations generated by its arguments
in either a \begin{equation} ...\end{equation} or
\begin{align} ...\end{align} LaTeX environment. See also
ref for consistent inline referencing of numbered equations in documents.
In a code chunk, use the chunk options results='asis', echo=FALSE to show only
the result of compiling the LaTeX expressions. For example,
```{r results = "asis", echo = FALSE}
Eqn("\mathbf{X} = \mathbf{U} \mathbf{\Lambda} \mathbf{V}", label='eq:svd')
```
Note that you can avoid the "leaning toothpick syndrome" of all those doubled backslashes by using R's new (as of 4.0.0)
"raw strings", composed as r"(...)" or r"{...}"
```{r results = "asis", echo = FALSE}
Eqn(r"{\mathbf{X} = \mathbf{U} \mathbf{\Lambda} \mathbf{V}}", label = 'eq:svn')
```
A collection of helper functions, such as Eqn_newline, Eqn_hspace
facilitate formatting of equations and functions like Eqn_overset and Eqn_overbrace
provide for decorators over or under a LaTeX expression or matrix. See Eqn_helpers
for their descriptions and examples.
ref{} provides inline references to equations in R
markdown and Quarto documents.
Depending on the output type this function will provide the correct
inline wrapper for MathJax or LaTeX equations. This provides more
consistent referencing when switching between HTML and PDF outputs as
well as documentation types (e.g., .Rmd vs .qmd).
Usage
Eqn(
...,
label = NULL,
align = FALSE,
preview = getOption("previewEqn"),
html_output = knitr::is_html_output(),
quarto = getOption("quartoEqn"),
mat_args = list(),
preview.pdf = FALSE,
preview.packages = NULL
)
ref(
label,
parentheses = TRUE,
html_output = knitr::is_html_output(),
quarto = getOption("quartoEqn")
)Arguments
- ...
comma separated LaTeX expressions that are either a) a
charactervector, which will be automatically wrapped the expression inside a call tocat, b) amatrixobject containing character or numeric information, which will be passedlatexMatrix, along with the information inmat_args, or c) an object that was explicitly created vialatexMatrix, which provides greater specificity.Note that user defined functions that use
catwithin their body should return an empty character vector to avoid printing the returned object- label
character vector specifying the label to use (e.g.,
eq:myeqn), which for LaTeX can be reference via\ref{eq:myeqn}or via the inline functionref. Including a label will also include an equation number automatically.For compiled documents if an HTML output is detected (see
html_output) then the equations will be labelled via(\#eq:myeqn)and references via\@ref(eq:myeqn), or again viareffor convenience. For Quarto documents the label must be of the formeq-LABEL- align
logical; use the
alignenvironment with explicit&representing alignment points. Default:FALSE- preview
logical; render an HTML version of the equation and display? This is intended for testing purposes and is only applicable to interactive R sessions, though for code testing purposes can be set globally via
options(e.g.,options('previewEqn' = FALSE)). Disabled wheneverquartoorhtml_outputareTRUE- html_output
logical; use labels for HTML outputs instead of the LaTeX? Automatically changed for compiled documents that support
knitr. Generally not required or recommended for the user to modify, except to view the generated syntax- quarto
logical; use Quarto referencing syntax? When
TRUEthehtml_outputwill be irrelevant. Generally not recommended for the user to modify, except to view the generated syntax- mat_args
list of arguments to be passed to
latexMatrixto change the properties of thematrixinput object(s). Note that these inputs are used globally, and apply to eachmatrixobject supplied. If further specificity is required createlatexMatrixobjects directly.- preview.pdf
logical; build a PDF of the preview equation? Generally not require unless additional LaTeX packages are required that are not supported by MathJax
- preview.packages
character vector for adding additional LaTeX package information to the equation preview. Only used when
preview.pdf = TRUE- parentheses
logical; include parentheses around the referenced equation?
References
Josiah Parry, Raw strings in R, https://josiahparry.com/posts/2023-01-19-raw-strings-in-r.html
See also
Eqn_helpers, latexMatrix, matrix2latex, ref
Examples
# character input
Eqn('e=mc^2')
#>
#> \begin{equation*}
#> e=mc^2\end{equation*}
# show only the LaTeX code
Eqn('e=mc^2', preview=FALSE)
#>
#> \begin{equation*}
#> e=mc^2\end{equation*}
# Equation numbers & labels
Eqn('e=mc^2', label = 'eq:einstein')
#>
#> \begin{equation}
#> \label{eq:einstein}
#> e=mc^2\end{equation}
Eqn("X=U \\lambda V", label='eq:svd')
#>
#> \begin{equation}
#> \label{eq:svd}
#> X=U \lambda V\end{equation}
# html_output and quarto outputs only show code
# (both auto detected in compiled documents)
Eqn('e=mc^2', label = 'eq:einstein', html_output = TRUE)
#>
#> \begin{equation}
#> (\#eq:einstein)
#> e=mc^2\end{equation}
# Quarto output
Eqn('e=mc^2', label = 'eq-einstein', quarto = TRUE)
#>
#> \begin{equation}
#> \label{eq-einstein}
#> e=mc^2\end{equation}
if (FALSE) { # \dontrun{
# The following requires LaTeX compilers to be pre-installed
# View PDF instead of HTML
Eqn('e=mc^2', preview.pdf=TRUE)
# Add extra LaTeX dependencies for PDF build
Eqn('\\bm{e}=mc^2', preview.pdf=TRUE,
preview.packages=c('amsmath', 'bm'))
} # }
# Multiple expressions
Eqn("e=mc^2",
Eqn_newline(),
"X=U \\lambda V", label='eq:svd')
#>
#> \begin{equation}
#> \label{eq:svd}
#> e=mc^2 \\
#> X=U \lambda V\end{equation}
# expressions that use cat() within their calls
Eqn('SVD = ',
latexMatrix("u", "n", "k"),
latexMatrix("\\lambda", "k", "k", diag=TRUE),
latexMatrix("v", "k", "p", transpose = TRUE),
label='eq:svd')
#>
#> \begin{equation}
#> \label{eq:svd}
#> SVD = \begin{pmatrix}
#> u_{11} & u_{12} & \cdots & u_{1k} \\
#> u_{21} & u_{22} & \cdots & u_{2k} \\
#> \vdots & \vdots & & \vdots \\
#> u_{n1} & u_{n2} & \cdots & u_{nk} \\
#> \end{pmatrix}
#> \begin{pmatrix}
#> \lambda_{1} & 0 & \cdots & 0 \\
#> 0 & \lambda_{2} & \cdots & 0 \\
#> \vdots & \vdots & \ddots & \vdots \\
#> 0 & 0 & \cdots & \lambda_{k} \\
#> \end{pmatrix}
#> \begin{pmatrix}
#> v_{11} & v_{12} & \cdots & v_{1p} \\
#> v_{21} & v_{22} & \cdots & v_{2p} \\
#> \vdots & \vdots & & \vdots \\
#> v_{k1} & v_{k2} & \cdots & v_{kp} \\
#> \end{pmatrix}^\top
#> \end{equation}
# align equations using & operator
Eqn("X &= U \\lambda V", Eqn_newline(),
"& = ", latexMatrix("u", "n", "k"),
latexMatrix("\\lambda", "k", "k", diag=TRUE),
latexMatrix("v", "k", "p", transpose = TRUE),
align=TRUE)
#>
#> \begin{align*}
#> X &= U \lambda V \\
#> & = \begin{pmatrix}
#> u_{11} & u_{12} & \cdots & u_{1k} \\
#> u_{21} & u_{22} & \cdots & u_{2k} \\
#> \vdots & \vdots & & \vdots \\
#> u_{n1} & u_{n2} & \cdots & u_{nk} \\
#> \end{pmatrix}
#> \begin{pmatrix}
#> \lambda_{1} & 0 & \cdots & 0 \\
#> 0 & \lambda_{2} & \cdots & 0 \\
#> \vdots & \vdots & \ddots & \vdots \\
#> 0 & 0 & \cdots & \lambda_{k} \\
#> \end{pmatrix}
#> \begin{pmatrix}
#> v_{11} & v_{12} & \cdots & v_{1p} \\
#> v_{21} & v_{22} & \cdots & v_{2p} \\
#> \vdots & \vdots & & \vdots \\
#> v_{k1} & v_{k2} & \cdots & v_{kp} \\
#> \end{pmatrix}^\top
#> \end{align*}
# numeric/character matrix example
A <- matrix(c(2, 1, -1,
-3, -1, 2,
-2, 1, 2), 3, 3, byrow=TRUE)
b <- matrix(c(8, -11, -3))
# numeric matrix wrapped internally
cbind(A,b) |> Eqn()
#>
#> \begin{equation*}
#> \begin{pmatrix}
#> 2 & 1 & -1 & 8 \\
#> -3 & -1 & 2 & -11 \\
#> -2 & 1 & 2 & -3 \\
#> \end{pmatrix}
#> \end{equation*}
cbind(A,b) |> latexMatrix() |> Eqn()
#>
#> \begin{equation*}
#> \begin{pmatrix}
#> 2 & 1 & -1 & 8 \\
#> -3 & -1 & 2 & -11 \\
#> -2 & 1 & 2 & -3 \\
#> \end{pmatrix}
#> \end{equation*}
# change numeric matrix brackets globally
cbind(A,b) |> Eqn(mat_args=list(matrix='bmatrix'))
#>
#> \begin{equation*}
#> \begin{bmatrix}
#> 2 & 1 & -1 & 8 \\
#> -3 & -1 & 2 & -11 \\
#> -2 & 1 & 2 & -3 \\
#> \end{bmatrix}
#> \end{equation*}
# greater flexibility when using latexMatrix()
cbind(A, b) |> latexMatrix() |> partition(columns=3) |> Eqn()
#>
#> \begin{equation*}
#> \begin{pmatrix}
#> \begin{array}{c c c | c}
#> 2 & 1 & -1 & 8\\
#> -3 & -1 & 2 & -11\\
#> -2 & 1 & 2 & -3\\
#> \end{array}
#> \end{pmatrix}\end{equation*}
# with showEqn()
showEqn(A, b, latex=TRUE) |> Eqn()
#>
#> \begin{equation*}
#> \begin{array}{lllllll}
#> 2 \cdot x_1 &+& 1 \cdot x_2 &-& 1 \cdot x_3 &=& 8 \\
#> -3 \cdot x_1 &-& 1 \cdot x_2 &+& 2 \cdot x_3 &=& -11 \\
#> -2 \cdot x_1 &+& 1 \cdot x_2 &+& 2 \cdot x_3 &=& -3 \\
#> \end{array}\end{equation*}
# used inside of Eqn() or manually defined labels in the document
Eqn('e = mc^2', label='eq:einstein')
#>
#> \begin{equation}
#> \label{eq:einstein}
#> e = mc^2\end{equation}
# use within inline block via `r ref()`
ref('eq:einstein')
#> [1] "(\\ref{eq:einstein})"
ref('eq:einstein', parentheses=FALSE)
#> [1] "\\ref{eq:einstein}"
ref('eq:einstein', html_output=TRUE)
#> [1] "\\@ref(eq:einstein)"
# With Quarto
Eqn('e = mc^2', label='eq-einstein', quarto=TRUE)
#>
#> \begin{equation}
#> \label{eq-einstein}
#> e = mc^2\end{equation}
ref('eq:einstein', quarto=TRUE)
#> [1] "(\\ref{eq:einstein})"
ref('eq:einstein', quarto=TRUE, parentheses=FALSE)
#> [1] "\\ref{eq:einstein}"