That’s Great, But How?

There are no shortage of individuals proselytizing the virtues of open science, replication, and FAIR Data, however, these principles are rarely practically or effectively demonstrated. Peer reviewed publications discussing open science occasionally present vague summaries or lists of available tools for reproducible science, but no comprehensive tutorials. Conceptualized workflows such as the Replication Recipe are common.¹ Allen (2019) notes the benefits of Git, R Markdown, and Jupyter Notebooks in passing..² Ihle (2017) presents a sidebar with talking points for the benefits of using RStudio project, version control with Git, and reports with R and Shiny.³ Lastly, Hampton (2015) provides a wonderfully organized list of mostly open source software and tools to aid in open science.⁴

Other available resources for open science and reproducible research can be cumbersome books with extraneous statistical theory,⁵ or blog posts that are extremely light on details.⁶ workflowr package is a recently developed R package designed to aid scientists in creating reproducible research. This package employs most the techniques I will showcase through the rest of this tutorial, however, it wraps them up with helper functions and into a somewhat dogmatic approach to reproducible science.⁷ They are aimed at users of all skill levels. The workflowr GitHub site is a good place to familiarize yourself with the package’s offerings.⁸ In the remainder of this guide I feature a more flexible lower level approach to R packages for reproducible research compared to workflowr. I believe these techniques are accessible to novice users, and make the most sense for those who will be using R consistently for their research.

Benefits of R for Reproducible Research

The R programming language, RStudio IDE, and R packages are well suited for open science. R and RStudio are end to end truly open source solutions for open science. While there are other analytic platforms that permit open and reproducible research, I will not review those here, because, simply put, I only know R. If you work primarily with Python, SAS, MATLAB, or any other software platform I encourage you to seek out ways to facilitate open and distributable science on those platforms. R and RStudio have capabilities that cover all aspects of open science, replication, reproduction, distribution, FAIR Data, open code, and appropriate applied statistical methods:

• Cutting edge applied statistical analysis and visualizations.
  • Python is the current leader for most machine learning applications, but R offers better high end statistical modeling developed from peer reviewed methodologies.
• Open source platforms that are free and allow anyone to interact with your code, documentation, and analysis.
• Tools to organize code into functions with easily generated help documentation.
• Tools for scripted data acquisition, data pre-processing, embedding processed data, and easily generate documentation.
• Embedded short form analysis and reports with package vignettes and R Markdown.
  • Vignettes can be written to several formats including html and Microsoft Word.
• Embedded professional manuscripts using R Markdown PDF outputs built on LaTeX.
• Embedded slide presentations with R Markdown.
  • Slide presentations can be written to several formatins including Powerpoint, LaTeX Beamer, ioslides, and Reveal.js.
• Excellent Git integration with the RStudio IDE.
  • Git allows your package and research to be installable by anyone from inside the R console without navigating the GitHub or GitLab websites.
  • Git allows you to easily generate a free website for your package with a welcome page, reference manual with function and dataset documentation, manual

Transitioning from being and R user to creating R packages can be intimidating. I was a high level R user for 7-8 years before taking on my first package. Converting from an RStudio project with dozens of loosely organized and partially documented scripts with the occasional README.txt file to a fully organized, documented, Git protected, and web-hosted package feels like a big step. This becomes more difficult due to the lack of centralized detailed guides on this process that are specifically aimed at reproducible research and not traditional package development. Moreover, from 2010-2020 there were significant changes to the organization and best practices of the R packages that are used to assist with R package development. Because there are very few consolidated resources for using R packages for reproducible research, the methods I apply here are an amalgamation of techniques I pulled from a variety of sources mostly designed for developers of traditional R packages. I developed this guide to demonstrate a detailed approach to open science with R packages.

Developing Your Own R Package for Research

install.packages("package-name")

install.packages('pkgdown')
install.packages('usethis')
install.packages('devtools')
install.packages('roxygen2')
install.packages('knitr')
install.packages('rmarkdown')

install.packages('tinytex')

tinytex::install_tinytex()

Creating the New Package

Start by creating a new project by through RStudio’s menu selecting File > New Project... and select New Directory.

The RStudio New Project interface.

Then select R Package.

The RStudio New Project-New Directory interface.

This opens up the New Package interface. At this point you select a name for your package. For this exercise we’ll call our new package myresearch. Package names must alphanumeric with no spaces or special characters. It’s a real pain to change your package name so choose wisely. If you regret your package name it’s easiest to back up your functions, scripts, vignettes, and just create a new package to dump them in; especially if you’re using version control with GitLab or GitHub. Leave Create git repository un-checked. I find it easier to add Git to the package later using the terminal. Lastly choose your directory for installation. The default is your home directory, but I placed this package in a sub-directory for packages. Click Create Project when you’re finished.

RStudio’s New Package Window Layout

You will be greeted by a fresh RStudio window for your new package. The package name is listed as the RStudio Project name (top right), the script window displays a new function hello.R, the Files window defaults to your package root directory, and the Environment window now has an additional tab for package development named Build.

RStudio window layout for newly created package.

Before exploring the individual components of the new package layout, we’ll briefly set some package settings. Go to the Environment window and click Build > More > Configure Build Tools.... In this dialogue we want to check the box for Generate documentation with Roxygen, which will bring up the Roxygen Options window. It’s a good idea to check the Install and Restart box under Automatically roxygenize when running. This option ensures that package documentation and reference materials are updated every time you rebuild locally after changes.

RStudio Build Tools and Roxygen Options interfaces.

You can also check the Vignettes box under the Roxygen Options, however, this isn’t always behaving as expected in the current RStudio build. Another consideration to this option is if you have large and time-intensive vignettes you may not want to rebuild them every time you make a minor change and rebuild your package.