---
title: "Using latex2exp"
author: "Stefano Meschiari"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using latex2exp}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---
```{r, include=FALSE}
knitr::opts_chunk$set(fig.width = 7, fig.height = 5, fig.retina = 2)
library(latex2exp)
library(reactable)
library(purrr)
library(dplyr)
library(ggplot2)
library(tibble)
```

## Usage
The `TeX` function takes a LaTeX string, parses it, and returns the closest [plotmath expression](http://stat.ethz.ch/R-manual/R-patched/library/grDevices/html/plotmath.html) suitable for use in graphics. The return value of `TeX()` can be used anywhere a plotmath expression is accepted, including plot labels, legends, and text for both base graphics and ggplot2.

Here's a simple example:

```{r, eval=FALSE}
# Use raw strings, no need to escape backslashes.
TeX(r"(\textbf{Euler's identity} is $e^{i\pi} + 1 = 0$.)")
```

In this example, `\textbf{}` is used to mark a fragment of text as bold,
`$` introduces inline math mode, `^{}` typesets its contents as superscript,
and `\pi` typesets the letter $\pi$.

Starting with R 4.0, it is recommended to use the new raw string literal syntax (see `?Quotes`). The syntax looks like `r"(...)"`, where `...` can contain any character sequence, including `\`.

Another option is to escape the backslash character (`\`) for LaTeX commands, such that the  command will be written as `\\command` rather than `\command`. This will also work on versions of R older than 4.0:

```{r, eval=FALSE}
# Equivalent to the previous code fragment.
# Use regular strings, but escape the backslashes.
TeX("\\textbf{Euler's identity} is $e^{i\\pi} + 1 = 0$.")
```

You can quickly preview what a translated LaTeX string would look like by using `plot`: 

```{r plot-formula, fig.height=2, fig.width=5}
plot(TeX(r'(A $\LaTeX$ formula: $\frac{2hc^2}{\lambda^5}\frac{1}{e^{\frac{hc}{\lambda k_B T}} - 1}$)'), cex = 2, main = "")
```


The following example shows plotting in base graphics:
```{r base-plot, warning=FALSE}
x <- seq(0, 4, length.out = 100)
alpha <- 1:5

plot(x, xlim = c(0, 4), ylim = c(0, 10), 
     xlab = 'x', ylab = TeX(r'($\alpha  x^\alpha$, where $\alpha \in \{1 \ldots 5\}$)'), 
     type = 'n', main = TeX(r'(Using $\LaTeX$ for plotting in base graphics!)', bold = TRUE))

for (a in alpha) {
  lines(x, a*x^a, col = a)
}

legend('topleft', 
       legend = TeX(sprintf(r'($\alpha = %d$)', alpha)), 
       lwd = 1, 
       col = alpha)
```

This example shows plotting in [ggplot2](https://ggplot2.tidyverse.org):

```{r ggplot, warning=FALSE}
x <- seq(0, 4, length.out = 100)
alpha <- 1:5
data <- map_df(alpha, ~ tibble(v = .*x^., x = x, alpha = .))

p <- ggplot(data, aes(x = x, y = v, color = as.factor(alpha))) +
    geom_line() + 
    ylab(TeX(r'($\alpha  x^\alpha$, where $\alpha \in 1\ldots 5$)')) +
    ggtitle(TeX(r'(Using $\LaTeX$ for plotting in ggplot2. I $\heartsuit$ ggplot!)')) +
    coord_cartesian(ylim = c(-1, 10)) +
    guides(color = guide_legend(title = NULL)) +
    scale_color_discrete(labels = lapply(sprintf(r'($\alpha = %d$)', alpha), TeX)) 
    # Note that ggplot2 legend labels must be lists of expressions, not vectors of expressions

print(p)
```


Here are a few examples of what you can do with **latex2exp**:

```{r examples, fig.width=7, fig.height=6}
latex2exp_examples(cex = 0.9)
```