R Markdown is a powerful notebook interface that allows code to be placed in a document alongside text. RStudio have created a short guide here with more information.
The benefits of R Markdown are:
- You can include the results of your analysis directly in your reports without cutting and pasting. This reduces the potential for errors.
- There is a direct link between your analysis and the report. When you update the analysis, so will the report.
- Document formatting is automatic when you write your report using the markdown syntax. The cheat sheet here summarises the markdown syntax.
Set up R Markdown
To set up R Markdown run the following code in the console
> install.packages("rmarkdown")
If you want to create PDF documents you will need to also install LaTeX.
Popular options are MiKTex for Windows, MacTeX for Mac OS X and TeX Live for Linux. Alternatively, TinyTeX is a cut down solution that you can install directly from R using
> install.packages("tinytex")
> tinytex::install_tinytex()
TinyTeX is likely to be the simplest option if you only want to install LaTeX to experiment with these exercises.
Using R Markdown
To create a R Markdown report go to File / New File / R Markdown..., enter the report title, author name and choose PDF.
Reports are saved in the reports directory.
Front matter
The front matter at the top of a R Markdown file contains the basic set up for the document.
---
title: "Document title"
author: "Name"
date: "Date"
output: pdf_document
---
Various output types are supported, including Microsoft Word, HTML websites and presentations.
Code chunks
To insert a chunk of R code into a document choose Insert / R at the top right of the script pane. The cog-wheel button on the right of the chunk lets you choose whether the code and/or output is included in the report.
The first chunk should include the following to set up the document
knitr::opts_chunk$set(echo = TRUE)
knitr::opts_knit$set(root.dir= normalizePath('..'))
You can import the results of analysis to a R Markdown document by adding a chunk to run the script you wish to import (for this example you would use source("src/analysis.R")). You then refer directly to the variables and plots in the analysis script when writing the document. This is the key to linking your analysis directly to the report.
Refering to variables in your document text
To insert a variable into your text, use r variable_name. You must surround the code with tick marks (`).
To format a variable use the format function, for example r format(round(variable_name,-3), big.mark=",") rounds a variable to the nearest thousand and inserts a breaking comma e.g. 123,000.
The example report below shows how this works.
Creating the document
To create a document, select Knit at the top of the script pane. This runs you code, inserts the results into the document and saves the output.
Further resources
We recommend R Markdown: The Definitive Guide by Yihui Xie, J. J. Allaire and Garrett Grolemund if you want to learn more.
Creating the report
Download report.Rmd and save it in the reports directory.
Enter the document title, your name, your organisation and the date under params in the front matter and click Knit to create a PDF which should look like this.
Review report.Rmd to see how results from the analysis have been included in the document. You can experiment by making changes or trying different document types (try replacing pdf_document with html_document in the front matter).
You can also create templates to customise how the document looks, for example to match your organisation’s report style. See advanced customisation for some pointers.