# Installation

The mat2tex package was written to facilitate the combination of matrices and LATEX$\LaTeX$ code. To install the mat2tex package from github enter

library(devtools)
install_github("markheckmann/mat2tex")

into the console. Windows users have to make sure that Rtools are installed.

# Basic usage

mat2tex is a mini-language with several operators and functions to allow to combine LaTeX code and R objects. Suppose you have the matrix A.

set.seed(1)
A <- matrix(runif(4), 2)

Know we want to create a LaTeX chunk inside an Sweave or a Rmarkdown file that contains an equation like this one:

A=(0.270.370.580.91)

Using mat2tex you can achieve this very easily, by inserting the following code into a knitr chunk with the options echo=FALSE and results='asis'

"$$A = " %_% A %_% "$$"

A=(0.270.370.570.91)

or equivalently

xx("A =", A)

A=(0.270.370.570.91)

In the example above we used a string containing plain LaTeX code "$$\\mathbf{A} = " and concatated it with the matrix A and another plain LaTeX chunk using the %_% operator. The operator can be used to concatenate chunks. Alternatively, you can use the xx function which will concatenate all the chunks given as arguments and seperated by comma automatically. The math environment we added by hand above ($$) is added automatically here.

## Creating chunks using Functions and operators

mat2tex is a mini-language consisting of functions to generate code chunks and several operators to combine the chunks. Most of the function names are acronymes starting with an x which stands for TeX or LaTeX.

function description
xc LaTeX code. Convert R object into chunk that can be concatenated.
xm Convert to LaTeX matrix
xmt Convert to LaTeX matrix plus transpose sign
xb Begin LaTeX math environment
xe End LaTeX math environment
xx A function that allows to enter all code chunks seperated by comma.
lp Create left parenthesis
rp Create right parenthesis
s Insert custom width space into formula.
operator description
%_% Concatenate LaTeX chunks.
%_1% Same as %_% but adds extra horizontal space. The operator also is defined for numbers up to five with an increasing space, i.e. %_2%, %_3% etc.
+ Same as %_% but only applicabale if unambigous. Better use %_% to be on the safe side.

## Examples

The following codes begins a new math environment ($$) and ends it again ($$). In order to convert the text into a chunk that can be concatenated, the function xc is used. Inside we use the function xm to convert the matrix A into LaTeX codem in this case with 3 digits.

xc("$$") %_% xm(A, 3) %_% xc("$$")

(0.2660.3720.5730.908)

In most cases you can simply omit the xc function when using the %_% operator. The chunks are then automatically converted. The following code is identical to the one before.

"$$" %_% xm(A, 2) %_% "$$"

(0.270.370.570.91)

You can even omit the xm function. To convert the matrix into a LaTex code chunk the function xm is invoked. As no arguments are specified in this case, the default values (see section defaults) are used.

"$$" %_% A %_% "$$"

(0.270.370.570.91)

An alternative formulation which is equivalent is to use the xx function to concatenate the code chunks. This function allows to enter the chunks seperated by commas and will be the most convenient option in most cases. The nice feature is, that it automatically adds a math environment specified via the argument e.

xx(xm(A, 2), e=1)

(0.270.370.570.91)

As e=1 and digits=2 is the default anyway, we can reduce this to

xx(A)

(0.270.370.570.91)

Let’s explore more arguments. We can change the type of brackets that are produced using the mtype argument.

"$$" %_% xm(A, mtype = "bm") %_% "$$"

[0.270.370.570.91]

The available bracket types (this time using the xx function) are

xx( xm(A, m="m"), xm(A, m="p"), xm(A, m="bm"),
xm(A, m="B"), xm(A, m="v"), xm(A, m="V"))   

0.270.370.570.91(0.270.370.570.91)[0.270.370.570.91]{0.270.370.570.91}0.270.370.570.910.270.370.570.91

Rmarkdown knows two environments: $$ which we used above and the inline environment . To include a formula inline like this 1+1=2$1 + 1 = 2$ in the midth of a sentence, you can use the same knitr settings, i.e. echo=FALSE and results='asis'. But make sure there are no blank lines between the text and the knitr chunk, otherwise the code will not be inline. ## More examples To construct a LaTeX expressions you can combine plain LaTeX text chunks, matrices and the output from several functions shown above to create more complex output. The SVD of A$A$ is d <- svd(A) "$$ A =" %_% A %_% "= UDV^T =" %_% d$u %_% diag(d$d) %_% d$v %_% "^T" %_% "$$" A=(0.270.370.570.91)=UDVT=(0.540.840.840.54)(1.170.000.000.02)(0.390.920.920.39)T or using the xx function xx("A =", A, "= UDV^T =", du, diag(dd), xmt(dv), e=1) A=(0.270.370.570.91)=UDVT=(0.540.840.840.54)(1.170.000.000.02)(0.390.920.920.39)T Let’s create a multiple rows example using the line break function lb to insert linebreaks (if or not this works depends on your math environment). g <- rep(1, 2) I <- diag(2) "$$" %_% pl() %_% "I - 11^T" %_% pr() %_% "A" %_% lb() %_% "=" %_% pl() %_% xm(I, 0) %_% "-" %_% xm(g, 0) %_% xm(t(g), 0) %_% pr() %_% A %_% lb() %_% "=" %_% xm(I - g %*% t(g), 0) %_% A %_% lb() %_% "=" %_% xm((I - g %*% t(g)) %*%A) %_% "$$"  (I11T)A=((1001)(11)(11))(0.270.370.570.91)=(0110)(0.270.370.570.91)=(0.370.270.910.57) or xx(pl(), "I - 11^T", pr(), "A", lb(), "=", pl(), xm(I, 0), "-", xm(g, 0), xm(t(g), 0), pr(), A, lb(), "=", xm(I - g %*% t(g), 0), A, lb(), "=", xm((I - g %*% t(g)) %*%A), e=1) (I11T)A=((1001)(11)(11))(0.270.370.570.91)=(0110)(0.270.370.570.91)=(0.370.270.910.57) ## Changing the default settings You can change several options that will affect the output. As default e.g. numeric values are rounded to two digits and round brackets are used to display the matrices and the $$ math environment is used. You can retrieve the current default settings by typing. mat2tex_options() $digits
[1] 2

$round [1] TRUE$mtype
[1] "pmatrix"

$mathenvir [1] 1$transpose.sign
[1] "^{T}"

$na [1] "" Suppose we want to have rectangular brackets and values rounded to four digits. We can achieve that by setting the xm arguments accrodingly. xx(xm(A, digits=4, mtype="bmatrix")) [0.26550.37210.57290.9082] If we want to use these settings as the default and apply these settings to all matrices can instead change the default values. To change the settings enter name = value pairs seperated by a comma. To change the default number of digits to 4 and the type of matrix to bmatrix ), i.e. rectangular, type opts <- mat2tex_options(digits=4, mtype="bmatrix") As a result the matrix A$A$ will know look like this xx(A) [0.26550.37210.57290.9082] To recreate the former settings again (note that the old settings were saved in opt) we can supply them as the argument to mat2tex_options and we get the old default back. mat2tex_options(opts) xx(A) (0.270.370.570.91) # Working with .Rmd and .Rnw files It makes sense to change the default settings according to the file type you work with. Working with .Rmd files using mathenviron=1 i.e. $\$ (which is the default) is suitable.

mat2tex_options(mathenvir=1)

For .Rnw you may want to change it to mathenviron=3, i.e. to the equation environment to get numbered equations.

mat2tex_options(mathenvir=3)

Have a look at the .Rnw vignette for more information.