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.
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.
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.
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.

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).

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’):
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."
.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 withfig.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.

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
.

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:
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\).In fact, you can use any arbitrary LaTeX syntax directly in your .Rmd document.↩