Calls for reproducibility

Reproducibility has the potential to serve as a minimum standard for judging scientific claims when full independent replication of a study is not possible.

• Fully scripted analyses pipelines
  • from raw data to published tables and figures
• Publication of code and data

Features

Rstudio features fly through

What is R Markdown? from RStudio, Inc. on Vimeo.

The researchers perspective

stripped down html. User can focus on communicating & disseminating

• intended to be as easy-to-read and easy-to-write as possible.

• most powerful as a format for writing to the web.

• syntax is very small, corresponding only to a very small subset of HTML tags.

• clean and legible across platforms (even mobile) and outputs.

• formatting handled automatically

• html markup language also handled.

RPubs: Publish rendered rmarkdown documents on the web with the click of a button http://rpubs.com/

GitHub: Host your site through gh-pages on GitHub. Can host entire websites, like this course material https://github.com/

Rmd documents

Can be useful for a number of research related materials

• Vignettes: long form documentation.
  • Analyses
  • Documentation (code & data)
  • Supplementary materials
• Reports
• Papers

Useful features: - bibliographies and citations

install the packages we’ll need

install.packages(c("skimr", "ggplot2", "dplyr", "plotly", "DT", "tibble"))

Create new project gapminder-analysis

Create your first .Rmd!

Render it

• Render the document by clicking on the knit button.

You can also render .Rmd documents to html using rmarkdown function render()

rmarkdown::render(input = "index.Rmd")

Publish your .Rmd

• Register an account on RPubs

• Publish your rendered document (don’t worry, you can delete or overwrite it later)

open the cheatsheet

basic html_document

---
title: "Untitled"
author: "Anna Krystalli"
date: "3/23/2018"
output: html_document
---

annotate code inline

rmarkdown

`this text will appear as code` inline

rendered html

this text will appear as code inline

evaluate r code inline

a <- 10

rmarkdown

the value of parameter *a* is `r a`

rendered html

the value of parameter a is 10

resize images

html in rmarkdown

<img src="assets/cheat.png" width="200px" />

rendered html

Get more info on gapminder:

Do some quick online research on Gapminder. A good places to start: https://www.gapminder.org/

Create a "Background" section using headers

Write a short description

Write a short description of the Gapminder project (feel free to copy, paste and edit information). Have a look at the gapminder site and especially the about page.

Make use of markdown annotation to:

• highlight important information
• include links to sources or further information.

Add an image

Add an image related to Gapminder.

• have a look online for an image.
• include the source URL underneath for attribution.
• see if you can resize it.

controlling code display with echo

chunk notation in .rmd

```{r hide-code, echo=FALSE}
print('hello world!')
```

rendered html code and output

[1] "hello world!"

controlling code evaluation with eval

chunk notation in .rmd

```{r dont-eval, eval=FALSE}
print('hello world!')
```

rendered html code and output

print("hello world!")

setting document level default options

knitr::opts_chunk$set(echo = TRUE, warning = F, message = F)

Create an “Installation” section using headers

Write installation instruction

Write brief instructions (including code) for others to access the dataset in R. Have a look at the package documentation on GitHub for inspiration.

In R we often need to describe a setup proceedure that involves specifying the installation of required packages. However, installation of packages in not handled in .Rmd! (For the moment, install packages through the console).

In our case, we’ll want to include the code for installing the gapminder package but not evaluate it in the .Rmd. We also want to include the rest of the packages we want to use: “ggplot2”, “DT”, “skimr”

printing data.frames

data(airquality)
head(airquality)

  Ozone Solar.R Wind Temp Month Day
1    41     190  7.4   67     5   1
2    36     118  8.0   72     5   2
3    12     149 12.6   74     5   3
4    18     313 11.5   62     5   4
5    NA      NA 14.3   56     5   5
6    28      NA 14.9   66     5   6

printing tibbles

One nice feature of using tibbles over data.frames is the tidy printing behaviour:

library(tibble)
as_tibble(airquality)

# A tibble: 153 x 6
   Ozone Solar.R  Wind  Temp Month   Day
   <int>   <int> <dbl> <int> <int> <int>
 1    41     190   7.4    67     5     1
 2    36     118   8      72     5     2
 3    12     149  12.6    74     5     3
 4    18     313  11.5    62     5     4
 5    NA      NA  14.3    56     5     5
 6    28      NA  14.9    66     5     6
 7    23     299   8.6    65     5     7
 8    19      99  13.8    59     5     8
 9     8      19  20.1    61     5     9
10    NA     194   8.6    69     5    10
# … with 143 more rows

Displaying knitr::kable() tables

We can use other packages to create html tables from our data.

The simplest is to use the knitr::kable() function.

library(knitr)
data(airquality)
kable(head(airquality), caption = "New York Air Quality Measurements")

Displaying interactive DT::datatable() tables

You can display interactive html tables using function DT::datatable():

library(DT)
data(airquality)
datatable(airquality, caption = "New York Air Quality Measurements")

Summarising data with skimr::skim()

Fuction skimr::skim() provides a simple approach to displaying summary statistics that can be quickly skimmed quickly to understand data.

skimr::skim(airquality)

Skim summary statistics
 n obs: 153 
 n variables: 6 

── Variable type:integer ──────────────────────────────────────────────
 variable missing complete   n   mean    sd p0    p25   p50    p75 p100
      Day       0      153 153  15.8   8.86  1   8     16    23      31
    Month       0      153 153   6.99  1.42  5   6      7     8       9
    Ozone      37      116 153  42.13 32.99  1  18     31.5  63.25  168
  Solar.R       7      146 153 185.93 90.06  7 115.75 205   258.75  334
     Temp       0      153 153  77.88  9.47 56  72     79    85      97
     hist
 ▇▇▇▇▆▇▇▇
 ▇▇▁▇▁▇▁▇
 ▇▆▃▃▂▁▁▁
 ▃▃▃▃▅▇▇▃
 ▂▂▃▆▇▇▃▃

── Variable type:numeric ──────────────────────────────────────────────
 variable missing complete   n  mean   sd  p0 p25 p50  p75 p100     hist
     Wind       0      153 153  9.96 3.52 1.7 7.4 9.7 11.5 20.7 ▁▃▇▇▅▅▁▁

Start a new section called "Dataset"

Display an example of the dataset

Make the gapminder data available by loading the gapminder package

library(gapminder)

Write a short description of the dataset

• What size is the data? (How many variables? How many rows of data points. See if you can extract and include such info inline)
• what type of object is it? (see ?class)
• Use some of the functions you’ve learnt to extract such information (eg ?dim, ?ncol etc).

Summarise the data

(e.g. ?summary, ?skimr)

interactive plots with plotly

Wraps nicely around plotting library ggplot2

library(plotly)

ggplotly(p)

R -> Rmd

You can read in chunks of code from an annotated .R (or any other language) script using knitr::read_chunks()

Chunks are defined by the following notation. Names must be unique.

# ---- descriptive-chunk-name1 ----
code("you want to run as a chunk")

# ---- descriptive-chunk-name2 ----
code("you want to run as a chunk")

code in .R script hello-world.R

hello-world.R

# ---- demo-read_chunk ----
print("hello world")

read chunks from hello-world.R

knitr::read_chunk(here::here("demos", "hello-world.R"))

call chunk by name

rmarkdown r chunk notation

```{r demo-read_chunk}

```

rendered html code and output

print("hello world")

[1] "hello world"

Check chunks in the current session

knitr:::knit_code$get()

$`demo-read_chunk`
[1] "print(\"hello world\")"

Rmd -> R

You can use knitr::purl() to tangle code out of an Rmd into an .R script. purl takes many of the same arguments as knit(). The most important additional argument is:

• documentation: an integer specifying the level of documentation to go the tangled script:
  • 0 means pure code (discard all text chunks)
  • 1 (default) means add the chunk headers to code
  • 2 means add all text chunks to code as roxygen comments

purl("file-to-extract-code-from.Rmd", documentation = 0)

extract using purl

Here i’m running a loop to extract the code in demo-rmd.Rmd for each documentation level

file <- here::here("demos", "demo-rmd.Rmd")
for (docu in 0:2) {
    knitr::purl(file, output = paste0(gsub(".Rmd", "", file), "_", docu, ".R"), 
        documentation = docu, quiet = T)
}

knitr::opts_chunk$set(echo = TRUE)
summary(cars)
plot(pressure)

## ----setup, include=FALSE------------------------------------------------
knitr::opts_chunk$set(echo = TRUE)

## ----cars----------------------------------------------------------------
summary(cars)

## ----pressure, echo=FALSE------------------------------------------------
plot(pressure)

#' ---
#' title: "Untitled"
#' author: "Anna Krystalli"
#' date: "3/23/2018"
#' output:
#'   html_document:
#'     toc: true
#'     toc_float: true
#'     theme: cosmo
#'     highlight: textmate
#' 
#' ---
#' 
## ----setup, include=FALSE------------------------------------------------
knitr::opts_chunk$set(echo = TRUE)

#' 
#' ## R Markdown
#' 
#' 
#' This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.
#' 
#' When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
#' 
## ----cars----------------------------------------------------------------
summary(cars)

#' 
#' ## Including Plots
#' 
#' You can also embed plots, for example:
#' 
## ----pressure, echo=FALSE------------------------------------------------
plot(pressure)

#' 
#' Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.
#' 
#' 

read in a chunk

• Open an .R script
• Cut the code from one or more of your chunks and paste it into the .R script
• Annotate the code up as named chunk(s)
• Read the chunk(s) in your .R script into your .Rmd (?read_chunk())
• Include the code in your .Rmd workflow by labelling an empty chunk with your chunk(s) name(s)

marking up with html tags

This text marked up in html

<strong>Bold text</strong>

renders to this

Bold text

**This text marked up with Bootstrap alert css classes

<div class="alert alert-warning"><small>this a is warning message</small></div>

renders to

<div class="alert alert-success"><small>this a is success message</small></div>

renders to

embedding tweets

This snipped copied from twitter in the embed format

<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">How cool does this tweet look embedded in <a href="https://twitter.com/hashtag/rmarkdown?src=hash&amp;ref_src=twsrc%5Etfw">#rmarkdown</a>! 😎</p>&mdash; annakrystalli (@annakrystalli) <a href="https://twitter.com/annakrystalli/status/977209749958791168?ref_src=twsrc%5Etfw">March 23, 2018</a></blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

renders to this

How cool does this tweet look embedded in #rmarkdown! 😎

— annakrystalli (@annakrystalli) March 23, 2018

Embbed gifs, videos, widgets in this way

reprex

install.packages("reprex")

Use function reprex::reprex() to produce a reproducible example in a custom markdown format for the venue of your choice

• "gh" for GitHub (default)
• "so" for StackOverflow,
• "r" or "R" for a runnable R script, with commented output interleaved.

using reprex

1. Copy the code you want to run.
   all required variables must be defined and libraries loaded
2. In the console, call the reprex function

reprex::reprex()

• the code is executed in a fresh environment and “code + commented output” is returned invisibly on the clipboard.

1. Paste the result in the venue of your choice.
   • Once published it will be rendered to html.

bookdown

Authoring with R Markdown. Offers:

• cross-references,
• citations,
• HTML widgets and Shiny apps,
• tables of content and section numbering

The publication can be exported to HTML, PDF, and e-books (e.g. EPUB) Can even be used to write thesis!

<img src=“assets/logo_bookdown.png”, width=“200px”/> <img src=“assets/cover_bookdown.jpg”, width=“200px”/>

pkgdown

workflowr pkg

blogdown

bookdown