How to create reports with R Markdown in RStudio

Introduction

R Markdown is one of the most popular data science tools and is used to save and execute code to create exceptional reports whice are easily shareable.

The documents that R Markdown provides are fully reproducible and support a wide variety of static and dynamic output formats.

R Markdown uses markdown syntax, which provides an easy way of creating documents that can be converted to many other file types, while embeding R code in the report, so it is not necessary to keep the report and R script separately. Furthermore The report is written as normal text, so knowledge of HTML is not required. Of course no additional files are needed because everything is incorporated in the HTML file.

Package Installation

In order to use the R Markdown package we have to install and call it with:
install.packages("rmarkdown") library(rmarkdown)

Create an R Markdown file

To create a new R Markdown file (.Rmd) in RStudio we follow these steps: select File -> New File -> R Markdown…, then choose the file type you want to create. We choose the default .html, which can be easily converted to other file types later.

The .Rmd file we just created comes with default text as you can see but we will create our own file step by step so we delete everything.

R Markdown Syntax

The YAML Header

At the top of any R Markdown script is always the YAML header section enclosed by --- and is the minimum code chunk that should be put there. By default this includes a title, author, date, and the file type you want as output. Whatever we set in the header section is applied to the whole document.

This is an example of a YAML header at the top of an .Rmd script which creates an html document.
--- title: "R Markdown Example" author: Makis Kasvikis date: 17/Aug/2017 output: html_document ---

Inserting Code

Code that is included in your .Rmd document should be enclosed by three backwards apostrophes ``` like the example below:
```{r} summary(cars) ```

The space inside the brackets is where you can assign rules for that code chunk. The code chunk above says that the code is R code.

Of course you can click the green button with the “plus” symbol in RStudio to put a code chunk wherever you want.

< aside class='stb-icon'>

Learn more about reporting your results in the online course: R for Data Science Solutions. In this course you will learn how to:

• Build a complete workflow in R for your data science problem
• Get indepth on how to report your results in a interactive way
• And much more

Instructions for Code Chunks

As you have probably understood by now you can use code to do everything you want. For example you can generate a plot like this:
```{r} plot(cars) ```

Or you can create a dataframe:
```{r} A <- c("Bob", "Tom", "Bill", "Joe") B <- c(1.78, 1.86, 1.85, 1.70) dataframe <- data.frame(A, B) head(dataframe) ```

In case you don’t want that code to appear in the report and just display the result, then you should set echo=FALSE in the code chunk instructions.
```{r,echo=FALSE} A <- c("Bob", "Tom", "Bill", "Joe") B <- c(1.78, 1.86, 1.85, 1.70) dataframe <- data.frame(A, B) head(dataframe) ```

If you want to load a package like knitr you must load the package in the .Rmd file. In case you do not want the entire code chunk and its output from appearing in the report, use include=FALSE: ```{r, include=FALSE} library(knitr) ```

More code instructions

eval: eval=TRUE– Is the code run and the results included in the output?
include: include=TRUE– Are the code and the results included in the output (the code is still run)?
echo: echo=TRUE– Is the code displayed alongside the results?
warning: warning=TRUE– Are warning messages displayed?
error: error=FALSE– Are error messages displayed?
message: message=TRUE– Are messages displayed?
tidy: tidy=FALSE– Is the code reformatted to make it look “tidy”?
results: results="markup"– How are results treated?
cache: cache=FALSE– Are the results cached for future renders
comment:comment="##"– What character are comments prefaced with?
fig.width:, fig.width=7– What width (in inches) are the plots?
fig.align: fig.align="left"– “left” “right” “center”

Inserting Figures

To manually set the figure dimensions, you can insert an instruction:
```{r,fig.width=5, fig.height=5,echo=FALSE} plot(cars) ```

By default, figures are rendered as .png files by R Markdown, so you can change that to .svg, a vector file format by adding dev=”svg” to the code chunk instruction section.
```{r,fig.width=5, fig.height=5,echo=FALSE,dev="svg"} plot(cars) ```

Inserting Tables

While R Markdown can print the contents of a data frame easily by enclosing the name of the data frame in a code chunk this doea not seem the best idea.
```{r,echo=FALSE} dataframe ```
A better solution could be to use the table formatting function kable() in the knitr package like the example below:
```{r,echo=FALSE} library(knitr) kable(dataframe,digits=1) ```

Formatting Text

Markdown syntax can be used to change how text appears in your output file, here are a few common formatting commands

header 1: # header 1
header 2: ## header 2
header 3: ### header 3
header 4: #### header 4
bold text: **bold** text
italics text: *italics* text
code text: `code` text
inlcude a link: [link](www.r exercises.com)
Including a picture: R Studio Logo ![R Studio Logo](img/R Studio Logo.png)
LaTeX equation syntax: $A = \pi \times r^{2}$

You can also manually create small tables using markdown syntax.

`:----:`: Centre
`:-----`: Left
`-----:`: Right
`------`: Auto

For example:
| Teams | Wins | Loses | |:------|:-----:|-------:| | A | 21 | 4 | | B | 19 | 6 | | C | 17 | 8 |

Compiling an R Markdown file

Select Knit -> Knit to HTML in RStudio.

A preview appears in the Viewer window in RStudio and the .html file is saved to your working directory. You can set your working directory location using:
setwd("~/...")

You can find your working directory using:
getwd()