RecreateLibrary: Recreate R Library
In inlmisc: Miscellaneous Functions for the USGS INL Project Office

Description Usage Arguments Details Value Note Author(s) Examples

Recreate an existing library on a new installation of R. The SavePackageDetails function writes the details of installed packages to a text file. And the RecreateLibrary function reads this file and downloads and installs any ‘missing’ packages from the Comprehensive R Archive Network (CRAN), CRAN-like repositories, and local package-installation files.

RecreateLibrary(
  file = "R-packages.tsv",
  lib = .libPaths()[1],
  repos = getOption("repos"),
  snapshot = FALSE,
  local = NULL,
  versions = FALSE,
  parallel = TRUE,
  quiet = FALSE
)

SavePackageDetails(file = "R-packages.tsv", lib = .libPaths(), pkg = NULL)

`file`	'character' string. Name of the file for reading (or writing) the list of package details. For a file name that does not contain an absolute path, the name is assumed relative to the current working directory (see `getwd` function). A ‘.gz’ file extension indicates the file is compressed by gzip.
`lib`	'character' vector. Library tree(s) to search through when locating installed packages (see `.libPaths` function), or the library directory where to install packages.
`repos`	'character' vector. Base URL(s) of the CRAN-like repositories (includes CRAN) to use when installing packages. For example, the URL of the RStudio sponsored CRAN mirror is `"https://cloud.r-project.org/"`. And the URL of the Geological Survey R Archive Network (GRAN) is `"https://owi.usgs.gov/R"`.
`snapshot`	'logical' flag, 'Date', or 'character' string. Calendar date for a CRAN snapshot in time, see the Microsoft R Application Network (MRAN) website for details. If true, the snapshot date is read from the first line of the package-details `file`. A snapshot date can also be specified directly using the required date format, YYYY-MM-DD. This argument masks any CRAN mirror specified in `repos`.
`local`	'character' vector. Paths to local repositories. Packages are installed from local files in these directories. Files can contain binary builds of packages (‘.zip’ on Windows and ‘.tgz’ on macOS) or be source packages (‘.tar.gz’).
`versions`	'logical' flag. If true, installed package versions will be identical to version numbers stored in the package-details `file`. Only applies to packages from CRAN-like repositories and local package-installation files. Requires that the devtools package is available.
`parallel`	'logical' flag or 'integer' count. Whether to use parallel processes for a parallel install of more than one source package. This argument can also be used to specify the number of cores to employ.
`quiet`	'logical' flag. Whether to reduce the amount of output.
`pkg`	'character' vector. Names of package(s) located under `lib`. Only packages specified in `pkg`, and the packages that `pkg` depend on/link to/import/suggest, will be included in the package-details `file`.

A typical workflow is as follows: Run the SavePackageDetails() command on an older version of R. It will print to a text file a complete list of details for packages located under your current R library tree(s). If the older version of R no longer needed, uninstall it. Then, on a freshly installed version of R with the inlmisc package available, run the RecreateLibrary() command. It will download and install the packages listed in the package-details file.

The type of package to download and install from CRAN-like repositories is binary on Windows and some macOS builds, and source on all others. Package installation from a local ‘.tar.gz’ file is always a source installation. If a package is installed from source, and it contains code that needs compiling, you must have a working development environment. On Windows, install the Rtools collection and have the PATH environment variable set up as required by Rtools. On macOS, install Xcode from the Mac App Store. And on Linux, install a compiler and various development libraries.

Daily snapshots of CRAN are stored on MRAN and available as far back as September 17, 2014. Use the snapshot argument to install older package versions from MRAN. Newer versions of R may not be compatible with older versions of packages. To avoid any package installation issues, install the R version that was available from CRAN on the snapshot date.

The package-details file is of the following format:

# Date modified: YYYY-MM-DD HH:MM:SS UTC
# R version 9.9.9 (YYYY-MM-DD)
Package Version
name    9.9.9
...     ...

Where the first two lines are reserved for the timestamp and R-version number, respectively. And package data are stored in a tabular structure, that is, data-table values are separated by a TAB character. The data format is flexible enough to add additional extraneous metadata and table fields, for example,

# Date modified: 2017-08-12 05:14:33 UTC
# R version 3.4.1 (2017-06-30)
# Running under: Windows 10 x64 (build 14393)
# Platform: x86_64-w64-mingw32
Package   Version Priority Depends       Imports
akima     0.6-2   NA       R (>= 2.0.0)  sp
animation 2.5     NA       R (>= 2.14.0) NA

The SavePackageDetails function returns (invisibly) the MD5 hash of the package-details file content. Any changes in the file content will produce a different MD5 hash. Use the md5sum function to verify that a file has not been changed. The RecreateLibrary function returns (invisibly) NULL.

This package-installation method does not offer one-hundred percent reproducibility of existing R libraries. Alternative methods, that offer better reproducibility, are available using the checkpoint and packrat packages; both of which provide robust tools for dependency management in R.

J.C. Fisher, U.S. Geological Survey, Idaho Water Science Center

# Run on old version of R
SavePackageDetails()

# Run on new version of R, and ensure 'inlmisc' package is available.
if (interactive()) {
  repos <- c(CRAN = "https://cloud.r-project.org/")
  if (system.file(package = "inlmisc") == "")
    utils::install.packages("inlmisc", repos = repos["CRAN"],
                            dependencies = TRUE)
  inlmisc::RecreateLibrary(repos = repos)
}

# Clean up example
file.remove("R-packages.tsv")