Writing template

import sys
import pandas as pd
import matplotlib as mpl

sys.path.append("../../src/python")
mpl.rc_file("../../assets/vizz.mplstyle")

# from cards import sync_projects
# pd.read_csv("../../data/3class_data.csv")

Combining R Markdown with typesetting functionality from the Bookdown package and Distill web publishing format provides a comprehensive set of tools for composing web documents. In this high-level reference I cover the tools that I find most useful for writing organized, easily referenced, math-heavy documents. The examples are arbitrary, only meant to illustrate the syntax. The LaTeX and markdown syntax are not explained. For each example I provide the raw text followed by the rendered output.

1 Definition, theorem, proof

The familiar math textbook refrain. Here’s the Bookdown syntax for definition, theorem, and proof environments, respectively.

Definition

Definition 1 (Disjoint sets) Two sets \(A_1\) and \(A_2\) are disjoint if their intersection \(A_1 \cap A_2 = \emptyset\), where \(\emptyset\) is the empty set. We say that \(n\) sets \(A_1, A_2, ..., A_n\) are disjoint if \(A_i \cap A_j = \emptyset\) for \(i! = j\).

Theorem

Theorem 1 (Pythagorean theorem) Given a right triangle, if \(c\) denotes the length of the hypotenuse and \(a\) and \(b\) the lengths of the other two sides, then \[a^2 + b^2 = c^2.\]

Table 2.1 on this page from Authoring Books with R Markdown lists all the other available theorem environments and their respective keywords.

Proof

Proof (Pythagorean theorem). Let \(x, y\) be …

… Thus, \[a^2 + b^2 = c^2,\] as desired.

\[ \tag*{$\square$} \]

Automatic numbering

The nice thing about Bookdown is that it will automatically number definitions and theorems so that you can easily cross-reference them later on (see the Cross-references section below). Just replace the name following the # (pyth-thm in the example below) with a unique label (containing no spaces) that will be convenient to reference.

Definition 2 (Continuous map) A continuous map is a continuous function between two topological spaces.

Notice that the definition’s number was automatically incremented from the previous definition.

2 Assorted math examples

Here is an assortment of LaTeX examples along with their output.

Brackets and braces

\[ ( a ), [ b ], \{ c \}, | d |, \| e \|, \langle f \rangle, \lfloor g \rfloor, \lceil h \rceil, \ulcorner i \urcorner, / j \backslash \]

\[ ( \big( \Big( \bigg( \Bigg( \]

Fractions

\[ \begin{equation} x = a_0 + \cfrac{1}{a_1 + \cfrac{1}{a_2 + \cfrac{1}{a_3 + \cfrac{1}{a_4} } } } \end{equation} \]

The \left( / \right) command encloses its contents in big brackets.

\[ \frac{ \begin{array}[b]{r} \left( x_1 x_2 \right) \\ \times \left( x'_1 x'_2 \right) \end{array} }{ \left( y_1y_2y_3y_4 \right) } \]

Calculus

\[ \int_0^\infty \mathrm{e}^{-x} ~ \mathrm{d}x \]

\[ \int\limits_a^b \sin(x) ~ \mathrm{d}x \]

\[ \sum_{\substack{0<i<m \\ 0<j<n}} P(i,j) \]

Linear algebra

\[ \begin{matrix} a & b & c \\ d & e & f \\ g & h & i \end{matrix} \]

\[ A_{m,n} = \begin{pmatrix} a_{1,1} & a_{1,2} & \cdots & a_{1,n} \\ a_{2,1} & a_{2,2} & \cdots & a_{2,n} \\ \vdots & \vdots & \ddots & \vdots \\ a_{m,1} & a_{m,2} & \cdots & a_{m,n} \end{pmatrix} \]

\[ X = \begin{bmatrix} x_1 & y_1 \\ x_2 & y_2 \\ x_3 & y_3 \end{bmatrix} \]

The ~ symbol represents a whitespace character.

\[ \begin{align} X & = \left[\begin{matrix} a & b & c \\ d & e & f \\ g & h & i \end{matrix}\right] \left[\begin{matrix} y^{(1)} \\ y^{(2)} \\ y^{(3)} \end{matrix}\right] \\ & = \left[\begin{matrix} | & | & | \\ y^{(1)} ~ \vec{x}_1 & y^{(2)} ~ \vec{x}_2 & y^{(3)} ~ \vec{x}_3 \\ | & | & | \end{matrix}\right] \in \mathbb{R^3} \end{align} \]

Probability

\[ \left(\! \begin{array}{c} n \\ r \end{array} \!\right) = \frac{n!}{r!(n-c)!} \]

\[ \begin{equation} \phi \left(x; \mu, \sigma \right) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp \left( - \frac{\left(x - \mu\right)^2}{2 \sigma^2} \right) \end{equation} \]

3 Math blocks

Annotations

\[ \underbrace{ \ln \left( \frac{5}{6} \right) }_{\simeq -0.1823} < \overbrace{ \exp \left( \frac{1}{2} \right) }^{\simeq 1.6487} \]

Numbered equations

Unlike in pure LaTeX, in bookdown we must manually assign labels to every line that should have a number. I do so for significant passages, steps, and equations. Here is an example of a numbered equation:

\[ \begin{equation} \mathbb{P} \left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k} \end{equation} \tag{1}\]

Numbered blocks

Here is an example from the Bookdown documentation. It illustrates how to display a block of math with multiple lines that share a single number and label. We use the LaTeX split environment to split the number across lines and wrap it all in double dollar signs to tell R to treat it as math rather than raw text. To give the block a number we add an (\#eq:<equation-label>) after closing the split environment with \end{split}. Just replace the text after the \#eq: prefix with a memorable label of your choice.

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

Some additional notes:

• Each new line is preceded by a \\ operator.
• Each aligned expression begins with the & operator.

Inline notes

We can number lines individually by using the LaTeX align environment and adding a unique (\#eq:<equation-label>) at the end of every line that should have a number. Additionally, we can add in-line comments by placing && followed by (<my LaTeX-formatted comment>) at the end of the line, before the number label. As with our use of the & operator to align successive lines of math, the && operator tells the LaTeX compiler to align comments, but to do so to the right of the aligned math.

We use scriptstyle to make the inline text smaller. Other custom display options are detailed here (by Overleaf).

\[ \begin{align} \sum_{i=1}^{n} \left( X_i - \overline{X} \right) & = \sum_{i=1}^{n}X_i - \sum_{i=1}^{n} \overline{X} &&& \scriptstyle{\text{(comment 1)}} \tag{a} \\ & = \sum_{i=1}^{n} X_i - n \overline{X} &&& \scriptstyle{\left(\begin{array}{c} \text{comment 2 has symbols: } \int_{a}^{b} 4 \pi r^2 \\ \text{... and carries over to a second line. }\end{array}\right)} \\ & = \sum_{i=1}^{n}X_i - \sum_{i=1}^{n}X_i \\ & = 0 \tag{b} \end{align} \tag{3}\]

4 Code blocks

We can include some nicely formatted Python code:

# Display the Fibonacci sequence
nterms = 5

n1, n2 = 0, 1
count = 0

if nterms <= 0:
  print("Please enter a positive integer")

elif nterms == 1:
  print("Fibonacci sequence up to", nterms, ":")
  print(n1)

else:
  print("Fibonacci sequence:")
  while count < nterms:
    print(n1)
    nth = n1 + n2
    n1 = n2
    n2 = nth
    count += 1

Fibonacci sequence:
0
1
1
2
3

Tables

We can also display data frames as nicely formatted tables. This example uses kable to render the built-in mtcars dataset as a static table:

library(knitr)
kable(head(mtcars))

Table 1: This is a table caption

	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21.0	6	160	110	3.90	2.620	16.46	0	1	4	4
Mazda RX4 Wag	21.0	6	160	110	3.90	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108	93	3.85	2.320	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258	110	3.08	3.215	19.44	1	0	3	1
Hornet Sportabout	18.7	8	360	175	3.15	3.440	17.02	0	0	3	2
Valiant	18.1	6	225	105	2.76	3.460	20.22	1	0	3	1

Paged tables

And this example uses the paged_table function to generate a table with its columns spread out over several clickable pages:

library(rmarkdown)
paged_table(mtcars)

Table 2: This is another table caption

Use the knitr option layout="l-body-outset" to make the figure or table span the width of the page. More information here and here (from the Distill for R Markdown documentation).

5 References

Cross-references

Now that we have some labelled equations and images, we can create hyperlinked references to them. Here are some examples:

Target	Example	Raw
Bookdown environment	Theorem 1.	@thm-pyth
Math block	Equation 2.	@eq-var-beta
Figure or image	Table 1.	@tbl-1
Section	Section 2.	@sec-math-elements

Table 2.1 on this page from Authoring Books with R Markdown lists the label prefixes for all other available theorem environments (we use the thm prefix here).

Note: The section 1 header is followed by the label {#math-elements}.

In-text citations

Provided you have stored the sources you wish to formally cite in a bibtex document, you can cite them in-text as follows and they will automatically appear, with proper formatting, in the ‘References’ section at the bottom of your document:

(James et al. 2013)

This is the bibtex entry in my .bib file to which this example refers:

@book{james2013introduction,
  title={An introduction to statistical learning},
  author={James, Gareth and Witten, Daniela and Hastie, Trevor and Tibshirani, Robert},
  volume={112},
  year={2013},
  publisher={Springer}
}

Footnotes

This is a manual citation with a footnote:

(Axler, 2019)¹.

At the bottom of my document I have a corresponding footnote entry that looks like:

[^1]: Axler, S. (1997). *Linear algebra done right*.
Springer Science & Business Media.

6 Text formatting

Here are some additional text formatting tricks:

Asides

I have been using these throughout. Here’s how to create them:

This content will appear in the gutter of the article.

Scripts, strikethrough

A subscript and a superscript	A~subscript~and a^superscript^
This is a strikethrough	This is a ~~strikethrough~~

7 Concluding remarks

And that’s it! As we’ve seen, R Markdown is a powerful integrated tool for text editing, coding, and mathematical typesetting. Combined with the math environments from Bookdown and the handy annotation tools from Distill, we have a fully capable suite of tools at our fingertips for producing beautiful, well-referenced, web-friendly mathematical documents.

sI <- sessionInfo()
print(sI, RNG = FALSE, locale = FALSE)
## R version 4.3.3 (2024-02-29)
## Platform: aarch64-apple-darwin20 (64-bit)
## Running under: macOS Ventura 13.5.1
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] rmarkdown_2.26 knitr_1.45    
## 
## loaded via a namespace (and not attached):
##  [1] digest_0.6.34     fastmap_1.1.1     xfun_0.42         Matrix_1.6-5     
##  [5] lattice_0.22-5    reticulate_1.35.0 htmltools_0.5.7   png_0.1-8        
##  [9] cli_3.6.2         vctrs_0.6.5       grid_4.3.3        withr_3.0.0      
## [13] compiler_4.3.3    rstudioapi_0.15.0 tools_4.3.3       evaluate_0.23    
## [17] Rcpp_1.0.12       yaml_2.3.8        rlang_1.1.3       jsonlite_1.8.8   
## [21] htmlwidgets_1.6.4

# import watermark

# %load_ext watermark
# %watermark -u -n -v -iv -w -p pandas,numpy,matplotlib,seaborn,tensorflow

References

James, Gareth, Daniela Witten, Trevor Hastie, and Robert Tibshirani. 2013. An Introduction to Statistical Learning. Vol. 112. Springer.

Footnotes

1. Axler, S. (1997). Linear algebra done right. Springer Science & Business Media.