by Andrie de Vries
In 2014 we introduced the checkpoint package for reproducible research. This package makes it easy to use R package versions that existed on CRAN at a given date in the past, and to use varying package versions with different projects. Previous blog posts include:
- Introducing the Reproducible R Toolkit and the checkpoint package
- An update to the checkpoint package
- New features in checkpoint v0.3.15 now on CRAN
On April 12, 2017, we published version 0.4.0 of checkpoint to CRAN.
checkpoint() function enables reproducible research by managing your R package versions. These packages are downloaded into a local
.checkpoint folder. If you use
checkpoint() for many projects, these local packages can consume some storage space, and this update introduces functions to manage your snapshots. In this post I review:
- Managing local archives:
checkpointArchives(): list checkpoint archives on disk.
checkpointRemove(): remove checkpoint archive from disk.
getAccessDate(): returns the date the snapshot was last accessed.
unCheckpoint(): reset .libPaths to the user library to undo the effect of checkpoint().
Setting up an example project
For illustration, set up a script referencing a single package:
library(MASS) hist(islands) truehist(islands)
Next, create the checkpoint:
dir.create(file.path(tempdir(), ".checkpoint"), recursive = TRUE) ## Create a checkpoint by specifying a snapshot date library(checkpoint) checkpoint("2015-04-26", project = tempdir(), checkpointLocation = tempdir())
Working with checkpoint archive snapshots
You can query the available snapshots on disk using the
checkpointArchives() function. This returns a vector of snapshot folders.
# List checkpoint archives on disk. checkpointArchives(tempdir()) ##  "2015-04-26"
You can get the full paths by including the argument
checkpointArchives(tempdir(), full.names = TRUE) ##  "C:/Users/adevries/AppData/Local/Temp/RtmpcnciXd/.checkpoint/2015-04-26"
Working with access dates
Every time you use
checkpoint() the function places a small marker in the snapshot archive with the access date. In this way you can track when was the last time you actually used the snapshot archive.
# Returns the date the snapshot was last accessed. getAccessDate(tempdir()) ## C:/Users/adevries/AppData/Local/Temp/RtmpcnciXd/.checkpoint/2015-04-26 ## "2017-04-12"
Removing a snapshot from local disk
Since the date of last access is tracked, you can use this to manage your checkpoint archives. The function
checkpointRemove() will delete archives from disk. You can use this function in multiple ways. For example, specify a specific archive to remove:
# Remove singe checkpoint archive from disk. checkpointRemove("2015-04-26")
You can also remove a range of snapshot archives older (or more recent) than a snapshot date
# Remove range of checkpoint archives from disk. checkpointRemove("2015-04-26", allSinceSnapshot = TRUE) checkpointRemove("2015-04-26", allUntilSnapshot = = TRUE)
Finally, you can remove all snapshot archives that have not been accessed since a given date:
# Remove snapshot archives that have not been used recently checkpointRemove("2015-04-26", notUsedSince = TRUE)
Reading the checkpoint log file
One of the side effects of
checkpoint() is to create a log file that contains information about packages that get downloaded, as well as the download size. This file is stored in the checkpoint root folder, and is a csv file with column names, so you can read this with your favourite R function or other tools.
dir(file.path(tempdir(), ".checkpoint")) ##  "2015-04-26" "checkpoint_log.csv" "R-3.3.3"
Inspect the log file:
log_file ## timestamp snapshotDate pkg bytes ## 1 2017-04-12 15:05:12 2015-04-26 MASS 1084392
Resetting the checkpoint
In older versions of
checkpoint() the only way to reset the effect of
checkpoint() was to restart your R session. In v0.3.20 and above, you can use the function
unCheckpoint(). This will reset your
.libPaths to the user folder.
.libPaths() ##  "C:/Users/adevries/AppData/Local/Temp/RtmpcnciXd/.checkpoint/2015-04-26/lib/x86_64-w64-mingw32/3.3.3" ##  "C:/Users/adevries/AppData/Local/Temp/RtmpcnciXd/.checkpoint/R-3.3.3" ##  "C:/R/R-33~1.3/library" Now use `unCheckpoint()` to reset your library paths # Note this is still experimental unCheckpoint() .libPaths() ##  "C:\\Users\\adevries\\Documents\\R\\win-library" ##  "C:/R/R-33~1.3/library"
How to obtain and use checkpoint
Version 0.4.0 of the checkpoint package is available on CRAN now, so you can install it with:
The above command works both for CRAN R, and also for Microsoft R Open (which comes bundled with an older version of checkpoint). For more information on checkpoint, see the vignette Using checkpoint for reproducible research.