Technical reports written in RMarkdown usually include mathematical symbols. RMarkdown addresses that by supporting the inclussion of raw LaTeX code. Depending on the desired output format, the code gets rendered by some LaTeX engine. This feature is very convenient.
The issue here is that writing LaTeX code can be cumbersome and the
result is usually hard to read. Although the use of
newcommand
can alleviate that, in practice people use it
infrequently. The idea behind this package is that if you’re writing an
RMarkdown report, you’re already using R, so yuo might as well use it to
write your LaTeX code as well.
This is best explained through an example. Consider the following equation, encountered in Riemannian geometry:
\[ \frac{d}{dt} \langle V,W \rangle = \langle \frac{DV}{dt}, W \rangle + \langle V, \frac{DW}{dt} \rangle \]
The straightforward way to code that is:
\frac{d}{dt} \langle V,W \rangle = \langle \frac{DV}{dt}, W \rangle + \langle V, \frac{DW}{dt} \rangle
If you were to use latexSymb
, you would proceed as
follows instead. First you would create objects of class
latex_symb
to represent the vector fields:
## Loading required package: purrr
##
## Attaching package: 'latexSymb'
## The following objects are masked from 'package:base':
##
## *, +, -, /, ^
Then you would write R functions to represent the mathematical concepts being used: the inner product, the covariant derivative and the ordinary derivative:
inner <- function(x,y) ang(lsymb(x, ",", y))
cov.der <- function(x) lsymb("D", x)/"dt"
ddt <- function(x) lsymb("d", x)/"dt"
Then you would put everything in an equation
environment:
lenv("equation",
lsymb(
ddt(inner(vf1, vf2)),
"=",
inner(cov.der(vf1), vf2) + inner(vf1, cov.der(vf2))
)
)
## [1] "\\begin{equation}\\n\\frac{ d \\langle V , W \\rangle }{ dt } = \\langle \\frac{ D V }{ dt } , W \\rangle + \\langle V , \\frac{ D W }{ dt } \\rangle\\n\\end{equation}"
A caveat here is that your chuncks should have the options
results='asis', include=FALSE
so that you obtain the plain
LaTeX code.
Let us unpack all of this.
Notice first that in the definition of cov.der
an
important feature is being used. Namely, the /
function is
overwritten by latexSymb
so that if either of its arguments
are objects of class latex_symb
, the output is another
object of that class that uses frac
as you would expect.
This is also done with +
, -
, *
and ^
. Additionally, under
adds support for
the use of subscripts.
Also, in the numerator of cov.der
,
lsymb("D", x)
concatenates the string "D"
and
the object x
, and wraps the result in a new
latex_symb
object.
Further, there’s the use of the latexSymb
function
ang
, which provides the dynamic enclosing for the inner
product, thus avoiding the need to write left
and
right
. The functions br
, sqbr
and
pths
do the same for braces, square brackets and
parentheses respectively.
Finally, there is the function lenv
that spares the user
from writing begin
and end
. The second
argument is a list or a vector, whose components represent different
lines. So, for instance, we could have written also
lenv("align*",
c(
lsymb(ddt(inner(vf1, vf2)), "&=\\\\"),
lsymb("&=", inner(cov.der(vf1), vf2) + inner(vf1, cov.der(vf2)))
)
)
## [1] "\\begin{align*}\\n\\frac{ d \\langle V , W \\rangle }{ dt } &=\\\\\\n&= \\langle \\frac{ D V }{ dt } , W \\rangle + \\langle V , \\frac{ D W }{ dt } \\rangle\\n\\end{align*}"
latex_symb
also exposes il
, which surrounds
expressions in dollar signs, for inline math environments.
On the whole, latexSymb
may not significantly reduce the
amount of code users have to write compared to raw LaTeX. But I do think
it makes it more readable and hence less prone to errors. Users can
mostly write what they mean, not what they want to see.
Additionally, latexSymb
is not limited to RMarkdown.
Actually, it probably makes more sense in .Rtex
documents.
In any case, any format that knit
can handle will do.
Finally, for very complicated equations, R’s piping should make things even more readable.