{"id":14066267,"url":"https://github.com/gesistsa/rang","last_synced_at":"2025-05-05T03:21:20.619Z","repository":{"id":65927760,"uuid":"588944592","full_name":"gesistsa/rang","owner":"gesistsa","description":"🐶 (Re)constructing R computational environments","archived":false,"fork":false,"pushed_at":"2025-02-04T15:10:24.000Z","size":17586,"stargazers_count":81,"open_issues_count":16,"forks_count":3,"subscribers_count":6,"default_branch":"v0.3","last_synced_at":"2025-05-03T10:02:23.132Z","etag":null,"topics":["cran","r","reproducibility","reproducible-research","rstats"],"latest_commit_sha":null,"homepage":"https://gesistsa.github.io/rang/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gesistsa.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-14T15:05:43.000Z","updated_at":"2025-04-08T14:05:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"e459326c-b493-4d4d-88ac-352b4edbb55a","html_url":"https://github.com/gesistsa/rang","commit_stats":null,"previous_names":["gesistsa/rang","chainsawriot/rang"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesistsa%2Frang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesistsa%2Frang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesistsa%2Frang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesistsa%2Frang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gesistsa","download_url":"https://codeload.github.com/gesistsa/rang/tar.gz/refs/heads/v0.3","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252430272,"owners_count":21746629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cran","r","reproducibility","reproducible-research","rstats"],"created_at":"2024-08-13T07:05:01.048Z","updated_at":"2025-05-05T03:21:20.593Z","avatar_url":"https://github.com/gesistsa.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# rang \u003cimg src=\"man/figures/rang_logo.png\" align=\"right\" width = \"120\" /\u003e\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/gesistsa/rang/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/gesistsa/rang/actions/workflows/R-CMD-check.yaml)\n\u003c!-- badges: end --\u003e\n\nThe goal of rang (Reconstructing Ancient Number-crunching Gears) [^gesis] is to obtain the dependency graph of R packages at a specific time point.\n\nAlthough this package can also be used to ensure the current R computational environment can be reconstructed by future researchers, this package gears towards reconstructing historical R computational environments which have not been completely declared. For the former purpose, packages such as [renv](https://github.com/rstudio/renv/), [groundhog](https://github.com/CredibilityLab/groundhog), [miniCRAN](https://github.com/andrie/miniCRAN), and [Require](https://github.com/PredictiveEcology/Require) should be used. One can think of rang as an archaeological tool.\n\nTo reconstruct a historical R computational environment, this package assumes only the availability of source packages online. The reconstruction procedures have been tested in several vintage versions of R.\n\nPlease cite this package as:\n\nChan CH, Schoch D (2023) rang: Reconstructing reproducible R computational environments. PLOS ONE [https://doi.org/10.1371/journal.pone.0286761](https://doi.org/10.1371/journal.pone.0286761)\n\n## Installation\n\nYou can install the development version of rang like so:\n\n``` r\nremotes::install_github(\"gesistsa/rang\")\n```\n\nOr the stable CRAN version\n\n```r\ninstall.packages(\"rang\")\n```\n\n## Example\n\nTo obtain the dependency graph of R packages, use `resolve`. Currently, this package supports CRAN, Bioconductor, GitHub, and local packages.\n\n```r\nlibrary(rang)\nx \u003c- resolve(pkgs = c(\"sna\", \"schochastics/rtoot\", \"S4Vectors\"), snapshot_date = \"2022-11-30\")\n```\n\n```r\ngraph \u003c- resolve(pkgs = c(\"openNLP\", \"LDAvis\", \"topicmodels\", \"quanteda\"),\n                 snapshot_date = \"2020-01-16\")\n```\n\n```{r, include = FALSE}\ndevtools::load_all()\ngraph \u003c- readRDS(\"tests/testdata/graph.RDS\")\n```\n\n```{r example1}\ngraph\n```\n\n```{r example2}\ngraph$sysreqs\n```\n\n```{r example 3}\ngraph$r_version\n```\n\nThe resolved result is an S3 object called `rang` and can be exported as an installation script. The installation script can be execute on a vanilla R installation.\n\n```r\nexport_rang(graph, \"rang.R\")\n```\n\nHowever, the execution of the installation script often fails (now) due to missing system dependencies and incompatible R versions. Therefore, the approach outlined below should be used.\n\n## Recreate the computational environment via Rocker\n\nA `rang` object can be used to recreate the computational environment via [Rocker](https://github.com/rocker-org/rocker). Please note that the oldest R version one can get from Rocker is R 3.1.0.\n\n```r\ndockerize(graph, \"~/rocker_test\")\n```\n\nNow, you can build and run the Docker container.\n\n```bash\ncd ~/rocker_test\ndocker build -t rang .\ndocker run --rm --name \"rangtest\" -ti rang\n```\n\nUsing the above example, `sessionInfo()` outputs the following. You have successfully gone back to the pre-pandemic time.\n\n```\nR version 3.6.2 (2019-12-12)\nPlatform: x86_64-pc-linux-gnu (64-bit)\nRunning under: Debian GNU/Linux 10 (buster)\n\nMatrix products: default\nBLAS/LAPACK: /usr/lib/x86_64-linux-gnu/libopenblasp-r0.3.5.so\n\nlocale:\n [1] LC_CTYPE=en_US.UTF-8          LC_NUMERIC=C                 \n [3] LC_TIME=en_US.UTF-8           LC_COLLATE=en_US.UTF-8       \n [5] LC_MONETARY=en_US.UTF-8       LC_MESSAGES=C                \n [7] LC_PAPER=en_US.UTF-8          LC_NAME=en_US.UTF-8          \n [9] LC_ADDRESS=en_US.UTF-8        LC_TELEPHONE=en_US.UTF-8     \n[11] LC_MEASUREMENT=en_US.UTF-8    LC_IDENTIFICATION=en_US.UTF-8\n\nattached base packages:\n[1] stats     graphics  grDevices utils     datasets  methods   base     \n\nother attached packages:\n[1] topicmodels_0.2-9 LDAvis_0.3.2      openNLP_0.2-7     quanteda_1.5.2   \n\nloaded via a namespace (and not attached):\n [1] NLP_0.2-0           Rcpp_1.0.3          pillar_1.4.3       \n [4] compiler_3.6.2      tools_3.6.2         stopwords_1.0      \n [7] lubridate_1.7.4     lifecycle_0.1.0     tibble_2.1.3       \n[10] gtable_0.3.0        lattice_0.20-38     pkgconfig_2.0.3    \n[13] rlang_0.4.2         Matrix_1.2-18       fastmatch_1.1-0    \n[16] parallel_3.6.2      openNLPdata_1.5.3-4 rJava_0.9-11       \n[19] xml2_1.2.2          stringr_1.4.0       stats4_3.6.2       \n[22] grid_3.6.2          data.table_1.12.8   R6_2.4.1           \n[25] ggplot2_3.2.1       spacyr_1.2          magrittr_1.5       \n[28] scales_1.1.0        modeltools_0.2-22   colorspace_1.4-1   \n[31] stringi_1.4.5       RcppParallel_4.4.4  lazyeval_0.2.2     \n[34] munsell_0.5.0       tm_0.7-7            slam_0.1-47        \n[37] crayon_1.3.4    \n```\n\n### Caching R packages\n\nOne can also cache (or archive) the R packages from CRAN and Github at the time `dockerize` is executed. The cached R packages will then transfer to the container. Please note that system requirements (i.e. `deb` packages) are not cached.\n\n```r\ndockerize(graph, \"~/rocker_test\", cache = TRUE)\n```\n\n### Using alternative Rocker images\n\nOne can also select other Rocker versioned images: `rstudio`, `tidyverse`, `verse`, `geospatial`.\n\n```r\ndockerize(graph, \"~/rocker_test\", image = \"rstudio\")\n```\n\n`tidyverse`, `verse`, and `geospatial` are similar to the default (`r-ver`). For `rstudio`, one needs to build and launch it with:\n\n```bash\ncd ~/rocker_test\ndocker build -t rang .\ndocker run -p 8787:8787 -e PASSWORD=abc123 --rm --name \"rangtest\" -ti rang\n```\n\nWith any browser, go to: `local:8787`. The default username is `rstudio`, password is as specified.\n\n### Using Apptainer/Singularity containers\n\n\nA `rang` object can be used to recreate the computational environment via [Rocker](https://github.com/rocker-org/rocker). Instead of Docker you can also use [Apptainer/Singularity](https://apptainer.org/). Please note that the oldest R version one can get from Rocker is R 3.1.0.\n\n```r\napptainerize(graph, \"~/rocker_test\")\n# singularize(graph, \"~/rocker_test\") # same function, as so far Apptainer is identical to Singularity\n```\n\nNow, you can build and run the Apptainer/Singularity container.\n\nFor Apptainer installation:\n\n```bash\ncd ~/rocker_test\napptainer build container.sif container.def\napptainer run container.sif R\n```\n\nFor Singularity installation:\n\n```bash\ncd ~/rocker_test\nsudo singularity build container.sif container.def\nsingularity run container.sif R\n```\n\nUsing the above example, `sessionInfo()` outputs the following. You have successfully gone back to the pre-pandemic.\n\n```\nR version 3.6.2 (2019-12-12) -- \"Dark and Stormy Night\"\nCopyright (C) 2019 The R Foundation for Statistical Computing\nPlatform: x86_64-pc-linux-gnu (64-bit)\n\nR is free software and comes with ABSOLUTELY NO WARRANTY.\nYou are welcome to redistribute it under certain conditions.\nType 'license()' or 'licence()' for distribution details.\n\nR is a collaborative project with many contributors.\nType 'contributors()' for more information and\n'citation()' on how to cite R or R packages in publications.\n\nType 'demo()' for some demos, 'help()' for on-line help, or\n'help.start()' for an HTML browser interface to help.\nType 'q()' to quit R.\n\n\u003e sessionInfo()\nR version 3.6.2 (2019-12-12)\nPlatform: x86_64-pc-linux-gnu (64-bit)\nRunning under: Debian GNU/Linux 10 (buster)\n\nMatrix products: default\nBLAS/LAPACK: /usr/lib/x86_64-linux-gnu/libopenblasp-r0.3.5.so\n\nlocale:\n [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C\n [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8\n [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=C\n [7] LC_PAPER=en_US.UTF-8       LC_NAME=C\n [9] LC_ADDRESS=C               LC_TELEPHONE=C\n[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C\n\nattached base packages:\n[1] stats     graphics  grDevices utils     datasets  methods   base\n\nloaded via a namespace (and not attached):\n[1] compiler_3.6.2\n```\n\n`apptainerize()`/`singularize()` functions work exactly the same as `dockerize()`, except you cannot cache Linux distribution rootfs.\n\n### Apptainer/Singularity with RStudio IDE\n\nTo run RStudio IDE in Apptainer/Singularity container, some writeable folders and a config file have to be created locally:\n\n```bash\nmkdir -p run var-lib-rstudio-server .rstudio\nprintf 'provider=sqlite\\ndirectory=/var/lib/rstudio-server\\n' \u003e database.conf\n```\n\nAfter that, you can run the container (do not run as `root` user, otherwise you will not be able to login to RStudio IDE).\n\nStart instance (on default RSTUDIO port 8787):\n\n```bash\napptainer instance start \\\n    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \\\n    container.sif \\\n    rangtest\n```\n\nNow open a browser and go to localhost:8787.\nThe default username is your local username, default password is 'set_your_password' (if you are using container generated by rang).\n\n\nList running instances:\n\n```bash\napptainer instance list\n```\n\nStop instance:\n\n```bash\napptainer instance stop rangtest\n```\n\nStart instance with custom port (e.g. 8080) and password:\n\n```bash\napptainer instance start \\\n    --env RPORT=8080\n    --env PASSWORD='set_your_password' \\\n    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \\\n    container.sif \\\n    rangtest\n```\n\nRun container with custom `rserver` command line:\n\n```bash\napptainer exec \\\n    --env PASSWORD='set_your_password' \\\n    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \\\n    container.sif \\\n    /usr/lib/rstudio-server/bin/rserver \\\n    --auth-none=0 --auth-pam-helper-path=pam-helper \\\n    --server-user=$(whoami) --www-port=8787\n```\n\nIf you run the container using `apptainer exec` command, you will have to kill the `rserver` process manually or Cmd/Ctrl+C from the running container to stop the server.\n\n\n## Recreate the computational environment for R \u003c 3.1.0\n\n`rang` can still be used to recreate computational environments for R \u003c 3.1.0. The Dockerfile generated is based on Debian Lenny (5.0) and the requested version of R is compiled from source. As of writing, this method works for R \u003c 3.1.0 but not R \u003c 1.3.1. The `image` parameter is ignored in this case.\n\n```r\nrang_rio \u003c- resolve(\"rio\", snapshot_date = \"2013-08-30\") ## R 3.0.1\ndockerize(rang_rio, output_dir = \"~/old_renviron\")\n```\n\n## `evercran` support (experimental)\n\n`rang` supports [evercran](https://github.com/r-hub/evercran). As of writing, the support is still experimental (just like `evercran` itself). In the future, `evercran` will replace the Debian method.\n\n```r\nrang_rio \u003c- resolve(\"rio\", snapshot_date = \"2013-08-30\") ## R 3.0.1\ndockerize(rang_rio, output_dir = \"~/old_renviron\", method = \"evercran\")\n```\n\n## Acknowledgment\n\nThe logo of rang is a remix of [this](https://commons.wikimedia.org/wiki/File:Flag_of_the_Canary_Islands.svg) public domain image. The two dogs should be *Presa Canario*, the native dog breed on the islands of Gran Canaria and Tenerife.\n\n---\n\n[^gesis]: It stands for \"R Archiving Nerds at GESIS\". The package was previously named `gran`, but we decided to rename it to `rang` because there is another package named [gRAN](https://CRAN.R-project.org/package=GRANBase).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesistsa%2Frang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgesistsa%2Frang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesistsa%2Frang/lists"}