Reproducible Research in R

class: title-slide, left, middle, inverse

<h1> Reproducible Research in R </h1>

<br>

<h3> Katherine Simeon <br> R-Ladies Chicago</h3>

<br>
<h4> January 28, 2019 </h4>

---
class: left, middle

## This is inspired by multiple rstudio::conf talks  
  
Karthik Ram - [A guide to modern reproducible data science with R](https://github.com/karthik/rstudio2019)  
  
Amanda Gadrow - [Writing reliable & maintainable R code](https://github.com/ajmcoqui/testingRCode)  
  
Mike K Smith - [The lazy & easily distracted report writer: Using rmarkdown and parametrized reports](https://github.com/MikeKSmith/RStudioConf2019)  
  
Charlotte & Hadley Wickham - Building Tidy Tools Workshop  
  
---

# The motivation  
  
Research is hard!  
  
--
  
.center[<img src="https://pbs.twimg.com/media/DJ7rFL6XUAcnxLy.jpg:large" height="330px" />]

--
  
.right[Being organized is important!]  
  
---

## Good code should be...  
  
<img src="https://fluorofinder.com/wp-content/uploads/2017/06/Design.Experiment.Repeat.-Square.png" height="300px" align="right"/>
  
--
  
* Reliable & Reproducible    
* Flexible & Generalizable    
  
--
  
<br>
  
## In research, reproducibility allows us to...  
  
* Clearly communicate research methods & findings    
* Repeat & improve our techniques
  
---

# Research Compendium  
   
A **systematic** way to organize research data, analyses, and documentation.  
  
<br>
  
--
  
A good research compendium...  
  
* Keeps to the conventions of collaborators/peers (makes it <span style="color:#562457">**generalizable**</span>)  
  
--
  
* Keeps data, methods, and outputs separate (makes it <span style="color:#562457">**reliable**</span>)      
  
--
  
* Clearly specifies the computational environment to the best of its abilities (makes it <span style="color:#562457">**reproducible**</span>)
  
<br>
  
--
  
The structure of an R package already has this! 📦  
  
---

# The R package structure

```r
A_PACKAGE  
    |
    ├── DESCRIPTION         # Important metadata! 
    |                       # Makes .Rproj recognized as a package
    ├── README.md
    |
    ├── NAMESPACE
    |
    ├── LICENSE
    |
    ├── R/                    # Functions that are in your package
    │   ├── UsefulFunction1.R       
    │   └── UsefulFunction2.R   
    |
    ├── man/                   # Documentation for functions
    │   ├── UsefulFunction1.Rd       
    │   └── UsefulFunction2.Rd 
    |
    └── A_package.Rproj     # R project file for your package
```
  
---

# An R package as a research compendium

```r
SAMPLE_COMPENDIUM  
    |
    ├── DESCRIPTION
    |
    ├── README.md
    |
    ├── LICENSE
    |
    ├── data/
    │   ├── raw_data/       # data obtained from elsewhere
    │   └── derived_data/   # data generated during the analysis
    |
    ├── analysis/           # contains scripts for analyses
        └── analysis.R
    |
    ├── paper/
    │   ├── paper.Rmd       # this is the main document to edit
    │   └── references.bib  # this contains the reference list information
    |
    └── figures/            # location of the figures produced by the Rmd
```
  
---
  
# Create a package!  
  
`usethis`<img src="https://raw.githubusercontent.com/r-lib/usethis/master/man/figures/logo.png" height="70px" align="right" />
  
A [package](https://github.com/r-lib/usethis) that automates repetitive tasks in project development:

```r
usethis::create_package("packagename")
```
  
<br>
`rrtools`  
  
A [package](https://github.com/benmarwick/rrtools) that expands `devtools` and contains instructions and templates for a research compendium:

```r
create_compendium("packagename")
```
  
<br>
  
  
  
---
  
## Documenting the computational environment  
  
<img src="https://raw.githubusercontent.com/o2r-project/containerit/master/inst/logo.png" height="70px" align="right" />  
  
Good documentation in the `DESCRIPTION` (particularly for `Depends`, `Imports`, & `Suggests`).  
  
`containerit` [packages](https://github.com/o2r-project/containerit) R scripts, session, workspace and all dependencies as a [Docker](https://www.docker.com/) container.  
  
--
  
## Parameterized reports in RMarkdown  
  
<img src="https://bookdown.org/yihui/rmarkdown/images/hex-rmarkdown.png" height="70px" align="right" />  
  
For **reproducible** and **flexible** reporting & documentation, use:   `Knit with Parameters...`  
.center[<img src="img/parameters_rmd.png" height="150px" />] 
  
---
  
# Takeaways  
  
We need to document our research in a way that is <span style="color:#562457">**reliable**, **reproducible**, & **generalizable**</span>.  
  
R has a lot of tools to organize and disseminate research in a <span style="color:#562457">**systematic**</span> way.  
  
<br>
  
.center[<img src="img/devtools.png" height="90px"/> <img src="https://raw.githubusercontent.com/r-lib/usethis/master/man/figures/logo.png" height="90px" /> <img src="https://github.com/r-lib/testthat/blob/master/man/figures/logo.png?raw=true" height="90px"/> <img src="https://raw.githubusercontent.com/o2r-project/containerit/master/inst/logo.png" height="90px"/> <img src="https://pkgdown.r-lib.org/reference/figures/logo.png" height="90px" /> <img src="https://bookdown.org/yihui/rmarkdown/images/hex-rmarkdown.png" height="90px"/>]

---
class: center, middle, inverse  
  
# Thank you!  
  
<br>
  
.small[Slides at: <svg style="height:0.8em;top:.04em;position:relative;" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg> [katherinesimeon](https://github.com/katherinesimeon)]