Title:	Reconstructing Reproducible R Computational Environments
Version:	0.3.0
Description:	Resolve the dependency graph of R packages at a specific time point based on the information from various 'R-hub' web services https://blog.r-hub.io/. The dependency graph can then be used to reconstruct the R computational environment with 'Rocker' https://rocker-project.org.
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.2.3
URL:	https://github.com/gesistsa/rang
BugReports:	https://github.com/gesistsa/rang/issues
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Imports:	parsedate, fastmap, jsonlite, memoise, pkgsearch, remotes, utils, httr, vctrs, renv, here
Depends:	R (≥ 3.5.0)
VignetteBuilder:	knitr
LazyData:	true
NeedsCompilation:	no
Packaged:	2023-10-08 13:29:24 UTC; chainsawriot
Author:	Chung-hong Chan [aut, cre], David Schoch [aut], Egor Kotov [ctb]
Maintainer:	Chung-hong Chan <chainsawtiney@gmail.com>
Repository:	CRAN
Date/Publication:	2023-10-08 14:50:02 UTC

Create an Apptainer/Singularity Definition File of The Resolved Result

Description

This function exports the result from resolve() to an Apptainer/Singularity definition file. For R version >= 3.1.0, the file is based on the versioned Rocker Docker image. For R version < 3.1.0, the Apptainer/Singularity definition is based on Debian and it compiles R from source.

Usage

apptainerize(
  rang,
  output_dir,
  materials_dir = NULL,
  post_installation_steps = NULL,
  image = c("r-ver", "rstudio", "tidyverse", "verse", "geospatial"),
  rang_as_comment = TRUE,
  cache = FALSE,
  verbose = TRUE,
  lib = NA,
  cran_mirror = "https://cran.r-project.org/",
  check_cran_mirror = TRUE,
  bioc_mirror = "https://bioconductor.org/packages/",
  no_rocker = FALSE,
  debian_version = c("lenny", "squeeze", "wheezy", "jessie", "stretch"),
  skip_r17 = TRUE,
  insert_readme = TRUE,
  copy_all = FALSE
)

apptainerize_rang(...)

apptainerise(...)

apptainerise_rang(...)

singularize(...)

singularize_rang(...)

singularise(...)

singularise_rang(...)

Arguments

Details

The idea behind this is to determine the installation order of R packages locally. Then, the installation script can be deployed to another fresh R session to install R packages. dockerize() and apptainerize() are more reasonable ways because a fresh R session with all system requirements is provided. The current approach does not work in R < 2.1.0.

Value

output_dir, invisibly

References

Apptainer / Singularity

Kurtzer, G. M., Sochat, V., & Bauer, M. W. (2017) Singularity: Scientific containers for mobility of compute. PLOS ONE, 12(5):e0177459. doi:10.1371/journal.pone.0177459

The Rocker Project

Ripley, B. (2005) Packages and their Management in R 2.1.0. R News, 5(1):8–11.

See Also

resolve(), export_rang(), use_rang()

Examples

if (interactive()) {
    graph <- resolve(
        pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
        snapshot_date = "2020-01-16"
    )
    apptainerize(graph, ".")
    ## An example of using post_installation_steps to install quarto
    install_quarto <- c("apt-get install -y curl git && \\
    curl -LO https://quarto.org/download/latest/quarto-linux-amd64.deb && \\
    dpkg -i quarto-linux-amd64.deb && \\
    quarto install tool tinytex")
    apptainerize(graph, ".", post_installation_steps = install_quarto)
}

Convert Data Structures into Package References

Description

This generic function converts several standard data structures into a vector of package references, which in turn can be used as the first argument of the function resolve(). This function guessimates the possible sources of the packages. But we strongly recommend manually reviewing the detected packages before using them for resolve().

Usage

as_pkgrefs(x, ...)

## Default S3 method:
as_pkgrefs(x, ...)

## S3 method for class 'character'
as_pkgrefs(x, bioc_version = NULL, no_enhances = TRUE, no_suggests = TRUE, ...)

## S3 method for class 'sessionInfo'
as_pkgrefs(x, ...)

Arguments

Value

a vector of package references

Examples

as_pkgrefs(sessionInfo())
if (interactive()) {
   require(rang)
   graph <- resolve(as_pkgrefs(sessionInfo()))
   as_pkgrefs(c("rtoot"))
   as_pkgrefs(c("rtoot", "S4Vectors")) ## this gives cran::S4Vectors and is not correct.
   as_pkgrefs(c("rtoot", "S4Vectors"), bioc_version = "3.3") ## This gives bioc::S4Vectors
}

Convert Data Structures to rang edgelist

Description

This generic function converts several data structures provided by rang into an edgelist of package dependencies.

Usage

convert_edgelist(x, ...)

## Default S3 method:
convert_edgelist(x, ...)

## S3 method for class 'ranglet'
convert_edgelist(x, ...)

## S3 method for class 'rang'
convert_edgelist(x, ...)

Arguments

Details

the resulting data frame can be converted to an igraph object for plotting and analysis via the function igraph::graph_from_data_frame()

Value

a data frame of directed edges of dependencies

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                snapshot_date = "2020-01-16")
                
    # dependency edgelist of a single package
    convert_edgelist(graph$ranglets[[1]])
    
    # full dependency edgelist
    convert_edgelist(graph)
}

Create executable research compendium according to the Turing Way

Description

This usethis-style function creates an executable research compendium according to the Turing Way.

Usage

create_turing(
  path,
  add_rang = TRUE,
  add_makefile = TRUE,
  add_here = TRUE,
  verbose = TRUE,
  force = FALSE,
  apptainer = FALSE
)

Arguments

Details

According to the Turing Way, an executable research compendium should have the following properties

1. Files should be organized in a conventional folder structure;

2. Data, methods, and output should be clearly separated;

3. The computational environment should be specified.

We use the structure suggested by the Turing Way:

• data_raw: a directory to hold the raw data

• data_clean: a directory to hold the processed data

• code: a directory to hold computer code

• CITATION: a file holding citation information

• paper.Rmd: a manuscript This function provides the a clearly separated organizational structure. Components can be changed. For example, the manuscript can be in another format (e.g. quarto, sweave) or even optional. With add_rang, the computational environment can be recorded and reconstructed later.

Value

path, invisibly

References

The Turing Way: Research Compendia Gorman, KB, Williams TD. and Fraser WR (2014). Ecological Sexual Dimorphism and Environmental Variability within a Community of Antarctic Penguins (Genus Pygoscelis). PLoS ONE 9(3):e90081. doi:10.1371/journal.pone.0090081

See Also

use_rang()

Dockerize The Resolved Result

Description

This function exports the result from resolve() to a Docker file. For R version >= 3.1.0, the Dockerfile is based on the versioned Rocker image. For R version < 3.1.0, the Dockerfile is based on Debian and it compiles R from source.

Usage

dockerize(
  rang,
  output_dir,
  materials_dir = NULL,
  post_installation_steps = NULL,
  image = c("r-ver", "rstudio", "tidyverse", "verse", "geospatial"),
  rang_as_comment = TRUE,
  cache = FALSE,
  verbose = TRUE,
  lib = NA,
  cran_mirror = "https://cran.r-project.org/",
  check_cran_mirror = TRUE,
  bioc_mirror = "https://bioconductor.org/packages/",
  no_rocker = FALSE,
  debian_version = c("lenny", "squeeze", "wheezy", "jessie", "stretch"),
  skip_r17 = TRUE,
  insert_readme = TRUE,
  copy_all = FALSE
)

dockerize_rang(...)

dockerise(...)

dockerise_rang(...)

Arguments

Details

The idea behind this is to determine the installation order of R packages locally. Then, the installation script can be deployed to another fresh R session to install R packages. dockerize() and apptainerize() are more reasonable ways because a fresh R session with all system requirements is provided. The current approach does not work in R < 2.1.0.

Value

output_dir, invisibly

References

The Rocker Project Ripley, B. (2005) Packages and their Management in R 2.1.0. R News, 5(1):8–11.

See Also

resolve(), export_rang(), use_rang()

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                    snapshot_date = "2020-01-16")
    dockerize(graph, ".")
    ## An example of using post_installation_steps to install quarto
    install_quarto <- c("RUN apt-get install -y curl git && \\
    curl -LO https://quarto.org/download/latest/quarto-linux-amd64.deb && \\
    dpkg -i quarto-linux-amd64.deb && \\
    quarto install tool tinytex")
    dockerize(graph, ".", post_installation_steps = install_quarto)
}

Export The Resolved Result As Installation Script

Description

This function exports the results from resolve() to an installation script that can be run in a fresh R environment.

Usage

export_rang(
  rang,
  path,
  rang_as_comment = TRUE,
  verbose = TRUE,
  lib = NA,
  cran_mirror = "https://cran.r-project.org/",
  check_cran_mirror = TRUE,
  bioc_mirror = "https://bioconductor.org/packages/"
)

Arguments

Details

The idea behind this is to determine the installation order of R packages locally. Then, the installation script can be deployed to another fresh R session to install R packages. dockerize() and apptainerize() are more reasonable ways because a fresh R session with all system requirements is provided. The current approach does not work in R < 2.1.0.

Value

path, invisibly

References

Ripley, B. (2005) Packages and their Management in R 2.1.0. R News, 5(1):8–11.

See Also

generate_installation_order()

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                    snapshot_date = "2020-01-16")
    export_rang(graph, "rang.R")
}

Export The Resolved Result As a renv Lockfile

Description

This function exports the results from resolve() to a renv lockfile that can be used as an alternative to a docker container.

Usage

export_renv(rang, path = ".")

Arguments

Details

A renv lockfile is easier to handle than a docker container, but it cannot always reliably reproduce the exact computational environment,especially for very old code.

Value

path, invisibly

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                    snapshot_date = "2020-01-16")
    export_renv(graph, ".")
}

Create a Data Frame of The Resolved Result This function exports the results from resolve() to a data frame, which each row represents one installation step. The order of rows is the installation order. By installing packages in the specified order, one can install all the resolved packages without conflicts.

Description

Create a Data Frame of The Resolved Result This function exports the results from resolve() to a data frame, which each row represents one installation step. The order of rows is the installation order. By installing packages in the specified order, one can install all the resolved packages without conflicts.

Usage

generate_installation_order(rang)

Arguments

Value

A data frame ordered by installation order.

References

Ripley, B. (2005) Packages and their Management in R 2.1.0. R News, 5(1):8–11.

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                    snapshot_date = "2020-01-16")
    generate_installation_order(graph)
}

Query for System Requirements

Description

This function takes an S3 object returned from resolve() and (re)queries the System Requirements.

Usage

query_sysreqs(rang, os = "ubuntu-20.04")

Arguments

Value

a rang S3 object with the following items

See Also

resolve()

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                snapshot_date = "2020-01-16", query_sysreqs = FALSE)
    graph$sysreqs
    graph2 <- query_sysreqs(graph, os = "ubuntu-20.04")
    graph2$sysreqs
}

Recipes for Building Container Images

Description

A list containing several useful recipes for container building. Useful for the post_installation_steps argument of dockerize(). Available recipes are:

• texlive: install pandoc and LaTeX, useful for rendering RMarkdown

• texlivefull: Similar to the above, but install the full distribution of TeX Live (~ 3GB)

• quarto: install quarto and tinytex

• clean: clean up the container image by removing cache

• make: install GNU make

Usage

recipes

Format

An object of class list of length 5.

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                    snapshot_date = "2020-01-16")
    ## install texlive
    dockerize(graph, ".", post_installation_steps = recipes[['texlive']])
}

Resolve Dependencies Of R Packages

Description

This function recursively queries dependencies of R packages at a specific snapshot time. The dependency graph can then be used to recreate the computational environment. The data on dependencies are provided by R-hub.

Usage

resolve(
  pkgs = ".",
  snapshot_date,
  no_enhances = TRUE,
  no_suggests = TRUE,
  query_sysreqs = TRUE,
  os = "ubuntu-20.04",
  verbose = FALSE
)

Arguments

Value

a rang S3 object with the following items

References

Package References

See Also

dockerize()

Examples

if (interactive()) {
    graph <- resolve(pkgs = c("openNLP", "LDAvis", "topicmodels", "quanteda"),
                snapshot_date = "2020-01-16")
    graph
    ## to resolve github packages
    gh_graph <- resolve(pkgs = c("https://github.com/schochastics/rtoot"),
                   snapshot_date = "2022-11-28")
    gh_graph
    ## scanning
    graph <- resolve(snapshot_date = "2022-11-28")
    ## But we recommend this:
    pkgs <- as_pkgrefs(".")
    pkgs ## check the accuracy
    graph <- resolve(pkgs, snapshot_date = "2022-11-28")
}

Setup rang for a directory

Description

This usethis-style function adds the infrastructure in a directory (presumably with R scripts and data) for (re)constructing the computational environment. Specifically, this function inserts inst/rang into the directory, which contains all components for the reconstruction. Optionally, Makefile and .here are also inserted to ease the development of analytic code. By default, (re)running this function does not overwrite any file. One can change this by setting force to TRUE.

Usage

use_rang(
  path = ".",
  add_makefile = TRUE,
  add_here = TRUE,
  verbose = TRUE,
  force = FALSE,
  apptainer = FALSE
)

Arguments

Details

The infrastructure being added to your path consists of:

• inst/rang directory in the project root

• update.R file inside the directory

• .here in the project root (if add_here is TRUE)

• Makefile in the project root (if add_makefile is TRUE) You might need to edit update.R manually. The default is to scan the whole project for used R packages and assume they are either on CRAN or Bioconductor. If you have used other R packages, you might need to edit this manually.

Value

path, invisibly