Introduction

(Baker 2016)

Research is increasingly computational

  • Code and data are important research outputs

    • Yet, we mainly on publishing papers.

  • Calls for openness

    • Stick: we have a reproducibility crisis
    • Carrot: open science promotes equity and collaboration

We however lack the means for such openness.

Enter the Research Compendium

The goal of a research compendium is to provide a standard and easily recognizable way for organizing the digital materials of a project to enable others to inspect, reproduce, and extend the research.

Three Generic Principles

  1. Organize files according to best practices

    • Help others understand the structure of your project.
    • Supports tool building which takes advantage of the shared structure.

  2. Separate of data, method, and output, while making the relationship between them clear.

  3. Specify the computational environment that was used for the original analysis.

R community response

R packages can be used as a research compendium for organizing and sharing files!

  1. _Wickham, H. (2017) Research compendia. Note prepared for the 2017 rOpenSci Unconf

  2. Ben Marwick, Carl Boettiger & Lincoln Mullen (2018) Packaging Data Analytical Work Reproducibly Using R (and Friends), The American Statistician, 72:1, 80-88, DOI: <10.1080/00031305.2017.1375986>

Example use of the R package structure for a research compendium (Marwick, Boettiger, and Mullen 2018)

Enter rrtools

The goal of rrtools is to provide instructions, templates, and functions for making a template compendium suitable for producing reproducible research with R.

rrtools build on tools & best practices for R package development to

  • Organize files
  • Manage dependencies
  • Share code
  • Document code
  • Check and test code where applicable

rrtools extends and works with a number of R packages:

  • devtools: functions for package development

  • usethis: automates repetitive tasks that arise during project setup and development

  • bookdown: facilitates writing books and long-form articles/reports with R Markdown

Aims and objectives

In this book we’ll create a template research compendium that you can use for your own research project (text, data, code).

By the end of the book, you should be able to:

  • Be able to Create a Research Compendium to manage and share resources associated with an academic publication.

  • Be able to produce a reproducible manuscript from a single Rmarkdown document.

  • (If there’s interest) Understand the basics of managing code as an R package.

  • Appreciate the power of convention!

It’s like agreeing that we will all drive on the left or the right. A hallmark of civilization is following conventions that constrain your behavior a little, in the name of public safety.

Jenny Bryan on Project-oriented workflows

Let’s dive in!