Eqn: Create a LaTeX Equation Wrapper

In friendly/matlib: Matrix Functions for Teaching and Learning Linear Algebra and Multivariate Statistics

Create a LaTeX Equation Wrapper

Description

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 character vector, which will be automatically wrapped the expression inside a call to cat, b) a matrix object containing character or numeric information, which will be passed latexMatrix, along with the information in mat_args, or c) an object that was explicitly created via latexMatrix, which provides greater specificity. Note that user defined functions that use cat within 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 function ref. 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 via ref for convenience. For Quarto documents the label must be of the form eq-LABEL
align	logical; use the align environment 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 whenever quarto or html_output are TRUE
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 TRUE the html_output will 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 latexMatrix to change the properties of the matrix input object(s). Note that these inputs are used globally, and apply to each matrix object supplied. If further specificity is required create latexMatrix objects 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?

Author(s)

Phil Chalmers

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

# show only the LaTeX code
Eqn('e=mc^2', preview=FALSE)

# Equation numbers & labels
Eqn('e=mc^2', label = 'eq:einstein')
Eqn("X=U \\lambda V", label='eq:svd')

# html_output and quarto outputs only show code
#   (both auto detected in compiled documents)
Eqn('e=mc^2', label = 'eq:einstein', html_output = TRUE)

# Quarto output
Eqn('e=mc^2', label = 'eq-einstein', quarto = TRUE)

## Not run: 
# 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'))


## End(Not run)

# Multiple expressions
Eqn("e=mc^2",
    Eqn_newline(),
    "X=U \\lambda V", label='eq:svd')

# 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')

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

#  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()
cbind(A,b) |> latexMatrix() |> Eqn()

# change numeric matrix brackets globally
cbind(A,b) |> Eqn(mat_args=list(matrix='bmatrix'))

# greater flexibility when using latexMatrix()
cbind(A, b) |> latexMatrix() |> partition(columns=3) |> Eqn()

# with showEqn()
showEqn(A, b, latex=TRUE) |> Eqn()


# used inside of Eqn() or manually defined labels in the document
Eqn('e = mc^2', label='eq:einstein')

# use within inline block via `r ref()`
ref('eq:einstein')
ref('eq:einstein', parentheses=FALSE)
ref('eq:einstein', html_output=TRUE)

# With Quarto
Eqn('e = mc^2', label='eq-einstein', quarto=TRUE)
ref('eq:einstein', quarto=TRUE)
ref('eq:einstein', quarto=TRUE, parentheses=FALSE)

friendly/matlib documentation built on Dec. 6, 2024, 9:25 a.m.