YAML

At the top of the .Rmd file you downloaded you can see text in between ---:

---
title: "Viridis Demo"
output: html_document
---

This is called the YAML header. YAML is a simple text-based format for specifying data. In R markdown documents YAML can be used for specifying the document metadata (title, author, date). This can be done as below:

---
title: "Viridis demo"
author: "Your name"
date: "3 Feb 2017"
output: html_document
---

The final document will then contain a nicely formatted title, along with the author name and date.

You can leave off the author and date if you want; you can leave off the title, too. Actually, you don’t need to include any of this. But output: html_document tells the rmarkdown package to convert the document to html. Similarly output: pdf_document or even output: word_document, in which case your document will be converted to a PDF or Word .docx file, respectively.

Have a play with changing the YAML output from output: html_document to output: pdf_document or output: word_document and click on the ‘Knit’ button to see how easy it is to generate documents in different formats.

Figure 1: The ‘Knit’ button in R Studio.

YAML becomes more important later when we want to convert between document formats and customise our documents.

Code chunks

A key motivation for using R markdown is facilitating reproducible research and reporting: that our results are accompanied by the data and code needed to produce them.

Code chunks allow you to incorporate your analysis and output in R directly into your reporting.

Code chunks look like this:

{r makesomedata}
x <- rnorm(100)
y <- 2*x + rnorm(100)

When you process the R markdown document, each of the code chunks will be evaluated, and then the code and/or output will be inserted. If the code produces a figure, that figure will be inserted.

It’s important to give each code chunk a name, like rat_graph and RTC_table. Each code chunk needs a unique name. The advantage of giving each chunk a name is that it will be easier to understand where to look for errors, should they occur. Also, any figures or tables that are created will be given names based on the name of the code chunk that produced them.

An R markdown document will have often have many code chunks. They are evaluated in order and the outputs of a code chunk can be used in other parts of your reporting.

In-line code

The other way of incorporating R code directly into your reporting is through ‘in-line’ code. This is not an alternative to using code chunks. The 2 methods serve different purposes. For instance you would not produce a graph or figure using in-line code. This is done through using code chunks as described above.

In-line code is used for incorporating numbers derived from data directly into your writing. Thus, your report should never explicitly include numbers that are derived from the data. Don’t write “There are 168 individuals.” Rather, insert a bit of code that, when evaluated, gives the number of individuals.

In R markdown, in-line code is indicated with `r and `. The bit of R code between them is evaluated and the result inserted.

Code results can be inserted directly into the text of a .Rmd file by enclosing the code with:

`r code_here`  

To write “there are 168 individuals” using in-line code you would do this:

There are `r nrow(my_data)` individuals.

Another example:

The estimated correlation between x and y was `r cor(x,y)`.

R markdown will display the results of in-line code, but not the code itself. In-line code is used to insert information in your document where needed to enable easy updating of the document when new data becomes available.

Writing text

Writing plain text is as simple as writing as in Microsoft word, you are simply incorporating your formatting into your text.

For example:

To make text bold use 2 ** either side of your text (**bold**).

To make italics use ’_’ either side of the text you want _italicized_.

See the R markdown cheatsheet for instructions for other aspects of writing such as creating bullet points etc.

Tables

Making and displaying tables in R markdown is really easy. If wanting to display data in a table we can use the kable function from the knitr package inside a code chunk like this:

_Insert image

This outputs like this:

kable works really well for simple tables, other packages such as xtable are better for more complex tables.

If displaying solely in HTML the DT library has some good options for displaying more complex data. It has some nice interactive features.

require(DT)
datatable(iris)

You’ll see that DT tables have more options for filtering and searching data. This can be helpful if you have a more complicated table you want to show. DT tables don’t work if you want a PDF report.

You can also generate a table in straight markdown.

This looks like this:

| Sepal.Length [^1] | Sepal.Width | Petal.Length | Petal.Width | Species |
|--------------|-------------|--------------|-------------|---------|
| 5.1          | 3.5         | 1.4          | 0.2         | setosa  |
| 4.9          | 3.0         | 1.4          | 0.2         | setosa  |
| 4.7          | 3.2         | 1.3          | 0.2         | setosa  |
| 4.6          | 3.1         | 1.5          | 0.2         | setosa  |
| 5.0          | 3.6         | 1.4          | 0.2         | setosa  |
| 5.4          | 3.9         | 1.7          | 0.4         | setosa  |
| 4.6          | 3.4         | 1.4          | 0.3         | setosa  |
| 5.0          | 3.4         | 1.5          | 0.2         | setosa  |
| 4.4          | 2.9         | 1.4          | 0.2         | setosa  |
| 4.9          | 3.1         | 1.5          | 0.1         | setosa  |
Table: (\#tab:markdowntable) A table about some sort of flower

[^1]: A footnote about Sepal length

But outputs like this:

Markdown tables can be tricky to manually produce. It is easier to use a webtool like http://www.tablesgenerator.com/ to copy a table from word/excel, paste into the webtool and convert to markdon format.

The advantage of using markdown format is that it gives more flexibility for situations where you may need to to more editing inside a table, such as adding footnotes which you would do by inserting [^1] where needed followed by [^1]: A footnote below the table as shown above.

Figures

To display a graph or figure in Microsoft Word or similar you generally have to copy and paste them manually into your document. This lends itself to making mistakes and becomes tedious when your data/presentation changes.

Using R markdown and R and it is really easy to place your figure in your work exactly where you want it to go. If your data changes then it is as simple as ensuring your new data is called to update your figure. Figure 2 tells us simple things about the iris dataset.

plot(iris)

Figure 2: Something to do with flowers

References and citations

R markdown will automatically produce a bibliography from in-line citations.

Figure 3: The ‘Cite’ dialog box in Google Scholar.

You can now refer to this within your document.

Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of @ + the citation identifier from the database.

to add a citation at the end of a sentence:

Blah blah [@doe99]

To refer to one or more citations use ;:

Blah blah [@smith04; @doe99].

To do an in-line citation do the following:

@smith04 says blah.

To add additional information to your citation such as page number use square brackets following the citation:

@smith04 [p. 33] says blah.

When you cite something using the @ symbol and the citation identifier i.e. @smith04 it will automatically appear in the document bibliography. The bibliography will automatically appear at the end of the document. If you finish each document with ##References then the bibliography will appear below the header.

Custom templates

It is possible to create custom made templates for PDF and HTML documents in R markdown. Using a custom made template means the author can produce a fully reproducible document using the correct styling for your organisation.

The DocRR package contains templates for reproducible reporting for the New Zealand Department of Conservation (DOC). The following sections will get you started with the package and walk you through producing PDF and HTML documents from R markdown.

Installing the package

First off open R/RStudio and install the devtools package if you haven’t already.

Paste the code into your R console and run it:

install.packages("devtools")

Now install the DocRR package using:

devtools::install_github('ogansell/DocRR')

Opening a template in RStudio

R Studio supports these templates natively.

You can now load pre-made templates for outputting analysis and reporting in HTML or PDF format. To do this go to File>New File>RMarkdown (Figure 4).

Figure 4: Opening a new rmarkdown file within RStudio.

Go to RMarkdown>From Template and select one of the templates under DocRR.

Select the template you want to load, give your file a name and save it (Figure 5).

Figure 5: The dialog box for saving a template.

Important to note here is that when you save your file a folder structure for your file is automatically made. This is because the templates have some extra files they are dependant on in order to compile (Figure 6).

Figure 6: The folder structure automatically created when a template is loaded.

You’ve now got a template for producing a PDF or HTML report to begin working on (Figure 7). Press the knit button to have a look at what it produces.

Figure 7: A loaded rmarkdown template

After installation

When making PDF or HTML documents a common intermediate step is to knit your document to .docx format. This makes it easy to send to reviewers to get their input. The webshot package is useful in this instance as it includes a screenshot of any html widgets used in the knitted .docx file. It requires installation of the PhantomJS software. This causes installation of the DocRR package to fail on older installations of R so it is recommended to install this manually after installing DocRR. Do this by running the code below in your R console:

webshot::install_phantomjs()

Creating a template outside of RStudio

If you’re not using R Studio it’s still easy to use these templates in base R.

Wrapper functions have been made to make it easy to load a template.

There is one function for each template. The document names are examples only, you can name the .Rmd file whatever you like.

Functions below:

• DocRR::article("myarticle.Rmd")
• DocRR::article_book("myarticle.Rmd")
• DocRR::report("myreport.Rmd")
• DocRR::report_book("myreport.Rmd")
• DocRR::plain_html("myplainwebpage.Rmd")
• DocRR::tab_html("mytabbedwebpage.Rmd")
• DocRR::indicator_html("myindicatorfactsheet.Rmd")

To compile your document use:

rmarkdown::render("my_article/my_article.Rmd")

Remember that you need to point it to the right directory, which means you need to include the folder which was automatically created to host your .Rmd file.

Extra information

You can now start making documents using these templates. It’s important to remember that each template has been designed for a specific output (i.e. PDF articles or reports, plain webpages, web pages with tabbed layout or standardised pages for reporting on biodiversity indicators). Therefore the docarticle or docreport templates won’t work for making webpages and HTML templates won’t work for generating PDF documents. Saying that, all of the templates will output to .docx (word format) provided some of the YAML metadata is altered (we’ll cover this later). This is useful for giving reviewers who aren’t familiar with R or R markdown a version of your document for editing and making comments.

You’ll see there are 2 versions of the article and report PDF templates (i.e. docarticle and docarticle_bookdown). The bookdown package adds the extra utility of cross referencing tables and figures in text. This is especially handy for scientific/technical publications with lots of tables and graphs, but is also useful for images etc.

Using the bookdown templates seems to cause some problems when knitting documents on some computers, so article and report templates have been included which do not use the bookdown package. Guidance on how to cross-reference using bookdown has been provided in each of the templates.To learn more about bookdown go to https://bookdown.org/yihui/bookdown/.

Knitting to PDF

To create your PDF press the ‘knit’ button in R Studio or use the render function in R. Behind the scenes your .Rmd document in converted to a formatted PDF document.