I’ve recently been consolidating a lot of R code from different parts of my analysis into one file. I wanted to add good documentation and explanation of results and interpretations along with my code to make sense of it later. I came across this option of creating dynamic reports that can combine our code, custom text and R output to an output document using the knitR package in R. I find it a good practice to create such reports for any analysis (wish I followed this earlier), so here’s a post on how to create them. They are very useful coz of the following reasons:
- It is a great option to generate PDF, HTML and word reports by combining our text explanations, code, R output and graphics at one go. It saves the hassle of saving and copying text, code, output and figures separately into a report.
- We can easily share the file with someone else with the output and explanations.
- It is much easier to generate a new report dynamically when the input file changes, as it runs the same code and generates new output report based on the new file at one go.
How to create dynamic reports in R?
The first step is to create a R Markdown file (with the extension .Rmd). If you’re using RStudio, you can go to File -> New File -> R Markdown to create a Rmd file. You should specify whether you want an output in html, pdf or word. It generated the following skeleton code for me as I specified an output pdf file:
Alternatively, you can write the sections in R and save it as .Rmd file. The Header section begins and ends with three dashes (—). It contains title, date and author attributes and specifies the type of output document: E.g. html_document for html web page, pdf_document for a pdf file, word_document for Microsoft Word .docx etc. The header can include other options as needed: “runtime: shiny” if it should be run as an interactive shiny app, “css: styles.css” to change the stylesheet when working with html, “toc: true” to include a table of contents etc.
The following code contains instructions along with R code to create a simple html document. It should be pretty self-explanatory to follow instructions and edit the code as needed for your own use:
---
title: "Sample Markdown file in R"
author: "Shibani"
output:
pdf_document: default
html_document: null
toc: yes
---
# Main Heading of the report
Plain text can be included as part of the report. This can be used to give introduction and explanations to your R code and results. Level 1 heading is added using '#'.
Blank line generates a new paragraph
## Including Text and Formatting
Level 2 heading added using '##', deeper heading using '###' and so on.
### Bulleted list using '*'
* item 1
* item 2
* item 3
### Numbered list using '1.'
1. item 1
2. item 2
3. item 3
### Formatting parts of text by enclosing within the symbols as below:
_italic_, *italic*, __bold__, **bold**, `monospace`
### Horizontal line using '- - -'
---
## Including Code
Code chunks start with ```{r name, option=value} and end with ```. Instead of typing them manually, they can be created in RStudio using Ctrl+Alt+i command (command+option+i in mac). Optional parameters can be specified to customize the display of code chunks in the report.Some commonly used options below:
* include=TRUE (default) displays all code and results in the report, and include=FALSE runs the code but doesnot display it in the report
* echo=TRUE displays the code in the report, but not the results, and echo=FALSE hides the code in the report
* warning=TRUE/ FALSE to display warnings generated
* cache=TRUE to use knitr for caching to improve performance for time-consuming computations
Inline code can be added by enclosing in single quotes E.g. "Two plus two equals `r 2 + 2`" displays "Two plus two equals 4"
knitr::opts_chunk$set(options) sets options globally to all code chunks unless overwritten by local options
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, error = TRUE)
library(knitr)
library(ggplot2)
```
### Code chunk calculating and displaying results
Using a sample data set to demonstrate code usage:
```{r calculate_chunk, echo=T}
data("cars")
head(cars)
cars$time <- round(cars$dist/cars$speed,2)
cars$time
```
## Including Figures
Any figure produced by the code will be automatically included in the report when the code is run. You can hide accompanying code using echo=FALSE in the code chunk. Figure display options can be set in the code chunk as well as follows:
```{r barplot, fig.width=5, fig.height=5, fig.cap= "Barplot of Distance vs Speed", echo=F}
ggplot(data=cars,aes(x=dist,y=speed))+geom_bar(stat = "identity")
```
## Including Tables
`kable()` function in the `knitr` package can be used to produce a table in the report with a matrix or data frame as input. To further customize the table with advanced fomatting options, use pander package.
```{r, echo=F}
kable(head(cars), digits = 2)
```
----
The html file created by the above code can be accessed here to view how the corresponding output is generated:
Useful resources:
https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf