Understanding Packaging in R

0
49

In this eighth article in the R series, we shall explore the packaging of R code and publishing it for end users. We will be using R version 4.1.2 installed on Parabola GNU/Linux-libre (x86-64) for the code snippets.

By now we know that the R programming language comes with pre-built functions. The base installation of R provides packages with essential functions.

Install
The default list of packages available in the system can be fetched using the following command:

> getOption(“defaultPackages”)
[1] “datasets”  “utils”     “grDevices” “graphics”  “stats”     “methods”

If you need to install new packages in the R console, you can use the command given below to do so:

> install.packages(“RUnit”)

You will need to load the library in the R session before using its functions. For example:

> library(RUnit)

The present active packages that have been loaded into the R session can be displayed as follows:

> (.packages())
[1] “stats”  “graphics”  “grDevices” “utils”  “datasets”  “methods”  
[7] “base”

You can list all the available packages with the all.available=TRUE option to the packages command:

> (.packages(all.available=TRUE))
  [1] “AMR”  “base64enc”   “bit”         “bit64”       “blob”       
  [6] “brio”   “bslib”     “cachem”      “callr”       “cli”        
 [11] “commonmark”  “crayon”  “cubature”  “DBI”        “desc”       
 [16] “diffobj”  “digest”   “ellipsis”  “evaluate”    “fansi”      
 [21] “fastmap” “fontawesome” “fs”      “glue”        “highr”      
 [26] “htmltools” “httpuv” “IRdisplay” “IRkernel” “jquerylib”  
 [31] “jsonlite”  “knitr”  “kyotil”   “later”     “lifecycle”  
 [36] “magrittr”   “memoise”    “mime”  “mvtnorm”    “pbdZMQ”     
 [41] “pillar”   “pkgconfig”   “pkgload”   “plogr”    “praise”     
 [46] “processx”   “promises”   “ps”   “R6”     “rappdirs”   
 [51] “Rcpp”  “rematch2”  “repr”   “rjson”       “rlang”      
 [56] “rmarkdown” “rprojroot”  “RSQLite”  “rstudioapi”  “RUnit”      
 [61] “sass”  “shiny”  “sourcetools” “stringi”     “stringr”    
 [66] “testthat” “tibble”  “tinytest”    “tinytex”     “utf8”       
 [71] “uuid”  “vctrs”     “waldo”       “withr”       “xfun”       
 [76] “xtable”   “yaml”    “base”     “boot”        “class”      
 [81] “cluster” “codetools”  “compiler” “datasets”  “foreign”    
 [86] “graphics” “grDevices”  “grid”  “KernSmooth”  “lattice”    
 [91] “MASS”  “Matrix”    “methods”   “mgcv”  “nlme”       
 [96] “nnet”  “parallel”  “rpart”    “spatial”     “splines”    
[101] “stats”   “stats4”  “survival”   “tcltk”    “tools”      
[106] “utils”

The library() function will open a new window showing a list of available packages along with a one-line description of the package, as illustrated below:

> library()
Packages in library ‘/home/guest/R/x86_64-pc-linux-gnu-library/4.1’:
AMR                     Antimicrobial Resistance Data Analysis
base64enc               Tools for base64 encoding
bit                     Classes and Methods for Fast Memory-Efficient
                        Boolean Selections
bit64                   A S3 Class for Vectors of 64bit Integers
blob                    A Simple S3 Class for Representing Vectors of
                        Binary Data (‘BLOBS’)
brio                    Basic R Input Output
bslib                   Custom ‘Bootstrap’ ‘Sass’ Themes for ‘shiny’
                        and ‘rmarkdown’
cachem                  Cache R Objects with Automatic Pruning
callr                   Call R from R
cli                     Helpers for Developing Command Line Interfaces
commonmark              High Performance CommonMark and Github Markdown
                        Rendering in R
crayon                  Colored Terminal Output
cubature                Adaptive Multivariate Integration over
                        Hypercubes
DBI                     R Database Interface
desc                    Manipulate DESCRIPTION Files
diffobj                 Diffs for R Objects
digest                  Create Compact Hash Digests of R Objects
ellipsis                Tools for Working with ...
evaluate                Parsing and Evaluation Tools that Provide More
                        Details than the Default
fansi                   ANSI Control Sequence Aware String Functions
fastmap                 Fast Data Structures
fontawesome             Easily Work with ‘Font Awesome’ Icons
fs                      Cross-Platform File System Operations Based on
                        ‘libuv’
...

You can install multiple packages with the install.packages function passing it a vector of package names. For example, the ‘abc’ package provides tools for approximate Bayesian computation (ABC), and the ‘abtest’ tool implements Bayesian A/B testing. You can install both using the following command:

> install.packages(c(“abc”, “abtest”))

You can now verify that the installed packages are listed from the available.packages function, as shown below:

> (.packages(all.available=TRUE))
  [1] “abc”    “abc.data”   “abtest”   “AMR”       “base64enc”   
  [6] “bit”    “bit64”    “blob”      “brio”         “bslib”       
 [11] “cachem”  “callr”   “cli”      “commonmark”   “crayon”      
 [16] “cubature”  “DBI”   “desc”    “diffobj”      “digest”      
 [21] “doParallel”   “ellipsis”     “evaluate”     “fansi”        “fastmap”     
 ...

Remove
You can remove a package using the remove.package function. For example:

> remove.packages(c(“abc”,”abc.data”, “abtest”),”/home/guest/R/x86_64-pc-linux-gnu-library/4.1”)

The second argument specifies the path where the packages are installed by default. If you install the packages in a different directory, you can set it to the Library variable, and use it as the second argument to remove.packages(). We can again verify that the packages have been removed:

> (.packages(all.available=TRUE))
  [1] “AMR”    “base64enc”   “bit”      “bit64”        “blob”        
  [6] “brio”   “bslib”     “cachem”       “callr”        “cli”         
 [11] “commonmark”   “crayon”  “cubature”  “DBI”        “desc”        
 [16] “diffobj”  “digest”  “doParallel”  “ellipsis” “evaluate”    
 [21] “fansi”   “fastmap”   “fontawesome”  “foreach”      “fs”
 ...

Update
The old.packages function returns a list of packages that have a newer version released in a remote R repository. For example:

> old.packages()
         Package    LibPath                                           Installed
cli      “cli”      “/home/shakthi/R/x86_64-pc-linux-gnu-library/4.1” “3.1.0”  
DBI      “DBI”      “/home/shakthi/R/x86_64-pc-linux-gnu-library/4.1” “1.1.1”  
fansi    “fansi”    “/home/shakthi/R/x86_64-pc-linux-gnu-library/4.1” “1.0.0”  
glue     “glue”     “/home/shakthi/R/x86_64-pc-linux-gnu-library/4.1” “1.4.2”  
...
         Built   ReposVer  Repository                               
cli      “4.1.2” “3.1.1”   “https://cloud.r-project.org/src/contrib”
DBI      “4.1.0” “1.1.2”   “https://cloud.r-project.org/src/contrib”
fansi    “4.1.2” “1.0.2”   “https://cloud.r-project.org/src/contrib”
glue     “4.1.0” “1.6.1”   “https://cloud.r-project.org/src/contrib”
...

The cli.3.1.0 package has been installed on the system, but there is a newer ‘3.1.1’ package available. We can update the package using the update.packages function, as follows:

> update.packages()
cli :
 Version 3.1.0 installed in /home/shakthi/R/x86_64-pc-linux-gnu-library/4.1 
 Version 3.1.1 available at https://cloud.r-project.org
Update? (Yes/no/cancel) Yes
DBI :
 Version 1.1.1 installed in /home/shakthi/R/x86_64-pc-linux-gnu-library/4.1 
 Version 1.1.2 available at https://cloud.r-project.org
Update? (Yes/no/cancel) no
...
 ** building package indices
 ** testing if installed package can be loaded from temporary location
 ** checking absolute paths in shared objects and dynamic libraries
 ** testing if installed package can be loaded from final location
 ** testing if installed package keeps a record of temporary installation path
 * DONE (cli)

The command prompts you for a confirmation before proceeding to update the package. You can choose not to update a specific package, or cancel the entire operation. In the above example, we only update the cli package to 3.1.1. The same can be verified using the packageVersion function, as follows:

> packageVersion(“cli”)
[1] ‘3.1.1’

Download
The new.packages function shows the uninstalled packages from the local system that are available in remote R repositories. For example:

> new.packages()
    [1] “A3”                               “aaSEA”                           
    [3] “AATtools”                         “aba”                             
    [5] “ABACUS”                           “abbreviate”                      
    [7] “abbyyR”                           “abc”                             
    [9] “abc.data”                         “ABC.RAP”                         
   [11] “abcADM”                           “ABCanalysis”                     
   [13] “abcdeFBA”                         “ABCoptim”                        
   [15] “ABCp2”                            “abcrf”                           
   [17] “abcrlda”                          “abctools”

You can download the R packages to a specific directory using the download.packages function.

The surveillance R package provides statistical methods for modelling and monitoring of time series data and for epidemic phenomena. Its R source code can be downloaded to a ‘/tmp’ directory, as illustrated below:

> download.packages(“surveillance”, destdir=”/tmp”)
trying URL ‘https://cloud.r-project.org/src/contrib/surveillance_1.19.1.tar.gz’
Content type ‘application/x-gzip’ length 4388559 bytes (4.2 MB)
==================================================
downloaded 4.2 MB
     [,1]           [,2]                             
[1,] “surveillance” “/tmp/surveillance_1.19.1.tar.gz”

Layout
The bitops R package implements bitwise operations on integer vectors. The bitops.1.0.7 source code contains the following files:

$ ls
ChangeLog  DESCRIPTION  INDEX  man  MD5  NAMESPACE  R  README.md  src  tests
$ ls man
bitAnd.Rd  bitFlip.Rd  bitShiftL.Rd  cksum.Rd
$ ls R
bitops.R
$ ls src/
bit-ops.c  bit-ops.h  cksum.c  init.c
$ ls tests/
consistency.R

An R source code package should contain the following files.

  • README: This documentation file contains the purpose of the project, and the steps to install, configure and use the package. For example, the README of the bitops.1.0.7 project contains the following text:
$ cat README.md

# R-bitops -- R CRAN package `bitops` -- implementing bitwise operations
## Functionality
Bitwise operations on (the 32-bit) \R integers
## Context and History
Probably the smallest [CRAN](https://CRAN.R-project.org)
[R](https://www.r-project.org) package I maintain,
the package has a long history, originating as S / S-plus extensions by
Steve Dutky.
...
  • ChangeLog: This file provides a brief history of the changes for the various commits to the project. The ChangeLog file in bitops.1.0.7 shows the recent changes on the top of the file.
$ cat ChangeLog
        
2021-04-13  Martin Maechler  <maechler@stat.math.ethz.ch>
        * From Dan Robertson (dlrobertson) via GH PR #3, Feb.2016:
        Introduce C-style  “operators”:
        “%&%”, “%|%”, “%^%”, “%<<%”, “%>>%”
2021-03-30  Martin Maechler  <maechler@stat.math.ethz.ch>
        * src/bit-ops.c (R_2_UINT_): cast even more, now via _2_UINT_()
2021-03-24  Martin Maechler  <maechler@stat.math.ethz.ch>
        * DESCRIPTION (Date, URL): cosmetic before finally releasing
...
  • INDEX: This file is optional and provides names of important objects in the package, along with their description. For example:
$ cat INDEX
bitAnd                  Bitwise And, Or and Xor operations
bitFlip                 Binary Flip (Not) Operator
bitShiftL               Bitwise Shift Operator (to the Left or Right)
cksum                   Compute Check Sum
  • MD5: This file contains the MD5 output of the source files in the R package. This is used to verify the checksum of the downloaded files using the md5sum utility.
  • NAMESPACE: This file contains directives that specify the various imports and exports of the name space for a package. The name space management specifies which variables are imported from other packages, and describes the variables that are exported to users of the package.
$ cat NAMESPACE
 ## Re-written 2012-11-03 B. D. Ripley
 useDynLib(bitops, .registration = TRUE, .fixes = “C_”)
 export(bitFlip, bitAnd, bitOr, bitXor, bitShiftL, bitShiftR, cksum)
 export(“%&%”, “%|%”, “%^%”, “%<<%”, “%>>%”)
  • man: This directory contains manual pages for the source package, and is written in the ‘R documentation’ (Rd) format.
  • R: This directory contains the actual R source files of the project.
  • src: This directory contains additional source files that are used by the package, such as .c and .h header files that interact with R’s foreign function interface (FFI).
$ ls src/
bit-ops.c  bit-ops.h  cksum.c  init.c
  • tests: This folder has the complete test suite to run and verify the R package. For example:
$ ls tests/
consistency.R
  • DESCRIPTION: This file provides the meta-information with details of the package name, version, date, author, maintainer, licence, URL, repository, published date, etc.

Build
You can build a package from the R source directory files using the R CMD build command. The bitops.1.0.7 sources can be built from the command line, as shown below:

$ R CMD build bitops
 * checking for file ‘bitops/DESCRIPTION’ ... OK
 * preparing ‘bitops’:
 * checking DESCRIPTION meta-information ... OK
 * cleaning src
 * checking whether ‘INDEX’ is up-to-date ... NO
 * use ‘--force’ to remove the existing ‘INDEX’
 * checking for LF line-endings in source and make files and shell scripts
 * checking for empty or unneeded directories
 * building ‘bitops_1.0-7.tar.gz’

You can also manually install a package from the shell command line after downloading the tarball with the R CMD INSTALL command, as shown below:

$ R CMD INSTALL bitops_1.0-7.tar.gz 
 * installing to library ‘/home/shakthi/R/x86_64-pc-linux-gnu-library/4.1’
 * installing *source* package ‘bitops’ ...
 ** package ‘bitops’ successfully unpacked and MD5 sums checked
 ** using staged installation
 ** libs
 gcc -I”/usr/include/R/” -DNDEBUG   -D_FORTIFY_SOURCE=2   -fpic  -march=x86-64 -mtune=generic -O2 -pipe -fno-plt  -c bit-ops.c -o bit-ops.o
 gcc -I”/usr/include/R/” -DNDEBUG   -D_FORTIFY_SOURCE=2   -fpic  -march=x86-64 -mtune=generic -O2 -pipe -fno-plt  -c cksum.c -o cksum.o
 gcc -I”/usr/include/R/” -DNDEBUG   -D_FORTIFY_SOURCE=2   -fpic  -march=x86-64 -mtune=generic -O2 -pipe -fno-plt  -c init.c -o init.o
 gcc -shared -L/usr/lib64/R/lib -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now -o bitops.so bit-ops.o cksum.o init.o -L/usr/lib64/R/lib -lR
 installing to /home/shakthi/R/x86_64-pc-linux-gnu-library/4.1/00LOCK-bitops/00new/bitops/libs
 ** R
 ** byte-compile and prepare package for lazy loading
 ** help
 *** installing help indices
 ** building package indices
 ** testing if installed package can be loaded from temporary location
 ** checking absolute paths in shared objects and dynamic libraries
 ** testing if installed package can be loaded from final location
 ** testing if installed package keeps a record of temporary installation path
 * DONE (bitops)

You can verify the same using the packageVersion command in the R console:

> packageVersion(“bitops”)
[1] ‘1.0.7’

The devtools library provides various functions that allow you to install R packages from Git repositories and URLs. This is useful if you would like to test the latest main development branch of an R package. You will need to first load the devtools library in the R console session:

> install.packages(“devtools”)
 Installing package into ‘/home/shakthi/R/x86_64-pc-linux-gnu-library/4.1’
 (as ‘lib’ is unspecified)
 also installing the dependencies ‘gert’, ‘usethis’
 trying URL ‘https://cloud.r-project.org/src/contrib/gert_1.5.0.tar.gz’
 Content type ‘application/x-gzip’ length 66958 bytes (65 KB)
 ...
 ** testing if installed package keeps a record of temporary installation path
 * DONE (devtools)
> library(devtools)
Loading required package: usethis

You can now use the install_github function with a GitHub ‘username/project-name’ to install the R sources from the main branch, as shown below:

> install_github(“hadley/plyr”)
Downloading GitHub repo hadley/plyr@HEAD
...
─  preparing ‘plyr’:
  checking DESCRIPTION meta-information ...
─  cleaning src
─  checking for LF line-endings in source and make files and shell scripts
─  checking for empty or unneeded directories
─  building ‘plyr_1.8.6.9000.tar.gz’
 ** checking absolute paths in shared objects and dynamic libraries
 ** testing if installed package can be loaded from final location
 ** testing if installed package keeps a record of temporary installation path
 * DONE (plyr)

R also provides the package.skeleton function to build your own package from a directory containing R source files. This function accepts the following arguments:

Argument Purpose
name Package name
list A character vector of named R objects
environment The environment (default .GlobalEnv) to evaluate list
path A character vector (default ‘.’) containing path in the file system
force A Boolean value to overwrite files if directory already exists
namespace A Boolean value to include a namespace
code_files The character vector that mentions the R source files


Repositories

The R packages are available on the Internet in three major repositories:

1.  Comprehensive R Archive Network (CRAN): This provides source code as well as pre-compiled binary distributions for the R base system and packages. The latest R release is 2021-11-01 (Bird Hippie) R-4.1.2.tar.gz as of writing this article. It has over 18,928 packages, and you can view the available packages by name or date of publication.

2.  Bioconductor: This project provides Free/Libre and Open Source R software packages for powerful statistical and graphical methods to analyse genomic data. These packages are also made available in CRAN, in addition to their own R packages. Their software is released under the Artistic License 2.0.

3.  R-Forge: This provides a platform for the development of R packages and hosts 2145 R related projects. It is based on FusionForge, and uses Subversion for source control management. It has support for mailing lists, forums, bug tracking, Web based administration and backups.

The remote repositories available on your system can be obtained using the following options function:

> options(‘repos’)
$repos
                         CRAN 
“https://cloud.r-project.org”

You can add additional remote R repositories using the setRepositories function.

LEAVE A REPLY

Please enter your comment!
Please enter your name here