Update citation information

gesistsa · Aug 8, 2023 · 52fe7d8 · 52fe7d8
1 parent eb76625
commit 52fe7d8
Show file tree

Hide file tree

Showing 3 changed files with 278 additions and 5 deletions.
diff --git a/README.Rmd b/README.Rmd
@@ -27,7 +27,7 @@ To reconstruct a historical R computational environment, this package assumes on
 
 Please cite this package as:
 
-Chan CH, Schoch D (2023) rang: Reconstructing reproducible R computational environments. arXiv preprint:[2303.04758](https://doi.org/10.48550/arXiv.2303.04758)
+Chan 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)
 
 ## Installation
 
@@ -164,6 +164,140 @@ docker run -p 8787:8787 -e PASSWORD=abc123 --rm --name "rangtest" -ti rang
 
 With any browser, go to: `local:8787`. The default username is `rstudio`, password is as specified.
 
+### Using Apptainer/Singularity containers
+
+
+A `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.
+
+```r
+apptainerize(graph, "~/rocker_test")
+# singularize(graph, "~/rocker_test") # same function, as so far Apptainer is identical to Singularity
+```
+
+Now, you can build and run the Apptainer/Singularity container.
+
+For Apptainer installation:
+
+```bash
+cd ~/rocker_test
+apptainer build container.sif container.def
+apptainer run container.sif R
+```
+
+For Singularity installation:
+
+```bash
+cd ~/rocker_test
+sudo singularity build container.sif container.def
+singularity run container.sif R
+```
+
+Using the above example, `sessionInfo()` outputs the following. You have successfully gone back to the pre-pandemic.
+
+```
+R version 3.6.2 (2019-12-12) -- "Dark and Stormy Night"
+Copyright (C) 2019 The R Foundation for Statistical Computing
+Platform: x86_64-pc-linux-gnu (64-bit)
+
+R is free software and comes with ABSOLUTELY NO WARRANTY.
+You are welcome to redistribute it under certain conditions.
+Type 'license()' or 'licence()' for distribution details.
+
+R is a collaborative project with many contributors.
+Type 'contributors()' for more information and
+'citation()' on how to cite R or R packages in publications.
+
+Type 'demo()' for some demos, 'help()' for on-line help, or
+'help.start()' for an HTML browser interface to help.
+Type 'q()' to quit R.
+
+> sessionInfo()
+R version 3.6.2 (2019-12-12)
+Platform: x86_64-pc-linux-gnu (64-bit)
+Running under: Debian GNU/Linux 10 (buster)
+
+Matrix products: default
+BLAS/LAPACK: /usr/lib/x86_64-linux-gnu/libopenblasp-r0.3.5.so
+
+locale:
+ [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
+ [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
+ [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=C
+ [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
+ [9] LC_ADDRESS=C               LC_TELEPHONE=C
+[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
+
+attached base packages:
+[1] stats     graphics  grDevices utils     datasets  methods   base
+
+loaded via a namespace (and not attached):
+[1] compiler_3.6.2
+```
+
+`apptainerize()`/`singularize()` functions work exactly the same as `dockerize()`, except you cannot cache Linux distribution rootfs.
+
+### Apptainer/Singularity with RStudio IDE
+
+To run RStudio IDE in Apptainer/Singularity container, some writeable folders and a config file have to be created locally:
+
+```bash
+mkdir -p run var-lib-rstudio-server .rstudio
+printf 'provider=sqlite\ndirectory=/var/lib/rstudio-server\n' > database.conf
+```
+
+After that, you can run the container (do not run as `root` user, otherwise you will not be able to login to RStudio IDE).
+
+Start instance (on default RSTUDIO port 8787):
+
+```bash
+apptainer instance start \
+    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \
+    container.sif \
+    rangtest
+```
+
+Now open a browser and go to localhost:8787.
+The default username is your local username, default password is 'set_your_password' (if you are using container generated by rang).
+
+
+List running instances:
+
+```bash
+apptainer instance list
+```
+
+Stop instance:
+
+```bash
+apptainer instance stop rangtest
+```
+
+Start instance with custom port (e.g. 8080) and password:
+
+```bash
+apptainer instance start \
+    --env RPORT=8080
+    --env PASSWORD='set_your_password' \
+    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \
+    container.sif \
+    rangtest
+```
+
+Run container with custom `rserver` command line:
+
+```bash
+apptainer exec \
+    --env PASSWORD='set_your_password' \
+    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \
+    container.sif \
+    /usr/lib/rstudio-server/bin/rserver \
+    --auth-none=0 --auth-pam-helper-path=pam-helper \
+    --server-user=$(whoami) --www-port=8787
+```
+
+If 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.
+
+
 ## Recreate the computational environment for R < 3.1.0
 
 `rang` can still be used to recreate computational environments for R < 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 < 3.1.0 but not R < 1.3.1. The `image` parameter is ignored in this case.

diff --git a/README.md b/README.md
@@ -30,8 +30,8 @@ of R.
 Please cite this package as:
 
 Chan CH, Schoch D (2023) rang: Reconstructing reproducible R
-computational environments. arXiv
-preprint:[2303.04758](https://doi.org/10.48550/arXiv.2303.04758)
+computational environments. PLOS ONE
+<https://doi.org/10.1371/journal.pone.0286761>
 
 ## Installation
 
@@ -194,6 +194,145 @@ docker run -p 8787:8787 -e PASSWORD=abc123 --rm --name "rangtest" -ti rang
 With any browser, go to: `local:8787`. The default username is
 `rstudio`, password is as specified.
 
+### Using Apptainer/Singularity containers
+
+A `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.
+
+``` r
+apptainerize(graph, "~/rocker_test")
+# singularize(graph, "~/rocker_test") # same function, as so far Apptainer is identical to Singularity
+```
+
+Now, you can build and run the Apptainer/Singularity container.
+
+For Apptainer installation:
+
+``` bash
+cd ~/rocker_test
+apptainer build container.sif container.def
+apptainer run container.sif R
+```
+
+For Singularity installation:
+
+``` bash
+cd ~/rocker_test
+sudo singularity build container.sif container.def
+singularity run container.sif R
+```
+
+Using the above example, `sessionInfo()` outputs the following. You have
+successfully gone back to the pre-pandemic.
+
+    R version 3.6.2 (2019-12-12) -- "Dark and Stormy Night"
+    Copyright (C) 2019 The R Foundation for Statistical Computing
+    Platform: x86_64-pc-linux-gnu (64-bit)
+
+    R is free software and comes with ABSOLUTELY NO WARRANTY.
+    You are welcome to redistribute it under certain conditions.
+    Type 'license()' or 'licence()' for distribution details.
+
+    R is a collaborative project with many contributors.
+    Type 'contributors()' for more information and
+    'citation()' on how to cite R or R packages in publications.
+
+    Type 'demo()' for some demos, 'help()' for on-line help, or
+    'help.start()' for an HTML browser interface to help.
+    Type 'q()' to quit R.
+
+    > sessionInfo()
+    R version 3.6.2 (2019-12-12)
+    Platform: x86_64-pc-linux-gnu (64-bit)
+    Running under: Debian GNU/Linux 10 (buster)
+
+    Matrix products: default
+    BLAS/LAPACK: /usr/lib/x86_64-linux-gnu/libopenblasp-r0.3.5.so
+
+    locale:
+     [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
+     [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
+     [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=C
+     [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
+     [9] LC_ADDRESS=C               LC_TELEPHONE=C
+    [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
+
+    attached base packages:
+    [1] stats     graphics  grDevices utils     datasets  methods   base
+
+    loaded via a namespace (and not attached):
+    [1] compiler_3.6.2
+
+`apptainerize()`/`singularize()` functions work exactly the same as
+`dockerize()`, except you cannot cache Linux distribution rootfs.
+
+### Apptainer/Singularity with RStudio IDE
+
+To run RStudio IDE in Apptainer/Singularity container, some writeable
+folders and a config file have to be created locally:
+
+``` bash
+mkdir -p run var-lib-rstudio-server .rstudio
+printf 'provider=sqlite\ndirectory=/var/lib/rstudio-server\n' > database.conf
+```
+
+After that, you can run the container (do not run as `root` user,
+otherwise you will not be able to login to RStudio IDE).
+
+Start instance (on default RSTUDIO port 8787):
+
+``` bash
+apptainer instance start \
+    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \
+    container.sif \
+    rangtest
+```
+
+Now open a browser and go to localhost:8787. The default username is
+your local username, default password is ‘set\_your\_password’ (if you
+are using container generated by rang).
+
+List running instances:
+
+``` bash
+apptainer instance list
+```
+
+Stop instance:
+
+``` bash
+apptainer instance stop rangtest
+```
+
+Start instance with custom port (e.g. 8080) and password:
+
+``` bash
+apptainer instance start \
+    --env RPORT=8080
+    --env PASSWORD='set_your_password' \
+    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \
+    container.sif \
+    rangtest
+```
+
+Run container with custom `rserver` command line:
+
+``` bash
+apptainer exec \
+    --env PASSWORD='set_your_password' \
+    --bind run:/run,var-lib-rstudio-server:/var/lib/rstudio-server,database.conf:/etc/rstudio/database.conf,.rstudio:/home/rstudio/.rstudio/ \
+    container.sif \
+    /usr/lib/rstudio-server/bin/rserver \
+    --auth-none=0 --auth-pam-helper-path=pam-helper \
+    --server-user=$(whoami) --www-port=8787
+```
+
+If 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.
+
 ## Recreate the computational environment for R \< 3.1.0
 
 `rang` can still be used to recreate computational environments for R \<

diff --git a/inst/CITATION b/inst/CITATION
@@ -3,8 +3,8 @@ citHeader("To cite rang in publications use:")
 
 bibentry(bibtype = "article",
          title = "rang: Reconstructing reproducible R computational environments",
-         journal = "arXiv preprint 2303.04758",
+         journal = "PLOS ONE",
          author = c(person("Chung-hong", "Chan"), person("David", "Schoch")),
          url = "https://github.com/chainsawriot/rang",
          year = 2023,
-         doi = "10.48550/arXiv.2303.04758")
+         doi = "10.1371/journal.pone.0286761")