Create a LaTeX Equation Wrapper

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. It 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 a code chunk, use the chunk options results='asis', echo=FALSE to show only the result of compiling the LaTeX expressions.

Eqn_newline() emits a newline (\) in an equation, with an optional increase to the padding following the newline.

Eqn_text() inserts a literal string to be rendered in a text font in an equation.

Eqn_hspace() is used to create (symmetric) equation spaces, most typically around = signs Input to lhs, rhs can be a numeric to increase the size of the space or a character vector to be passed to the LaTeX macro \hspace{}.

Eqn_vspace() inserts vertical space between lines in an equation. Typically used for aligned, multiline equations.

Eqn_size() is used to increase or decrease the size of LaTeX text and equations. Can be applied to a specific string or applied to all subsequent text until overwritten.

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
)

Eqn_newline(space = 0)

Eqn_text(text)

Eqn_hspace(lhs = 5, mid = "", rhs = NULL, times = 1)

Eqn_vspace(space)

Eqn_size(string, size = 0)

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

space

includes extra vertical space. Metric of the vertical space must be 'ex', 'pt', 'mm', 'cm', 'em', 'bp', 'dd', 'pc', or 'in'

text

argument to be used within \text{}

lhs

spacing size. Can be a number between -1 and 6. -1 provides negative spaces and 0 gives no spacing. Input can also be a character vector, which will be passed to \hspace{} (e.g., '1cm'; see space argument for supported metrics). Default is 5, resulting in a \quad space.

mid

character vector to place in the middle of the space specification. Most commonly this will be operators like '='

rhs

see lhs for details. If left as NULL and mid is specified the this will be set to rhs to create symmetric spaces around mid

times

number of times to repeat the spacings

string

a string that should have its text size modified. If missing the size modifier is returned, which applies the size modifier to the remainder of the text until reset with Eqn_size()

size

numeric size of LaTeX text modifier, ranging from -3 (\tiny) to 5 (\HUGE), with 0 defining the normal test size (\normalsize; default)

parentheses

logical; include parentheses around the referenced equation?

Author

Phil Chalmers

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*}


Eqn_newline()
#> [1] " \\\\ \n"
Eqn_newline('10ex')
#> [1] " \\\\[10ex] \n"


Eqn_hspace()
#> [1] "\\quad"
Eqn_hspace(3) # smaller
#> [1] "\\;"
Eqn_hspace(3, times=2)
#> [1] "\\;\\;"
Eqn_hspace('1cm')
#> [1] "\\hspace{1cm}"

# symmetric spacing around mid
Eqn_hspace(mid='=')
#> [1] "\\quad=\\quad"
Eqn_hspace(mid='=', times=2)
#> [1] "\\quad\\quad=\\quad\\quad"


Eqn_vspace('1.5ex')
#> [1] " \\vspace{1.5ex} \n"
Eqn_vspace('1cm')
#> [1] " \\vspace{1cm} \n"



# set size globally
Eqn_size(size=3)
#> [1] "\\LARGE"
Eqn_size() # reset
#> [1] "\\normalsize"

# locally for defined string
string <- 'e = mc^2'
Eqn_size(string, size=1)
#> [1] "{\\large e = mc^2}"



# 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}"