3 Dynamic reporting

One of the most important benefits of writing in R Markdown (aside from being able to compile to other formats than PDF, such as HTML or even Microsoft Word), is the ability to insert results dynamically into your manuscript using code chunks or inline code. This means that you can do analyses directly in your manuscript or, probably better, read file(s) with data, summaries, or results directly into your manuscript and refer to them dynamically.

This is important for two (related) reasons: 1. You avoid initial manual transfer of results from statistical software to manuscript, which reduces the risk of error. 2. If at a later stage you update the analysis files, the results reported in your manuscript are automatically also updated - this again reduces the risk of mistakes, because you don’t need to manually update figures and tables.

In R Markdown syntax, code chunks have the following form (cf. R Markdown: The Definitive Guide):

```{coding_language chunk-label, chunk_options}
# your code goes here
```

Inline code has the form `coding_language #code here`.

3.1 Setup chunks and figure descriptions

The first chunk in an R Markdown document is usually used to load packages and set default chunk options, for example like so (we normally add the chunk option include=FALSE to not include output from this chunk in the manuscript; here we just add message=FALSE to suppress the message that the tidyverse package has been loaded):

library(tidyverse)
knitr::opts_chunk$set(echo = FALSE, 
  message = FALSE, warning = FALSE)
# these options will exclude code output, 
# messages, or warnings in knitted manuscript

In addition, version 1.56 of the ACM Master template adds the ability to provide descriptions of figures via the latex command \Description{my description}. To be able to add these descriptions easily, as well as an option to position chunks vertically, include this code in your initial setup chunk:

# create additional chunk options
hook_chunk = knit_hooks$get('chunk')
knit_hooks$set(chunk = function(x, options) {
  txt = hook_chunk(x, options)
  # add chunk option 'vspaceout' which positions 
  # chunks vertically with \vspace
  if (!is.null(options$vspaceout)) {
    latex_vspace <- paste0("\\1\\\\vspace\\{", 
                      options$vspaceout, "\\}")
    txt <- sub('(\\\\begin[^}]+})', 
                      latex_vspace, txt)  
  }
  # add chunk option 'description' which adds 
  # \Description{...} to figures
  if (!is.null(options$description)) {
    latex_include <- paste0("\\1\\\\Description\\{", 
                      options$description, "\\}")
    gsub('(\\\\includegraphics[^}]+})', 
                      latex_include, txt) 
  } else {
    return(txt)  # pass to default hook
  }
})

You can then add descriptions to your figures by setting description="my description" as a chunk option to images and plots as you will see below.

3.2 Inline results

You might read in a made-up data set of goals scored by basketball players like so:

data <- read_csv("data/fakeBasketData.csv")

We can use inline code to dynamically report properties of this data set. For example, “there are a total of 270 observations of goals scored. The mean number of goals made by any player in a given game is: 17.2555556”.

3.3 Tables

For tables, you could use LaTeX syntax directly. This might be useful if your table itself contains LaTeX syntax, as in Table ??.

However, the power of writing in R Markdown is that you can read in data and automatically create corresponding LaTeX tables. The easiest way is probably to use the kable function. For example, Table 3.1 shows the first 5 rows in our basket data set.

Table 3.1: The first 5 rows of some made-up basket data.
Player goals
Carmelo Anthony 4
Carmelo Anthony 2
Carmelo Anthony 10
Carmelo Anthony 3
Carmelo Anthony 1

You can reference Table 3.1 with \@ref(tab:basket-data).

You can also do arbitrary transformations and analyses of the data before creating a table, as in Table 3.2.

Table 3.2: Summary statistics of goals scored by top players in made-up basketball season.
Player Total goals scored
Blake Griffin 406
Brook Lopez 776
Carmelo Anthony 166
Damian Lillard 808
David Lee 362
David West 492
Demar Derozan 972
Deron Williams 365
Dwyane Wade 312

To set a wider table, which takes up the whole width of the page’s live area, put it in a \table* environment by adding the parameter table.env = 'table*' to the kable function, like in Table 3.3.

Table 3.3: Bigger display of more summary statistics of goals scored by top players in made-up basketball season.
Player Total goals scored Goals per game
Blake Griffin 406 13.533333
Brook Lopez 776 25.866667
Carmelo Anthony 166 5.533333
Damian Lillard 808 26.933333
David Lee 362 12.066667
David West 492 16.400000
Demar Derozan 972 32.400000
Deron Williams 365 12.166667
Dwyane Wade 312 10.400000

3.4 Figures

3.4.1 Static figures

Figures are similarly included via code chunks. You can include arbitrary image files, as in Figure 3.1.

Here's a little pretty fly.

Figure 3.1: Here’s a little pretty fly.

If you don’t give it a caption in the chunk options (with something like fig.cap="My caption"), the figure does not float:

You can resize the figures with the chunk options out.height and out.width, as in Figure 3.2. If you only care about LaTeX output, you can resize e.g. in inches or relative to the column width (out.height = '1in' or out.height = '0.50\\columnwidth'), but if you want to get maximum value out of R Markdown and be able to output also to html formats, set it with a percentage (out.height = '50%' - when outputting to PDF via LaTeX, this will be translated into out.height = '.5\linewidth', see the bookdown reference).

A sample black and white graphic that has been resized with the out.height and out.width chunk options.

Figure 3.2: A sample black and white graphic that has been resized with the out.height and out.width chunk options.

If you need to style text in a caption, or include references in the caption, you have two options (see bookdown on ‘text references’):

  1. set the caption with the chunk option fig.cap and use LaTeX rather than markdown syntax. As the figure caption is a string, you must escape the LaTeX syntax’s \ with another \. The caption for Figure 3.2 would then have been written like this: fig.cap="A sample black and white graphic that has been resized with the \\texttt{out.height} and \\texttt{out.width} chunk options.".

  2. write the caption in the body text with the syntax (ref:chunk_label) My caption here. and then refer to it in the chunk options with fig.cap='(ref:chunk_label) as we did for the resized fly caption.

3.4.2 Dynamic figures

Again, the power of R Markdown is that you can include e.g. plots that are dynamically generated from the underlying data. For example, Figure 3.3 is a simple visualisation of the basket data.

Total number of goals by the top 3 players in made-up basketball season

Figure 3.3: Total number of goals by the top 3 players in made-up basketball season

As with tables, you may want a figure to span two columns. To do this, set the environment to figure* with the chunk option fig.env = 'figure*'. You can fiddle around with the size and aspect ratio of the generated plot with the chunk options fig.height and fig.width. If your image is very large, you may want to restrict its width with out.width.

Distribution of goals scored by game for players in made-up basketball season

Figure 3.4: Distribution of goals scored by game for players in made-up basketball season

3.5 Math Equations

You may want to display math equations in three distinct styles: inline, numbered or non-numbered display. Each of the three are discussed in the next sections. You can use usual LaTeX syntax directly, or R Markdown.

3.5.1 Inline (In-text) Equations

A formula that appears in the running text is called an inline or in-text formula. In LaTeX it is produced by the math environment, which can be invoked by surrounding text with dollar signs: $. You can use any of the symbols and structures, from \(\alpha\) to \(\omega\), available in LaTeX. For example, here’s a nice equation inline: \(\lim_{n\rightarrow \infty}x=0\). If you’re writing in RStudio, you can even hover over it to see the rendered output displayed!

3.5.2 Display Equations

A numbered display equation—one set off by vertical space from the text and centered horizontally—is produced by using LaTeX syntax directly to put the content in an equation environment3. So here’s that nice equation from above: \[\begin{equation} \lim_{n\rightarrow \infty}x=0 \tag{3.1} \end{equation}\]

They can be assigned labels with the syntax (\#eq:label). Refer to the equation with \@ref(eq:display-equation), e.g. see Equation (3.1).

To make an unnumbered display equation, surround the expression with two dollar signs: \[ \lim_{n\rightarrow \infty}x=0 \]

3.6 Theorem-like Constructs

To create theorems, use this syntax (echo=TRUE is only necessary if you’ve set echo=FALSE as the default):

```{theorem, echo=TRUE}
Here is my theorem.
```

For example:

Theorem 3.1 Let \(f\) be continuous on \([a,b]\). If \(G\) is an antiderivative for \(f\) on \([a,b]\), then

\[\int^b_af(t)\,dt = G(b) - G(a).\]

Similarly for definitions, use the syntax

```{definition}
Here is my theorem.
```

For example:

Definition 3.1 If \(z\) is irrational, then by \(e^z\) we mean the unique number that has logarithm \(z\): \[\log e^z = z.\]

In the ACM LaTeX template, pre-defined theorem-like constructs are theorem, conjecture, proposition, lemma and corollary. The pre-defined definition-like constructs are example and definition.

Unsurprisingly, for proofs use

```{proof}
Here is my theorem.
```

For example:

Proof. Suppose on the contrary there exists a real number \(L\) such that

\[\lim_{x\rightarrow\infty} \frac{f(x)}{g(x)} = L.\]

Then

\[ l=\lim_{x\rightarrow c} f(x) = \lim_{x\rightarrow c} \left[ g{x} \cdot \frac{f(x)}{g(x)} \right ] = \lim_{x\rightarrow c} g(x) \cdot \lim_{x\rightarrow c} \frac{f(x)}{g(x)} = 0\cdot L = 0, \] which contradicts our assumption that \(l\neq 0\).

  1. In fact, you can use any arbitrary LaTeX syntax directly in your .Rmd document.