R: Configures R session to use packages as they existed on CRAN...

checkpoint {checkpoint}

R Documentation

Configures R session to use packages as they existed on CRAN at time of snapshot.

Description

Together, the checkpoint package and the checkpoint server act as a CRAN time machine. The checkpoint() function installs the packages referenced in the specified project to a local library exactly as they existed at the specified point in time. Only those packages are available to your session, thereby avoiding any package updates that came later and may have altered your results. In this way, anyone using the checkpoint checkpoint() function can ensure the reproducibility of your scripts or projects at any time.

Usage

checkpoint(snapshotDate, project = getwd(), R.version,
  scanForPackages = TRUE, checkpointLocation = "~/", verbose = TRUE,
  use.knitr, auto.install.knitr = TRUE, scan.rnw.with.knitr = FALSE,
  forceInstall = FALSE, forceProject = FALSE)

Arguments

`snapshotDate`	Date of snapshot to use in `YYYY-MM-DD` format, e.g. `"2014-09-17"`. Specify a date on or after `"2014-09-17"`. MRAN takes one snapshot per day. To list all valid snapshot dates on MRAN use `getValidSnapshots()`
`project`	A project path. This is the path to the root of the project that references the packages to be installed from the MRAN snapshot for the date specified for `snapshotDate`. Defaults to current working directory using `getwd()`.
`R.version`	Optional character string, e.g. `"3.1.2"`. If specified, compares the current R.version to the specified R.version. If these differ, stops processing with an error, making no changes to the system. Specifically, if the check fails, the library path is NOT modified. This argument allows the original script author to specify a specific version of R to obtain the desired results.
`scanForPackages`	If `TRUE`, scans for packages in project folder (see details). If FALSE, skips the scanning process. A use case for `scanForPackages = FALSE` is to skip the scanning and installation process, e.g. in production environments with a large number of R scripts in the project. Only set `scanForPackages = FALSE` if you are certain that all package dependencies are already in the checkpoint folder.
`checkpointLocation`	File path where the checkpoint library is stored. Default is `"~/"`, i.e. the user's home directory. A use case for changing this is to create a checkpoint library on a portable drive (e.g. USB drive).
`verbose`	If `TRUE`, displays progress messages.
`use.knitr`	If `TRUE`, parses all `Rmarkdown` files using the `knitr` package.
`auto.install.knitr`	If `TRUE` and the project contains rmarkdown files, then automatically included the packages `knitr` in packages to install.
`scan.rnw.with.knitr`	If `TRUE`, uses `knitr::knit()` to parse `.Rnw` files, otherwise use `utils::Sweave()`
`forceInstall`	If `TRUE`, forces the re-installation of all discovered packages and their dependencies. This is useful if, for some reason, the checkpoint archive becomes corrupted.
`forceProject`	If `TRUE`, forces the checkpoint process, even if the provided project folder doesn't look like an R project. A commonly reported user problem is that they accidentally trigger the checkpoint process from their home folder, resulting in scanning many R files and downloading many packages. To prevent this, we use a heuristic to determine if the project folder looks like an R project. If the project folder is the home folder, and also contains no R files, then `checkpoint()` asks for confirmation to continue.

Value

Checkpoint is called for its side-effects (see the details section), but invisibly returns a list with elements:

files_not_scanned
pkgs_found
pkgs_not_on_mran
pkgs_installed

Details

checkpoint() creates a local library into which it installs a copy of the packages required by your project as they existed on CRAN on the specified snapshot date. Your R session is updated to use only these packages.

To automatically determine all packages used in your project, the function scans all R code (.R, .Rmd, and .Rpres files) for library() and require() statements. In addition, scans for occurrences of code that accesses functions in namespaces using package[::]foo() and package[:::]foo(). Finally, any occurrences of the functions methods::setClass, methods::setRefClass, methods::setMethod or methods::setGeneric will also identify the methods package as a dependency.

Specifically, the function will:

Create a new local snapshot library to install packages. By default this library folder is at ~/.checkpoint but you can modify the path using the checkpointLocation argument.
Update the options for your CRAN mirror and point to an MRAN snapshot using options(repos)
Scan your project folder for all required packages and install them from the snapshot using utils::install.packages()

Resetting the checkpoint

To reset the checkpoint, simply restart your R session.

You can also use the experimental function unCheckpoint()

Changing the default MRAN url

By default, checkpoint() uses https to download packages. The default MRAN snapshot defaults to https://mran.microsoft.com/snapshot in R versions 3.2.0 and later, if https support is enabled.

You can modify the default URL. To change the URL, use options(checkpoint.mranUrl = ...).

Log file

As a side effect, the checkpoint function writes a log file with information about the downloaded files, in particular the package downloaded and the associated file size in bytes. The log is stored at the root of the checkpointLocation. For example, if checkpointLocation is the user home folder (the default) then the log file is at ~/.checkpoint/checkpoint_log.csv. This file contains columns for:

timestamp
snapshotDate
pkg
bytes

Last accessed date

The checkpoint() function stores a marker in the snapshot folder every time the function gets called. This marker contains the system date, thus indicating the the last time the snapshot was accessed. See also getAccessDate(). To remove snapshots that have not been used since a given date, use checkpointRemove()

Examples

## Not run: 

# Create temporary project and set working directory

example_project <- paste0("~/checkpoint_example_project_", Sys.Date())

dir.create(example_project, recursive = TRUE)
oldwd <- setwd(example_project)


# Write dummy code file to project

cat("library(MASS)", "library(foreach)",
    sep="\n",
    file="checkpoint_example_code.R")


# Create a checkpoint by specifying a snapshot date

library(checkpoint)
checkpoint("2014-09-17")

# Check that CRAN mirror is set to MRAN snapshot
getOption("repos")

# Check that library path is set to ~/.checkpoint
.libPaths()

# Check which packages are installed in checkpoint library
installed.packages()

# cleanup
unlink(example_project, recursive = TRUE)
setwd(oldwd)


## End(Not run)

[Package checkpoint version 0.4.3 Index]