## Overview

R Markdown combines markdown (an easy to write plain text format) with embedded R code chunks. When compiling R Markdown documents, the code components can be evaluated so that both the code and its output can be included in the final document. This makes analysis reports highly reproducible by allowing to automatically regenerate them when the underlying R code or data changes. R Markdown documents (.Rmd files) can be rendered to various formats including HTML and PDF. The R code in an .Rmd document is processed by knitr, while the resulting .md file is rendered by pandoc to the final output formats (e.g. HTML or PDF). Historically, R Markdown is an extension of the older Sweave/Latex environment. Rendering of mathematical expressions and reference management is also supported by R Markdown using embedded Latex syntax and Bibtex, respectively.

## Quick Start

### Install R Markdown

install.packages("rmarkdown")


### Initialize a new R Markdown (Rmd) script

To minimize typing, it can be helful to start with an R Markdown template and then modify it as needed. Note the file name of an R Markdown scirpt needs to have the extension .Rmd. Template files for the following examples are available here:

Users want to download these files, open the sample.Rmd file with their preferred R IDE (e.g. RStudio, vim or emacs), initilize an R session and then direct their R session to the location of these two files.

The metadata section (YAML header) in an R Markdown script defines how it will be processed and rendered. The metadata section also includes both title, author, and date information as well as options for customizing the output format. For instance, PDF and HTML output can be defined with pdf_document and html_document, respectively. The BiocStyle:: prefix will use the formatting style of the BiocStyle package from Bioconductor.

 ---
title: "My First R Markdown Document"
author: "Author: First Last"
date: "Last update: 23 August, 2017"
output:
BiocStyle::html_document:
toc: true
toc_depth: 3
fig_caption: yes

fontsize: 14pt
bibliography: bibtex.bib
---


### Render Rmd script

An R Markdown script can be evaluated and rendered with the following render command or by pressing the knit button in RStudio. The output_format argument defines the format of the output (e.g. html_document). The setting output_format="all" will generate all supported output formats. Alternatively, one can specify several output formats in the metadata section as shown in the above example.

rmarkdown::render("sample.Rmd", clean=TRUE, output_format="html_document")


The following shows two options how to run the rendering from the command-line.

$echo "rmarkdown::render('sample.Rmd', clean=TRUE)" | R --slave$ Rscript -e "rmarkdown::render('sample.Rmd', clean=TRUE)"


Alternatively, one can use a Makefile to evaluate and render an R Markdown script. A sample Makefile for rendering the above sample.Rmd can be downloaded here. To apply it to a custom Rmd file, one needs open the Makefile in a text editor and change the value assigned to MAIN (line 13) to the base name of the corresponding .Rmd file (e.g. assign systemPipeRNAseq if the file name is systemPipeRNAseq.Rmd). To execute the Makefile, run the following command from the command-line.

### Citations and bibliographies

Citations and bibliographies can be autogenerated in R Markdown in a similar way as in Latex/Bibtex. Reference collections should be stored in a separate file in Bibtex or other supported formats. To cite a publication in an R Markdown script, one uses the syntax (@<id1>) where <id1> needs to be replaced with a reference identifier present in the Bibtex database listed in the metadata section of the R Markdown script (e.g. bibtex.bib). For instance, to cite Lawrence et al. (2013), one uses its reference identifier (e.g. Lawrence2013-kt) as <id1> (Lawrence et al., 2013). This will place the citation inline in the text and add the corresponding reference to a reference list at the end of the output document. For the latter a special section called References needs to be specified at the end of the R Markdown script. To fine control the formatting of citations and reference lists, users want to consult this the corresponding R Markdown page. Also, for general reference management and outputting references in Bibtex format Paperpile can be very helpful.

### Viewing R Markdown report on HPCC cluster

R Markdown reports located on UCR’s HPCC Cluster can be viewed locally in a web browser (without moving the source HTML) by creating a symbolic link from a user’s .html directory. This way any updates to the report can be viewed immediately without creating another copy of the HTML file. For instance, if user ttest has generated an R Markdown report under ~/bigdata/today/rmarkdown/sample.html, then the proper symbolic link to this file can be created as follows:

cd ~/.html
ln -s ~/bigdata/today/rmarkdown/sample.html sample.html


After this one can view the report in a web browser using this URL http://biocluster.ucr.edu/~ttest/rmarkdown/sample.html. If necessary access to the URL can be restricted with a password following the instructions here.

Previous Page                     Next Page