11.5 The anatomy of a Notebook / R Markdown file

When you create a file, a helpful template is provided to get you started. Figure 11.3 shows the essential elements of a Notebook file and how these translate to the HTML preview.

11.5.1 YAML header

Every Notebook and Markdown files requires a “YAML header”. Where do they get these terms you ask? Originally YAML was said to mean Yet Another Markup Language, referencing its purpose as a markup language. It was later repurposed as YAML Ain’t Markup Language, a recursive acronym, to distinguish its purpose as data-oriented rather than document markup (thank you Wikipedia).

This is simply where many of the settings/options for file creation are placed. In RStudio, these often update automatically as different settings are invoked in the Options menu.

The Anatomy of a Notebook/Markdown file. Input (left) and output (right)

FIGURE 11.3: The Anatomy of a Notebook/Markdown file. Input (left) and output (right)

11.5.2 R code chunks

R code within a Notebook or Markdown file can included in two ways:

  • in-line: e.g. The total number of oranges was R sum(fruit$oranges);
  • as a “chunk”.

R chunks are flexible, come with lots of options, and you will soon get into the way of using them.

Figure 11.3 shows how a chunk fits into the document.

This is off-putting, but just go with it for now. You can type it manually, or use the Insert button and hit R. You will also notice that chunks are not limited to R code. It is particularly helpful that Python can also be run in this way.

Chunks can be named which is sometimes useful for debugging, but is not essential for the code to run, e.g. ```{r table1-demographics}.

When doing an analysis in a Notebook you will almost always want to see the code and the output. When you are creating a final document you may wish to hide code. Chunk behaviour can be controlled via the Chunk Cog on the right of the chunk (Figure 11.3) which makes this very easy.

Table 11.1 shows the various permutations of code and output options that are available. The code is placed in the chunk header but the options fly-out now does this automatically, e.g.

TABLE 11.1: Chunk output options when knitting an R Markdown file.
Option Code
Show output only echo=FALSE
Show code and output echo=TRUE
Show code (don’t run code) eval=FALSE
Show nothing (run code) include=FALSE
Show nothing (don’t run code) include=FALSE, eval=FALSE

Hide warnings warnings=FALSE
Hide messages messages=FALSE

11.5.3 Setting default chunk options

We can set default options for all our chunks at the top of our document. by adding and editing knitr::opts_chunk$set(echo = TRUE) at the top of the document.

11.5.4 Setting default figure options

It is possible to set different default sizes for different output types by including these in the YAML header (or using the document cog):

The YAML header is very sensitive to the spaces/tabs, so make sure these are correct.

11.5.5 Markdown elements

Markdown text can be included as you wish around your chunks. Figure 11.3 shows an example of how this can be done.
This is a great way of getting into the habit of explicitly documenting your analysis. When you come back to a file in 6 months time, all of your thinking is there in front of you, rather than having to work out what on Earth you were on about from a collection of random code!