Why am I doing this?
- Software for doing these sort of things are gaining momentum in the open science community.
- Presenting your work in this sort of fashion looks unique & saves you time.
Why Reproducible Report (RR)?
- Code, analysis, and results are in a single file.
- Automatically renew the report when the code or data changes.
- Avoid erros by NOT
copy-paste
ing results. - Preserve contextual narrative about why analysis was performed in a certain fashion [1].
- Documentation for the analytic and computational processes from which conclusions are drawn [1].
Workflow in a nutshell
Combine R with plain text file format to produce documents (e.g., pdfs, HTML documents, etc.)
Look here for all possible instances: http://cran.r-project.org/web/views/ReproducibleResearch.html
In this document we are going to explore making reports using Knitr & Markdown in RStudio
Why RStudio, Markdown, & Knitr?
- Classically RR is made using
Sweave (R + LaTeX)
Sweave
, a function in R to make reports from R code weaved with LaTeX.- The problem: Not smart enough to reformat/resize things if unfit for a document.
- Limited to only understanding
LaTeX
LaTeX
, an elegant markup language- The problem: Too many conventions to remember to make a simple report.
- But if mastered, then fruits are worth it!
Knitr
, R package to overcome most limitation ofSweave
- Allows any input languages (e.g. R, Python and Awk) and any output markup languages (e.g. LaTeX, HTML, Markdown and reStructuredText)
Markdown
, a light weight markup language that\’s simple, readable, and intuitive.- Notice the irony here: markup languages generally take a piece of text and decorations around it to render the final results (i.e.
<strong>BOLD TEXT</strong>
), while inmarkdown
you are doing the bare minimum!
- Notice the irony here: markup languages generally take a piece of text and decorations around it to render the final results (i.e.
RStudio
, software with builtin support for Knitr and Markdown….and it\’s simply awesome!
What are we doing essentially?
Weave R code into a document ->
Where text is fashioned by markdown ->
Which Knitr will parse and ->
Write the output into a HTML file.
Prerequisites:
Two best friends in RStudio
- MD button is a reference to Markdown documentation
- Knit HTML button will make the report.
Simplest Example
- Open a new R markdown document in RStudio. File -> New -> R Markdown.
- This launches a sample document to get you started.
- All the R code is enclosed in triple tick marks called code chunks
- Each code chunk by default shows up in the final output. You can add various options to fine tune the behavior of code chunks.
- Press Knit HTML button to see what it does.
R Code Chunks
To insert an R code chunk, you can type it manually or just press Chunks - Insert chunks
or use the shortcut key. This will produce the following code chunk:
The following R code chunk is as follows:
```r
myData <- data.frame(x = 1:10, y = 20:30)
myData
plot(myData)
```
The code chunk input and output is then displayed as follows:
myData <- data.frame(x = 1:10, y = 21:30) myData
## x y ## 1 1 21 ## 2 2 22 ## 3 3 23 ## 4 4 24 ## 5 5 25 ## 6 6 26 ## 7 7 27 ## 8 8 28 ## 9 9 29 ## 10 10 30
plot(myData)
Some example of ggplot!
library(ggplot2) suppressPackageStartupMessages(library(tabplot)) tableplot(diamonds)
Pressing tab when inside the braces will bring up code chunk options.
Most frequently used options (bold text denote default options):
- comment: display
#
in front of text when printing text from code chunk. Set to “” to display nothing. - echo: display the code chunk itself in the output. (T/F)
- eval: evaluate the code chunk. (T/F)
- result: how should the results be displayed. (markup,asis,hide)
- fig.width or fig.height : dimensions of the figure. (7)
- cache : save the code chunk computation for reuse later. To rerun cached code chunks, just delete the contents of the cache folder. (T/F)
References & Excellent resources to learn more
- Making Reproducible Research Enjoyable [1]
- Getting Started with R Markdown, knitr, and Rstudio
- Using R Markdown with RStudio
- Customizing Chunk Options