3.8 Equations

Can use $...$ ($$...$$ for blocks) or \(...\) (\[...\] for blocks) to enclose equations. Difference:

  • $...$ provides rendered equation previews in RStudio.
  • \(...\) does not have previews.

Rstudio equation previews do NOT work well with indented equations. \(\rightarrow\) reduce indentation

如果公式缩进，Rstudio 公式预览功能可能不识别。在不影响理解的前提下，减少不必要的缩进以便预览公式。

Multi-case functions using \begin{cases}

\begin{align*}
I_t = 
\begin{cases}
1 & \text{if } r_t>0 \\
0 & \text{if } r_t\leq0
\end{cases}
\end{align*}

will render as

\[\begin{align*} I_t = \begin{cases} 1 & \text{if } r_t>0 \\ 0 & \text{if } r_t\leq0 \end{cases} \end{align*}\]

For equation numbering support in bookdown you need to assign labels.

For equation numbering support in bookdown::pdf_document2 you need to assign labels. Default behavior is not adding numbering.

  • Use \begin{equation}...\end{equations} or \begin{align}...\end{align} environments.

    • Use (\#eq:eq1) or \label{eq:eq1} to add labels.
    • Automatically add numbering.
    • Drawback is that rmd does not have preview of equations.

  • Do NOT enclose the environments in double dollar signs $$. Otherwise, no label is added, but cross-references still show up.

    • $$ do not add numbering automatically.

    • But in bookdown::html_document2, it is ok to use

      $$
\begin{equation} 
\hat{\beta}_{\text{OLS}} = \left(\sum_{i=1}^n x_i x_i' \right)^{-1} \left(\sum_{i=1}^n x_i y_i \right) . 
(\#eq:simple-lm)
\end{equation}
$$

      Assign labels using the syntax (\#eq:label).

      The above equation will be rendered as

      \[ \begin{equation} \hat{\beta}_{\text{OLS}} = \left(\sum_{i=1}^n x_i x_i' \right)^{-1} \left(\sum_{i=1}^n x_i y_i \right) . \tag{3.3} \end{equation} \]

      Then reference with Eq. \@ref(eq:simple-lm), e.g., see Eq. (3.3).

  • Use \@ref(eq:eq1) (note this uses parentheses) or the Latex command \eqref{eq:eq1} (this uses curly braces) to cite the equation label.

Load the dataset and calculate the monthly return in month $r$ ($r_t$) as

\begin{equation}
r_t = \frac{P_t-P_{t-1}}{P_{t-1}} = \frac{P_t}{P_{t-1}}-1 , 
(\#eq:eq1)
\end{equation}

where $P_t$ is the adjusted price in month $t$. 

Test equation1 \@ref(eq:eq1).

Test equation2 \eqref{eq:eq1}.

eqn numbering in bookdown

  • Multilined equations.

    • Use the split environment inside equation so that all lines share the same number.

      Note that the label (\#eq:label) must be placed after \end{split}.

      \begin{equation} 
\begin{split}
\mathrm{Var}(\hat{\beta}) & =\mathrm{Var}((X'X)^{-1}X'y)\\
& =(X'X)^{-1}\sigma^{2}
\end{split}
(\#eq:var-beta)
\end{equation}

      will be rendenered as

      \[ \begin{equation} \tag{3.4} \begin{split} \mathrm{Var}(\hat{\beta}) & =\mathrm{Var}((X'X)^{-1}X'y)\\ & =(X'X)^{-1}\sigma^{2} \end{split} \end{equation} \]

      Note that the label (\#eq:var-beta) must be placed before \begin{split} or after \end{split}, i.e., outside the split environment.

      Then reference with Eq. \@ref(eq:var-beta), e.g., see Eq. (3.4).

    • Each line in the align environment will be assigned an equation number. We suppressed the number of the first line in the previous example using \notag.

Naming conventions for equation labels in bookdown:

  • Equation labels must start with the prefix eq:.

    In qmd, eq labels start with eq-.

  • All labels must only contain alphanumeric characters, :, -, and/or /.

  • Do NOT use underscore _. ❌

    Note that qmd supports underscores in eq labels.

If you want to provide a specific number to the equation, you can use \tag{XX.XX}.

  • With LaTeX

    LaTeX allows custom labels.

    \begin{align} \label{eq:my-label-latex} \tag{my label latex}
\frac{p(x)}{1-p(x)} = \exp (\beta_0+\beta_1 x) \,.
\end{align}

    will be rendered as

    \[\begin{align} \label{eq:my-label-latex} \tag{my label latex} \frac{p(x)}{1-p(x)} = \exp (\beta_0+\beta_1 x) \,. \end{align}\]

    My specific label here, see eq \(\eqref{eq:my-label-latex}\) (\eqref{eq:my-label-latex}).

    Cross reference using bookdown does NOT work: @ref{eq:my-label-latex} (eq. \@ref(eq:my-label-latex)).

  • With bookdown

    bookdown does NOT support custom tag though. Don’t use this.

    \begin{align}
\frac{p(x)}{1-p(x)} = \exp (\beta_0+\beta_1 x) \,.
(\#eq:my-label-bookdown) \tag{my label bookdown}
\end{align}

    will be rendered as

    \[ \begin{align} \tag{3.5} \tag{my label bookdown} \frac{p(x)}{1-p(x)} = \exp (\beta_0+\beta_1 x) \,. \end{align} \]

    The equation does not show properly; there are two \tag{}. My specific label here, see eq (3.5) (eq. \@ref(eq:my-label-bookdown)).

Color eqns using \color{#00CC66}{...}.

But sometime everything follows gets colored. You may want to use {\color{#00CC66} ... } instead.

$$
\color{#008B45}{Y_t} = I_tI_{t-1} + (1-I_t)(1-I_{t-1})
$$

\[\begin{align*} {\color{red}Y_t} = I_tI_{t-1} + (1-I_t)(1-I_{t-1}) \end{align*}\]

  • This only works for color names, not hex codes starting with #, because html requires the # followed by 6 characters to define a color, but LaTeX package xcolor specifically excludes # in color specifications.

  • Here is an (only works for LaTeX).

A workaround: We can write a custom R function to insert the correct syntax depending on the output format using the is_latex_output() and is_html_output() functions in knitr as follows:

colorize <- function(x, color) {
  if (knitr::is_latex_output()) {
    sprintf("\\textcolor{%s}{%s}", color, x)
  } else if (knitr::is_html_output()) {
    sprintf("<span style='color: %s;'>%s</span>", color,
      x)
  } else x
}

We can then use the code in an inline R expression `r colorize("some words in red", "red")`, which will create some words in red, which works for both html and .

Mathjax

https://bookdown.org/yihui/rmarkdown/html-document.html#mathjax-equations

RStudio IDE comes with Mathjax 2.7 bundled. This is used by rmarkdown when local mode is used for example. Path is stored in Sys.getenv("RMARKDOWN_MATHJAX_PATH").

> Sys.getenv("RMARKDOWN_MATHJAX_PATH")
[1] "/Applications/RStudio.app/Contents/Resources/app/resources/mathjax-27"

> rmarkdown:::mathjax_config()
[1] "MathJax.js?config=TeX-AMS-MML_HTMLorMML"

For online mode, rmarkdown uses https://mathjax.rstudio.com/latest/ with config MathJax.js?config=TeX-AMS-MML_HTMLorMML for now.

Default configuration used by the rmarkdown package is given by rmarkdown:::mathjax_config(). As of rmarkdown v2.1, the function returns “MathJax.js?config=TeX-AMS-MML_HTMLorMML”. This configures Mathjax to HTML-CSS.

Change Mathjax configuration to CommonHTML using the following codes.

---
title: "Trouble with MathJax"
output: 
  html_document:
    mathjax: "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS_CHTML.js"
    self_contained: false    
---

By default, MathJax scripts are included in HTML documents for rendering LaTeX and MathML equations. You can use the mathjax option to control how MathJax is included:

  • Specify "default" to use an HTTPS URL from a CDN host (currently provided by RStudio).
  • Specify "local" to use a local version of MathJax (which is copied into the output directory). Note that when using "local" you also need to set the self_contained option to false.
  • Specify an alternate URL to load MathJax from another location. To use a self-hosted copy of MathJax.
  • Specify null to exclude MathJax entirely.

Q: Why my eqns are not rendered?

A: MathJax is unlikely to work offline. Check internet connection.

You load MathJax into a web page by including its main JavaScript file into the page. That is done via a <script>tag that links to the MathJax.js file. To do that, place the following line in the <head> section of your document.

For example, if you are using the MathJax distributed network service, the tag might be

<script type="text/javascript"
   src="http://cdn.mathjax.org/mathjax/latest/MathJax.js">
</script>

MathJax is available as a web service from cdn.mathjax.org, so you can obtain MathJax from there without needing to install it on your own server. The CDN is part of a distributed “cloud” network, so it is handled by servers around the world. That means that you should get access to a server geographically near you, for a fast, reliable connection.

The CDN hosts the most current version of MathJax, as well as older versions, so you can either link to a version that stays up-to-date as MathJax is improved, or you can stay with one of the release versions so that your pages always use the same version of MathJax.

3.8.1 RStudio Equation Live Preview

Q: How to define custom macros that can be used in live equation preview in RStudio?

A: Go to /Applications/RStudio.app/Contents/Resources/app/resources/mathjax-27/config/TeX-MML-AM_CHTML.js, add your custom macros as follows.

MathJax.Hub.Config({
  extensions: ['[a11y]/accessibility-menu.js'],
  TeX: {
    Macros: { // define TeX macros
      RR: "{\\bf R}",
      bold: ["{\\bf #1}",1],
      btheta: "\\boldsymbol{\\theta}",
      bAlpha: "\\boldsymbol{\\Alpha}",
    }
  },
});

RStudio DevTools

RStudio functions like a web browser, you can use a web inspector to inspect every element of the appearance. Simply right-click pretty much anywhere on RStudio, and hit “Inspect Element” and RStudio DevTools will appear.

The MathJax supporting files can be found in Sources → Page → Electron Isolated Context → mathjax.

You will see MathJax.js?config=TeX-MML-AM_CHTML is loaded to parse and enable live previews of equations.

The user configuration file is located under config/. You will see your custom defined macros here.