Introduction to R markdown
This short tutorial will introduce you to creating reproducible reports using R markdown to encourage best (or better) practice to facilitate open science. It will first describe what R markdown is and why you might want to consider using it, describe how to create an R markdown document using RStudio and then how to convert this document to a html or pdf formatted report. During this tutorial you will learn about the different components of an R markdown document, how to format text, graphics and tables within the document and finally how to avoid some of the common difficulties using R markdown. There are also a couple of exercises for you to complete if you wish.
I estimate that this tutorial should take you roughly 1.5 to 2.5 hours to complete in one sitting, but feel free to dip in and out over a longer period if that suits you better.
What is R markdown?
R markdown is a simple and easy to use plain text language used to combine your R code, results from your data analysis (including plots and tables) and written commentary into a single nicely formatted and reproducible document (like a report, publication, thesis chapter or a web page like this one).
Technically, R markdown is a variant of another language (yet another language!) called Markdown and both are a type of ‘markup’ language. A markup language simply provides a way of creating an easy to read plain text file which can incorporate formatted text, images, headers and links to other documents. Don’t worry about the details for the moment, although if you’re interested you can find more information about markup languages here. Actually, if it makes you feel any better all of you will have been exposed to a markup language before, as most of the internet content you digest every day is underpinned by a markup language called HTML (Hypertext Markup Language). Anyway, the main point is that R markdown is very easy to learn (much, much easier than HTML) and when used with RStudio it’s ridiculously easy to integrate into your workflow to produce feature rich content (so why wouldn’t you?!).
Why use R markdown?
During our previous R course we talked a lot about conducting your research in a robust and reproducible manner to facilitate open science. In a nutshell, open science is about doing all we can to make our data, methods, results and inferences transparent and available to everyone. Some of the main tenets of open science are described here and include:
- Transparency in experimental methodology, observation, collection of data and analytical methods.
- Public availability and re-usability of scientific data
- Public accessibility and transparency of scientific communication
- Using web-based tools to facilitate scientific collaboration
By now all of you will (hopefully) be using R to explore and analyse your interesting data. As such, you’re already well along the road to making your analysis more reproducible, transparent and shareable. However, perhaps your current workflow looks something like this:
Your data is imported from your favourite spreadsheet software into RStudio (or R), you write your R code to explore and analyse your data, you save plots as external files, copy tables of analysis output and then manually combine all of this and your written prose into a single MS Word document (maybe a paper or thesis chapter). Whilst there is nothing particularly wrong with this approach (and it’s certainly better than using point and click software to analyse your data) there are some limitations:
It’s not particularly reproducible. Because this workflow separates your R code from the final document there are multiple opportunities for undocumented decisions to be made (which plots did you use? what analysis did/didn’t you include? etc).
It’s inefficient. If you need to go back and change something (create a new plot or update your analysis etc) you will need to create or amend multiple documents increasing the risk of mistakes creeping into your workflow.
It’s difficult to maintain. If your analysis changes you again need to update multiple files and documents.
It can be difficult to decide what to share with others. Do you share all of your code (initial data exploration, model validation etc) or just the code specific to your final document? It’s quite a common (and bad!) practice for researchers to maintain two R scripts, one used for the actual analysis and one to share with the final paper or thesis chapter. This can be both time consuming and confusing and should be avoided.
Perhaps a more efficient and robust workflow would look something like this:
Your data is imported into RStudio (or R) as before but this time all of the R code you used to analyse your data, produce your plots and your written text (Introduction, Materials and Methods, Discussion etc) is contained within a single R markdown document which is then used (along with your data) to automatically create your final document. This is exactly what R markdown allows you to do.
Some of the advantages of using R markdown include:
Explicitly links your data with your R code and output creating a fully reproducible workflow. ALL of the R code used to explore, summarise and analyse your data can be included in a single easy to read document. You can decide what to include in your final document (as you will learn below) but all of your R code can be included in the R markdown document.
You can create a wide variety of output formats (pdf, html web pages, MS Word and many others) from a single R markdown document which enhances both collaboration and communication.
Enhances transparency of your research. Your data and R markdown file can be included with your publication or thesis chapter as supplementary material or hosted on a GitHub repository (more about this in future tutorial).
Increases the efficiency of your workflow. If you need to modify or extend your current analysis you just need to update your R markdown document and these changes will automatically be included in your final document.
Getting started with R markdown
This tutorial assumes that you have already installed the latest
versions of R and RStudio. If you haven’t done this yet you can find
instructions here. To use R markdown you will
first need to install the rmarkdown package in RStudio (or
in the R console if you’re not using RStudio) and any package
dependencies. You can find instructions on how to do this for both
Windows and Mac OSX operating systems here. If you would like to create pdf
documents (or MS Word documents) from your R markdown file you will also
need to install a version of LaTeX on your computer. If you’ve not
installed LaTeX before, I recommend that you install TinyTeX. Again, instructions on
how to do this can be found here.
Creating an R markdown document
Right, time to create your first R markdown document. Within RStudio,
click on the menu File -> New File ->
R Markdown.... In the pop up window, give the document a
‘Title’ and enter the ‘Author’ information (your name) and select HTML
as the default output. We can change all of this later so don’t worry
about it for the moment.
You will notice that when your new R markdown document is created it
includes some example R markdown code. Normally you would just highlight
and delete everything in the document except the information at the top
between the --- delimiters (this is called the YAML header
which we will discuss in a bit) and then start writing your own code.
However, just for now we will use this document to practice converting R
markdown to both html and pdf formats and check everything is
working.
Once you’ve created your R markdown document it’s good practice to
save this file somewhere convenient. You can do this by selecting
File -> Save from RStudio menu (or use the
keyboard shortcut ctrl + s on Windows or cmd + s on a Mac) and enter an
appropriate file name (maybe call it my_first_rmarkdown).
Notice the file extension of your new R markdown file is
.Rmd.
Now, to convert your .Rmd file to a HTML document click
on the little black triangle next to the Knit icon at the
top of the source window and select knit to HTML
RStudio will now ‘knit’ (or render) your .Rmd file into
a HTML file. Notice that there is a new R Markdown tab in
your console window which provides you with information on the rendering
process and will also display any errors if something goes wrong.
If everything went smoothly a new HTML file will have been created
and saved in the same directory as your .Rmd file (ours
will be called my_first_rmarkdown.html). To view this
document simply double click on the file to open in a browser (like
Chrome or Firefox) to display the rendered content. RStudio will also
display a preview of the rendered file in a new window for you to check
out (your window might look slightly different if you’re using a Windows
computer).
Great, you’ve just rendered your first R markdown document. If you
want to knit your .Rmd file to a pdf document then all you
need to do is choose knit to PDF instead of
knit to HTML when you click on the knit icon.
This will create a file called my_first_rmarkdown.pdf which
you can double click to open. Give it a go!
You can also knit an .Rmd file using the command line in
the console rather than by clicking on the knit icon. To do this, just
use the render() function from the rmarkdown
package as shown below. Again, you can change the output format using
the output_format= argument as well as many other
options.
library(rmarkdown)
render('my_first_rmarkdown.Rmd', output_format = 'html_document')
# alternatively if you don't want to load the rmarkdown package
rmarkdown::render('my_first_rmarkdown.Rmd', output_format = 'html_document')
# see ?render for more options
R markdown anatomy
OK, now that you can render an R markdown file in RStudio into both HTML and pdf formats let’s take a closer look at the different components of a typical R markdown document. Normally each R markdown document is composed of 3 main components, 1) a YAML header, 2) formatted text and 3) one or more code chunks.
YAML header
YAML stands for ‘YAML Ain’t
Markup Language’ (it’s an ‘in’ joke!) and
this optional component contains the metadata and options for the entire
document such as the author name, date, output format, etc. The YAML
header is surrounded before and after by a --- on its own
line. In RStudio a minimal YAML header is automatically created for you
when you create a new R markdown document as we did above but you can change this any time. A simple YAML
header may look something like this:
---
title: My first R markdown document
author: Jane Doe
date: March 01, 2020
output: html_document
---
In the YAML header above the output format is set to HTML. If you
would like to change the output to pdf format then you can change it
from output: html_document to
output: pdf_document (you can also set more than one output
format if you like). You can also change the default font and font size
for the whole document and even include fancy options such as a table of
contents and inline references and a bibliography. If you want to
explore the plethora of other options see here.
Just a note of caution, many of the options you can specify in the YAML
header will work with both HTML and pdf formatted documents, but not
all. If you need multiple output formats for your R markdown document
check whether your YAML options are compatible between these formats.
Also, indentation in the YAML header has a meaning to be careful when
aligning text. For example, if you want to include a table of contents
you would modify the output: field in the YAML header as
follows
---
title: My first R markdown document
author: Jane Doe
date: March 01, 2020
output:
html_document:
toc: yes
---
Formatted text
As mentioned above, one of the great things about R markdown is that you don’t need to rely on your word processor to bring your R code, analysis and writing together. R markdown is able to render (almost) all of the text formatting that you are likely to need such as italics, bold, strike-through, super and subscript as well as bulleted and numbered lists, headers and footers, images, links to other documents or web pages and also equations. However, in contrast to your familiar What-You-See-Is-What-You-Get (WYSIWYG) word processing software you don’t see the final formatted text in your R markdown document (as you would in MS Word), rather you need to ‘markup’ the formatting in your text ready to be rendered in your output document. At first, this might seem like a right pain in the proverbial but it’s actually very easy to do and also has many advantages (do you find yourself spending more time on making your text look pretty in MS Word rather than writing good content?!).
Here is an example of marking up text formatting in an R markdown document
#### Benthic Biodiversity experiment
These data were obtained from a mesocosm experiment which aimed to examine the effect
of benthic polychaete (*Nereis diversicolor*) biomass on sediment nutrient
(NH~4~, NO~3~ and PO~3~) release. At the start of the experiment 15 replicate mesocosms
were filled with 20 cm^2^ of **homogenised** marine sediment and assigned to one of five
polychaete biomass treatments (0, 0.5, 1, 1.5, 2 g per mesocosm).
which would look like this in the final rendered document (can you spot the markups?)
Benthic Biodiversity experiment.
These data were obtained from a mesocosm experiment which aimed to examine the effect of benthic polychaete (Nereis diversicolor) biomass on sediment nutrient (NH4, NO3 and PO3) release. At the start of the experiment replicate mesocosms were filled with 20 cm2 of homogenised marine sediment and assigned to one of five polychaete biomass treatments (0, 0.5, 1, 1.5, 2 g per mesocosm).
Emphasis
Some of the most common R markdown syntax for providing emphasis and formatting text is given below.
| Goal | R markdown | output |
|---|---|---|
| bold text | **mytext** |
mytext |
| italic text | *mytext* |
mytext |
| strikethrough | ~~mytext~~ |
|
| superscript | mytext^2^ |
mytext2 |
| subscript | mytext~2~ |
mytext2 |
Interestingly there is no underline R markdown syntax by default. I
think this is because bold and italics are used to emphasise content (a
semantic meaning) whereas an underline is considered a stylistic element
(there may well be other reasons).
If you really want to underline text you can use
<span style="text-decoration:underline">underline this text</span>
for HTML output or
$\text{\underline{This sentence underlined using \LaTeX}}$
for pdf output. I just avoid underlining!
White space and line breaks
One of the things that can be confusing for new users of R markdown is the use of spaces and carriage returns (the enter key on your keyboard). In R markdown multiple spaces within the text are generally ignored as are carriage returns. For example this R markdown text
These data were obtained from a
mesocosm experiment which aimed to examine the
effect
of benthic polychaete (*Nereis diversicolor*) biomass.
will be rendered as
These data were obtained from a mesocosm experiment which aimed to examine the effect of benthic polychaete (Nereis diversicolor) biomass.
This is generally a good thing (no more random multiple spaces in your text). If you want your text to start on a new line then you can simply add two blank spaces at the end of the preceding line
These data were obtained from a
mesocosm experiment which aimed to examine the
effect benthic polychaete (Nereis diversicolor) biomass.
If you really want multiple spaces within your text and your output
format is HTML then you can use the Non
breaking space HTML tag
These data were obtained from a
mesocosm experiment which aimed to examine the
effect benthic polychaete (*Nereis diversicolor*) biomass.
These data were obtained from a
mesocosm experiment which aimed to examine the
effect benthic polychaete (Nereis diversicolor) biomass.
Headings
You can add headings and subheadings to your R markdown document by
using the # symbol at the beginning of the line. You can
decrease the size of the headings by simply adding more #
symbols. For example
# Benthic Biodiversity experiment
## Benthic Biodiversity experiment
### Benthic Biodiversity experiment
#### Benthic Biodiversity experiment
##### Benthic Biodiversity experiment
###### Benthic Biodiversity experiment
results in headings in decreasing size order
Benthic Biodiversity experiment.
Benthic Biodiversity experiment.
Benthic Biodiversity experiment.
Benthic Biodiversity experiment.
Benthic Biodiversity experiment.
Benthic Biodiversity experiment.
Lists
If you want to create a bullet point list of text you can format an unordered list with sub items. Notice that the sub-items need to be indented.
- item 1
- item 2
- sub-item 2
- sub-item 3
- item 3
- item 4
If you need an ordered list
- item 1
- item 2
- sub-item 2
- sub-item 3
- item 3
- item 4
Images
Another useful feature is the ability to embed images and links to web pages (or other documents) into your R markdown document. You can include images into your R markdown document in a number of different ways. Perhaps the simplest method is to use
resulting in:
The code above will only work if the image file
(Cute_grey_kitten.jpg) is in the right place relative to
where you saved your .Rmd file. In the example above the
image file is in a sub directory (folder) called images in
the directory where we saved our my_first_rmarkdown.Rmd
file. You can embed images saved in many different file types but
perhaps the most common are .jpg and .png.
I think a more flexible way of including images in your document is
to use the include_graphics() function from the
knitr package as this gives finer control over the
alignment and image size (it’s also works more or less the same with
both HTML and pdf output formats). However, to do this you will need to
include this R code in a ‘code chunk’ which
we haven’t covered yet. Despite this I’ll leave the code here for later
reference. This code center aligns the image and scales it to 50% of
it’s original size. See ?include_graphics for more
options.
```{r, echo=FALSE, fig.align='center', out.width='50%'}
library(knitr)
include_graphics("images/Cute_grey_kitten.jpg")
```
Links
In addition to images you can also include links to webpages or other links in your document. Use the following syntax to create a clickable link to an existing webpage. The link text goes between the square brackets and the URL for the webpage between the round brackets immediately after.
which gives you:
You can include a text for your clickable link
Exercise
You can find an exercise to practice formatting R markdown text here
Code chunks
Now to the heart of the matter. To include R code into your R
markdown document you simply place your code into a ‘code chunk’. All
code chunks start and end with three backticks ```. Note,
these are also known as ‘grave accents’ or ’back quotes and are not the
same as an apostrophe! On most keyboards you can find
the backtick on the same key as tilde (~).
```{r}
Any valid R code goes here
```
You can insert a code chunk by either typing the chunk delimiters
```{r} and ``` manually or use the RStudio
toolbar (the Insert button) or by clicking on the menu Code
-> Insert Chunk. Perhaps an even better way is to get
familiar with the keyboard shortcuts Ctrl + Alt + I for Windows and Cmd
+ Option + I on MacOSX.
There are a many things you can do with code chunks: you can produce
text output from your analysis, create tables and figures and insert
images amongst other things. Within the code chunk you can place rules
and arguments between the curly brackets {} that give you
control over how your code is interpreted and output is rendered. These
are known as chunk options. The only mandatory chunk option is the first
argument which specifies which language you’re using (r in
our case but other
languages are supported). Note, all of your chunk options must be
written between the curly brackets on one line with no line breaks.
You can also specify an optional code chunk name (or label) which can
be useful when trying to debug problems and when performing advanced
document rendering. In the following block we name the code chunk
summary-stats, create a dataframe (dataf) with
two variables x and y and then use the
summary() function to display some summary statistics .
When we run the code chunk both the R code and the resulting output are
displayed in the final document.
```{r, summary-stats}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
summary(dataf)
```
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
summary(dataf)## x y
## Min. : 1.00 Min. : 1.00
## 1st Qu.: 3.25 1st Qu.: 3.25
## Median : 5.50 Median : 5.50
## Mean : 5.50 Mean : 5.50
## 3rd Qu.: 7.75 3rd Qu.: 7.75
## Max. :10.00 Max. :10.00
When using chunk names make sure that you don’t have duplicate chunk
names in your R markdown document and avoid spaces and full stops as
this may cause problems when you come to knit your document (I use a
- to separate words in my chunk names).
If we wanted to only display the output of our R code (just the
summary statistics for example) and not the code itself in our final
document we can use the chunk option echo=FALSE
```{r, summary-stats, echo=FALSE}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
summary(dataf)
```
## x y
## Min. : 1.00 Min. : 1.00
## 1st Qu.: 3.25 1st Qu.: 3.25
## Median : 5.50 Median : 5.50
## Mean : 5.50 Mean : 5.50
## 3rd Qu.: 7.75 3rd Qu.: 7.75
## Max. :10.00 Max. :10.00
To display the R code but not the output use the
results='hide' chunk option.
```{r, summary-stats, results='hide'}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
summary(dataf)
```
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
summary(dataf)
Sometimes you may want to execute a code chunk without showing any
output at all. You can suppress the entire output using the chunk option
include=FALSE.
```{r, summary-stats, include=FALSE}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
summary(dataf)
```
There are a large number of chunk options documented here with a more condensed version here. Perhaps the most commonly used are summarised below with the default values shown.
| Chunk option | default value | Function |
|---|---|---|
| echo | echo=TRUE |
If FALSE, will not display the code in the final document |
| results | results='markup' |
If ‘hide’, will not display the code’s results in the final document. If ‘hold’, will delay displaying all output pieces until the end of the chunk. If ‘asis’, will pass through results without reformatting them. |
| include | include=TRUE |
If FALSE, will run the chunk but not include the chunk in the final document. |
| eval | eval=TRUE |
If FALSE, will not run the code in the code chunk. |
| message | message=TRUE |
If FALSE, will not display any messages generated by the code. |
| warning | warning=TRUE |
If FALSE, will not display any warning messages generated by the code. |
Adding figures
By default, figures produced by R code will be placed immediately after the code chunk they were generated from. For example:
```{r, simple-plot}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
```
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
If you want to change the plot dimensions in the final document you
can use the fig.width= and fig.height= chunk
options (in inches!). You can also change the alignment of the figure
using the fig.align= chunk option.
```{r, simple-plot, fig.width=4, fig.height=3, fig.align='center'}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
```
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
You can add a figure caption using the fig.cap=
option.
```{r, simple-plot-cap, fig.cap="A simple plot", fig.align='center'}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
```
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
A simple plot
If you want to suppress the figure in the final document use the
fig.show='hide' option.
```{r, simple-plot, fig.show='hide'}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
```
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
plot(dataf$x, dataf$y, xlab = "x axis", ylab = "y axis")
If you’re using a package like ggplot2 to create
your plots then don’t forget you will need to make the package available
with the library() function in the code chunk (or in a
preceding code chunk).
```{r, simple-ggplot}
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
library(ggplot2)
ggplot(dataf, aes(x = x, y = y))
```
x <- 1:10 # create an x variable
y <- 10:1 # create a y variable
dataf <- data.frame(x = x, y = y)
library(ggplot2)
ggplot(dataf, aes(x = x, y = y)) +
geom_point()
Again, there are a large number of chunk options specific to producing plots and figures. See here for more details.
Adding tables
R markdown can print the contents of a dataframe as a table (or any
other tabular object such as a summary of model output) by including the
name of the dataframe in a code chunk. For example, to create a table of
the first 10 rows of the inbuilt dataset iris
```{r, ugly-table}
iris[1:10,]
```
## Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1 5.1 3.5 1.4 0.2 setosa
## 2 4.9 3.0 1.4 0.2 setosa
## 3 4.7 3.2 1.3 0.2 setosa
## 4 4.6 3.1 1.5 0.2 setosa
## 5 5.0 3.6 1.4 0.2 setosa
## 6 5.4 3.9 1.7 0.4 setosa
## 7 4.6 3.4 1.4 0.3 setosa
## 8 5.0 3.4 1.5 0.2 setosa
## 9 4.4 2.9 1.4 0.2 setosa
## 10 4.9 3.1 1.5 0.1 setosa
But how ugly is that! You can create slightly nicer looking tables using native markdown syntax (this doesn’t need to be in a code chunk).
| x | y |
|:----------:|:----------:|
| 1 | 5 |
| 2 | 4 |
| 3 | 3 |
| 4 | 2 |
| 5 | 1 |
| x | y |
|---|---|
| 1 | 5 |
| 2 | 4 |
| 3 | 3 |
| 4 | 2 |
| 5 | 1 |
The :-------: lets R markdown know that the line above
should be treated as a header and the lines below as the body of the
table. Alignment within the table is set by the position of the
:. To center align use :------:, to left align
:------ and right align ------:. Whilst it can
be fun(!) to create tables with raw markup it’s only practical for very
small and simple tables.
The easiest way I know to include tables in an R markdown document is
by using the kable() function from the knitr
package (this should have already been installed when you installed the
rmarkdown package). The kable() function can
create tables for HTML, PDF and Word outputs.
To create a table of the first 10 rows of the iris
dataframe using the kable() function simply write your code
block as
```{r, kable-table}
library(knitr)
kable(iris[1:10,])
```
| Sepal.Length | 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 |
The kable() function offers plenty of options to change
the formatting of the table. For example, if we want to round numeric
values to one decimal place use the digits = argument. To
center justify the table contents use align = 'c' and to
provide custom column headings use the col.names =
argument. See ?knitr::kable for more information.
```{r, kable-table2}
kable(iris[1:10,], digits = 0, align = 'c', col.names = c('sepal length', 'sepal width', 'petal length', 'petal width', 'species'))
```
| sepal length | sepal width | petal length | petal width | species |
|---|---|---|---|---|
| 5 | 4 | 1 | 0 | setosa |
| 5 | 3 | 1 | 0 | setosa |
| 5 | 3 | 1 | 0 | setosa |
| 5 | 3 | 2 | 0 | setosa |
| 5 | 4 | 1 | 0 | setosa |
| 5 | 4 | 2 | 0 | setosa |
| 5 | 3 | 1 | 0 | setosa |
| 5 | 3 | 2 | 0 | setosa |
| 4 | 3 | 1 | 0 | setosa |
| 5 | 3 | 2 | 0 | setosa |
You can further enhance the look of your kable tables
using the kableExtra package (don’t forget to install the
package first!). See here
for more details and a helpful tutorial.
```{r, kableExtra-table}
library(kableExtra)
kable(iris[1:10,]) %>%
kable_styling(bootstrap_options = "striped", font_size = 10)
```
| Sepal.Length | 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 |
If you want even more control and customisation options for your
tables take a look at the pander and xtable
packages.
Inline R code
Up till now we’ve been writing and executing our R code in code
chunks. Another great reason to use R markdown is that we can also
include our R code directly within our text. This is known as ‘inline
code’. To include your code in your R markdown text you simply write
`r write your r code here`. This can come in really useful
when you want to include summary statistics within your text. For
example, we could describe the iris dataset as follows:
Morphological characteristics (variable names: `r names(iris)[1:4]`) were measured from
`r nrow(iris)`*Iris sp.* plants from `r length(levels(iris$Species))` different species. The mean Sepal length was `r round(mean(iris$Sepal.Length), digits = 2)` mm.
which would be rendered as
Morphological characteristics (variable names: Sepal.Length, Sepal.Width, Petal.Length, Petal.Width) were measured from 150 iris plants from 3 different species. The mean Sepal length was 5.84 mm.
The great thing about including inline R code in your text is that these values will automatically be updated if your data changes.
Exercise
You can find an exercise to practice using code chunks and inline R code here
Some tips and tricks
Problem :
When rendering my R markdown document to pdf my code runs off the edge of the page.
Solution:
Add a global_options argument at the start of your .Rmd file in a code chunk:
```{r global_options, include=FALSE}
knitr::opts_chunk$set(message=FALSE, tidy.opts=list(width.cutoff=60), tidy=TRUE)
```
This code chunk won’t be displayed in the final document due to the
include = FALSE argument and you should place the code
chunk immediately after the YAML header to affect everything below
that.
tidy.opts = list(width.cutoff = 60), tidy=TRUE defines
the margin cutoff point and wraps text to the next line. Play around
with this value to get it right (60-80 should be OK for most
documents).
Problem:
When I load a package in my R markdown document my rendered output contains all of the startup messages and/or warnings.
Solution:
You can load all of your packages at the start of your R markdown document in a code chunk along with setting your global options.
```{r global_options, include=FALSE}
knitr::opts_chunk$set(message=FALSE, warning=FALSE, tidy.opts=list(width.cutoff=60))
suppressPackageStartupMessages(library(ggplot2))
```
The message=FALSE and warning=FALSE
arguments suppress messages and warnings. The
suppressPackageStartupMessages(library(ggplot2)) will load
the ggplot2 package but suppress startup messages.
Problem:
When rendering my R markdown document to pdf my tables and/or figures are split over two pages.
Solution:
Add a page break using the LateX \pagebreak notation
before your offending table or figure
Problem:
The code in my rendered document looks ugly!
Solution:
Add the argument tidy=TRUE to your global arguments.
Sometimes, however, this can cause problems especially with correct code
indentation.
```{r global_options, include=FALSE}
knitr::opts_chunk$set(message=FALSE, tidy.opts=list(width.cutoff=60), tidy=TRUE)
```
Further Information
Although we’ve covered more than enough to get you quite far using R markdown, as with most things R related, we’ve really only had time to scratch the surface. Happily, there’s a wealth of information available to you should you need to expand your knowledge and experience. A good place to start is the excellent free book written by the creator of R markdown Yihui Xie which you can find here.
Another useful and concise R markdown reference guide can be found here
A quick and easy RStudio R markdown cheatsheet
Comments
As you can see above the meaning of the
#symbol is different when formatting text in an R markdown document compared to a standard R script (which is used to included a comment - remember?!). You can, however, use a#symbol to comment code inside a code chunk as usual (more about this in a bit). If you want to include a comment in your R markdown document outside a code chunk which won’t be included in the final rendered document then enclose your comment between<!--and-->.