annotater

While helping some labmates with their R code last year, I noticed that sometimes they couldn’t run their analyses because their scripts had many library() calls for obscure packages they didn’t need, some of which had installation issues, dependencies, version conflicts, or masked functions.

📦 We started looking up each of these packages to see what they’re for, and when working offline, we used the utils::packageDescription() function to parse the DESCRIPTION files for the already installed packages. For more informative scripts, we commented the libary() load calls with the ‘Title’ field from each package.

For example:

# package load ------------------------------------------------------------
library(readr) # Read Rectangular Text Data
library(dplyr) # A Grammar of Data Manipulation
library(sensiPhy) # Sensitivity Analysis for Comparative Methods
library(tibble) # Simple Data Frames
library(weatherData) # Get Weather Data from the Web

✍️ After that, it seemed like a good idea to automate this annotation process. The annotater package comes with a few addins for RStudio so we can easily add these comments to our code. This package follows the approach in styler for automatically adapting code to a formatting style.

Here’s the addin in action:

Thanks to user feedback, there’s a function to annotate library() calls with the repository sources for non-CRAN packages (e.g. GitHub, BioConductor, etc.). Much later, I saw this tweet with code used to illustrate a recent update to ggplot2

geom_bar() + scale_x_binned() feels like it reads my mind about histogram bins. https://t.co/LdcQODqJr7 #ggplot2 pic.twitter.com/clILW7cOaR

— Allison Horst (@allison_horst) March 8, 2020

It seemed like good idea to also add the package version to the annotations to avoid confusion and when sharing code that uses development and/or CRAN releases.

Here’s the other function in action:

I’ve been using these addins to annotate scripts in my own research, for previous posts on this site, and when sharing code with colleagues, and so far I’ve found it helpful.

📦 Read more about ànnotater here

Install from GitHub like so:

# install.packages("remotes")
remotes::install_github("luisdva/annotater")

The package is a work in process, and all feedback is welcome!