rrtools: Tools for Writing Reproducible Research in R

<!-- badges: start -->

<!-- badges: end -->

Motivation

The goal of rrtools is to provide instructions, templates, and functions for making a basic compendium suitable for writing a reproducible journal article or report with R. This package documents the key steps and provides convenient functions for quickly creating a new research compendium. The approach is based on Marwick et al.'s (2017, Marwick et al. 2018) work using the R package structure as the basis for a research compendium.

rrtools provides a template for doing scholarly writing in a literate programming environment using Quarto, an open-source scientific and technical publishing system. It also allows for isolation of your computational environment using Docker, package versioning using renv, and continuous integration using GitHub Actions. It makes a convenient starting point for writing a journal article or report.

The functions in rrtools allow you to use R to easily follow the best practices outlined in several major scholarly publications on reproducible research. In addition to those cited above, Wilson et al. (2017), Piccolo & Frampton (2016), Stodden & Miguez (2014) and rOpenSci (2017) are important sources that have influenced our approach to this package.

Installation

To explore and test rrtools without installing anything, click the Binder badge above to start RStudio in a browser tab that includes the contents of this GitHub repository. In that environment you can browse the files, install rrtools, and make a test compendium without altering anything on your computer.

You can install rrtools from GitHub with these lines of R code (Windows users are recommended to install a separate program, Rtools, before proceeding with this step):

if (!require("devtools")) install.packages("devtools")
devtools::install_github("benmarwick/rrtools")

How to use

To create a reproducible research compendium step-by-step using the rrtools approach, follow these detailed instructions. We use RStudio, and recommend it, but is not required for these steps to work. We recommend copy-pasting these directly into your console, and editing the options before running. We don’t recommend saving these lines in a script in your project: they are meant to be once-off setup functions.

0. Create a Git-managed directory linked to an online repository

• It is possible to use rrtools without Git, but usually we want our research compendium to be managed by the version control software Git. The free online book Happy Git With R has details on how to do this. In brief, there are two methods to get started:
  • New project on GitHub first, then download to RStudio: Start on Github, Gitlab, or a similar web service, and create an empty repository called pkgname (you should use a different name, please follow the rules below) on that service. Then clone that repository to have a local empty directory on your computer, called pkgname, that is linked to this remote repository. Please see our wiki for a step-by-step walk-though of this method, illustrated with screenshots.
  • New project in RStudio first, then connect to GitHub/GitLab: An alternative approach is to create a local, empty, directory called pkgname on your computer (e.g. in your Desktop or Downloads folder), and initialize it with Git (git init), then create a GitHub/GitLab repository and connect your local project to the remote repository.
• Whichever of those two methods that you choose, you continue by staging, commiting and pushing every future change in the repository with Git.
• Your pkgname must follow some rules for everything to work, it must:
  • … contain only ASCII letters, numbers, and ‘.’
  • … have at least two characters
  • … start with a letter (not a number)
  • … not end with ‘.’

1. rrtools::use_compendium("pkgname")

• if you started with a new project on GitHub first, run rrtools::use_compendium(), if you started with a new project in RStudio first, run rrtools::use_compendium("pkgname")
• this uses usethis::create_package() to create a basic R package in the pkgname directory, and then, if you’re using RStudio, opens the project. If you’re not using RStudio, it sets the working directory to the pkgname directory.
• we need to:
  • edit the DESCRIPTION file (located in your pkgname directory) to include accurate metadata, e.g. your ORCID and email address
  • periodically update the Imports: section of the DESCRIPTION file with the names of packages used in the code we write in the qmd document(s) by running rrtools::add_dependencies_to_description()

2. usethis::use_mit_license(copyright_holder = "My Name")

• this adds a reference to the MIT license in the DESCRIPTION file and generates a LICENSE file listing the name provided as the copyright holder
• to use a different license, replace this line with any of the licenses mentioned here: ?usethis::use_mit_license()

3. rrtools::use_readme_qmd()

• this generates README.qmd and renders it to README.md, ready to display on GitHub. It contains:
  • a template citation to show others how to cite your project. Edit this to include the correct title and DOI.
  • license information for the text, figures, code and data in your compendium
• this also adds two other markdown files: a code of conduct for users CONDUCT.md, and basic instructions for people who want to contribute to your project CONTRIBUTING.md, including for first-timers to git and GitHub.
• this adds a .binder/Dockerfile that makes Binder work, if your compendium is hosted online. Currently configured for GitHub, but easily adapted for elsewhere (e.g. Zenodo, Figshare, Dataverse, etc.)
• render this document after each change to refresh README.md, which is the file that GitHub displays on the repository home page

4. rrtools::use_analysis()

• this function has three location = options: top_level to create a top-level analysis/ directory, inst to create an inst/ directory (so that all the sub-directories are available after the package is installed), and vignettes to create a vignettes/ directory (and automatically update the DESCRIPTION). The default is a top-level analysis/.
• for each option, the contents of the sub-directories are the same, with the following (using the default analysis/ for example):

<!-- end list -->

analysis/
|
├── paper/
│   ├── paper.qmd       # this is the main document to edit
│   └── references.bib  # this contains the reference list information

├── figures/            # location of the figures produced by the qmd
|
├── data/
│   ├── raw_data/       # data obtained from elsewhere
│   └── derived_data/   # data generated during the analysis
|
└── templates
    ├── journal-of-archaeological-science.csl
    |                   # this sets the style of citations & reference list
    ├── template.docx   # used to style the output of the paper.qmd
    └── template.Rmd

• the paper.qmd is ready to write in and render with Quarto. It includes:
  • a YAML header that identifies the references.bib file and the supplied csl file (to style the reference list)
  • a colophon that adds some git commit details to the end of the document. This means that the output file (HTML/PDF/Word) is always traceable to a specific state of the code.
• the references.bib file has just one item to demonstrate the format. It is ready to insert more reference details.
• you can replace the supplied csl file with a different citation style from https://github.com/citation-style-language/
• we recommend using the RStudio 2022.07 or higher to efficiently insert citations from your Zotero library while writing in an qmd file (see here for detailed setup and use information to connect your RStudio to your Zotero)
• remember that the Imports: field in the DESCRIPTION file must include the names of all packages used in analysis documents (e.g. paper.qmd). We have a helper function rrtools::add_dependencies_to_description() that will scan the qmd file, identify libraries used in there, and add them to the `