User guide

1. Writing new scripts

Choose a date, a good default is the first day of the month when starting your project, and load all packages for that date.
For example

library(groundhog)
pkgs <- c(pkg1, pkg2, pkg3, pkg4)
groundhog.library(pkgs, '2021-09-01')

<your code>

Then, when you run or edit that script in the future, you can either stick with the date you chose originally,  or you can make the script up-to-date by just changing that one value.

If you will use multiple groundhog.libray() calls, you can set the date as a variable.

groundhog.day <-'2021-09-01'
groundhog.library(pkgs, groundhog.day)

 

2. Make existing scripts reproducible.

You can take any script that already exists, and retrofit it to make it reproducible in the future.
Set groundhog.day as if writing a new script. If the script runs as expected, with groundhog.day you chose , now you know it will continue running in the future. If it does not run as expected, try an earlier grounghog.day, perhaps the date from when the script was created or last saved. Once you find a date for which it works, the script will continue working.

3. Running/editing existing scripts.

When running a script that already relies on groundhog, using the existing groundhog.day value may make things slow (e.g., you may need to switch to an older version of R or install older packages from source). It may make sense to comment out the #groundhog.day in the script, and set groundhog.day to a more recent date.  This approach to using groundhog is similar to how people are supposed to use R, keeping packages up to date over time, except that:

  1. The package updating is accomplished by changing a single line of code: resetting groundhog.day.
  2. You know all packages in a script are simultaneously updated, and only if they need to be.
  3. Package updates are easy to reverse, and can be stopped, at any point.
  4. Future users of a script will load the same package versions used when the script was saved.
  5. Updates for one script will not affect other scripts that rely on the same packages

 

Starting with v2.0.0, this syntax makes it very easy to adapt an existing script to groundhog:

groundhog.library(“
    library(‘pkgA’)
    library(‘pkgB’)
    library(‘pkgC’)   “,    date)