The GRAN repository system and reproducibility tools

Gabriel Becker, Dinakar Kulkarni

09 May, 2018


GRANBase is an open source set of tools for testing and deploying R packages as package repositories for both general deployment and result reproduction. It is based on the switchr framework, and allows users to deploy package manifests as validated repositories.It is centered around the R repository mechanism for pacakge distribution. GRANBase provides three major areas of functionality:

Creating GRANBase repositories

GRANBase relies on the GRANCore framework for repository management, which in turn is based on package manifests (PkgManifest or SeedingManifest objects from the switchr framework).

Given a manifest, initial construction and rebuilding of individual GRANBase repositories (referred to as subrepositories because GRANBase supports a form of branched deployment) is performed via the makeRepo function. For example:

testpkgs <- list.files(system.file("testpkgs", package = "GRANBase"),
                       full.names = TRUE)
man <- PkgManifest(name = basename(testpkgs),
                  url = testpkgs, type = "local")
repdir <- file.path(tempdir(), "repos")
if(!file.exists(repdir)) dir.create(repdir)
repo <- makeRepo(man,
                repo_name= "stable",
                basedir = repdir,
                destination = repdir,
                cores = 1L,
                install_test = FALSE,
                check_test = FALSE)

NOTE: In the above code, we disabled the installation and R CMD check-related tests due to not playing well with the CRAN build system. In most cases, these should be TRUE in order to create a validated package repository. Also note that in the output below, the willfail package appears in the repository. This would not be the case if the check test was turned on, as it is engineered as a test case to fail check.

available.packages(repo, type="source")
#>            Package      Version  Priority
#> GRANBase   "GRANBase"   "2.5.0"  NA      
#> GRANCore   "GRANCore"   "0.2.1"  NA      
#> GRANstable "GRANstable" "0.10.0" NA      
#> deptest    "deptest"    "1.0"    NA      
#> switchr    "switchr"    "0.12.8" NA      
#> toyp       "toyp"       "1.0"    NA      
#> toypkg     "toypkg"     "1.0"    NA      
#> willfail   "willfail"   "1.0"    NA      
#>            Depends                                     
#> GRANBase   "GRANCore, switchr (>= 0.9.28), methods"    
#> GRANCore   "R (>= 3.1.0), switchr (>= 0.9.28), methods"
#> GRANstable "GRANCore"                                  
#> deptest    "toypkg"                                    
#> switchr    "methods"                                   
#> toyp       NA                                          
#> toypkg     NA                                          
#> willfail   NA                                          
#>            Imports                                                                                                  
#> GRANBase   "tools, utils, htmlTable (>= 1.11.0), dplyr, sendmailR, covr,\nRCurl, jsonlite, stringi, stats, markdown"
#> GRANCore   NA                                                                                                       
#> GRANstable NA                                                                                                       
#> deptest    NA                                                                                                       
#> switchr    "tools, RJSONIO, RCurl"                                                                                  
#> toyp       NA                                                                                                       
#> toypkg     NA                                                                                                       
#> willfail   NA                                                                                                       
#>            LinkingTo Suggests                                 Enhances
#> GRANBase   NA        "parallel, rmarkdown, hexSticker, knitr" NA      
#> GRANCore   NA        NA                                       NA      
#> GRANstable NA        NA                                       NA      
#> deptest    NA        NA                                       NA      
#> switchr    NA        "BiocInstaller"                          NA      
#> toyp       NA        NA                                       NA      
#> toypkg     NA        NA                                       NA      
#> willfail   NA        NA                                       NA      
#>            License        License_is_FOSS License_restricts_use OS_type
#> GRANBase   "Artistic-2.0" NA              NA                    NA     
#> GRANCore   "Artistic-2.0" NA              NA                    NA     
#> GRANstable "Artistic-2.0" NA              NA                    NA     
#> deptest    "Artistic-2.0" NA              NA                    NA     
#> switchr    "Artistic-2.0" NA              NA                    NA     
#> toyp       "Artistic-2.0" NA              NA                    NA     
#> toypkg     "Artistic-2.0" NA              NA                    NA     
#> willfail   "Artistic-2.0" NA              NA                    NA     
#>            Archs MD5sum                             NeedsCompilation File
#> GRANBase   NA    "d4551a2997b44726b231dcd37b2569fa" "no"             NA  
#> GRANCore   NA    "0bccdcd0f242ac3fe940e5e4eb0734c2" "no"             NA  
#> GRANstable NA    "21455eff94d1fc4c70fe6415e2fa1892" "no"             NA  
#> deptest    NA    "f3e61d74448b8dae52e3d739064ac8f6" "no"             NA  
#> switchr    NA    "06e6c855a35ba5d019bb0bb0e7bb5bff" "no"             NA  
#> toyp       NA    "e95d016e23dbc23a03b7935a45da36bd" "no"             NA  
#> toypkg     NA    "8c24c6957f8142e09315a36d68961210" "no"             NA  
#> willfail   NA    "cdef9616813a49172fee1b9d780e3bce" "no"             NA  
#>            Repository                                                                                   
#> GRANBase   "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"
#> GRANCore   "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"
#> GRANstable "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"
#> deptest    "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"
#> switchr    "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"
#> toyp       "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"
#> toypkg     "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"
#> willfail   "file:///var/folders/79/l_n_5qr152d2d9d9xs0591lh0000gn/T/Rtmp9B2Qlw/repos/stable/src/contrib"

Note that the repository contains the package GRANstable. This was generated automatically, and exports a defaultGRAN() function which the switchr package will use when the package is loaded to incorporate our package into the set of default repositories.

GRANBase represents (sub)repositories as GRANRepository objects, which come from the GRANCore package. These objects contain all the information required to build and deploy the repository.

Once a repository is created, its GRANRepository object is saved within the created directory structure as the repo.R file. This allows future builds to be invoked by the simpler syntax of passing a GRANRepository object or path to a created repository to makeRepo() directly:

repo <- makeRepo(file.path(repdir, "stable"), cores=1L)

The makeRepo() function also accepts a build_pkgs argument, which will cause only the specified packages (and their reverse dependencies) to be rebuilt, regardless of changes in version number.

repo2 <- makeRepo(repo,
                  build_pkgs = basename(testpkgs)[1],
                  cores = 1L)

The repository build process

GRANBase performs the following steps when creating or updating a repository. At the end of each step, the packages’ statuses are updated to reflect the results of that step.

Tools for managing repository stability

GRANBase also provides tools to navigate the tension between stability and using the most up-to-date version of packages to have the latest bug fixes available.

The identifyRisk function identifies which currently installed packages can be updated, and determines the packages that could possibly be affected by updating the package. In particular, the function allows the user to identify a vector of important packages and assesses the risks to each of them (by default, it takes that to be the full set of installed packages).

Risk here has a dual meaning. On the one hand updating a package which an important package depends on incurs the risk of changing the important package’s behavior, potentially changing results in a critical application. On the other hand, not updating a such a package may leave important bug fixes un-applied, drawing the results generated when using the important package into question.

buildRiskReport builds an HTML report which lists information about each package with an update available in an easy to digest table. It also provides a list of specific risks to each important package (packages with no risks identified are currently omitted).

An update risk report generated by buildRiskReport()

An update risk report generated by buildRiskReport()