Implementing custom iSEEindex resources

iSEEindex resources

Overview

iSEEindex imports data sets and initial app configurations from files. Each of those files is represented by a Uniform Resource Identifier (URI) in the lists of metadata returned by the functions supplied to the FUN.datasets and FUN.initial arguments of iSEEindex().

iSEEindex requires each URI to contain a scheme component (Wikipedia ), to identify the type of resource and invoke the associated method for accessing it.

This system allows iSEEindex users to use both standard and custom schemes in the URI of their resources, to fetch files from virtually any logical or physical resource, local or remote.

In this vignette, we describe the implementation of iSEEindex resources, using built-in classes of resources as examples.

Implementation

Given a scheme <scheme>, iSEEindex automatically attempts to create an object of class iSEEindex<Scheme>Resource that contains the class iSEEindexResource. For instance, the scheme https produces an object of class iSEEindexHttpsResource.

iSEEindex provides a range of built-in iSEEindexResource sub-classes, described in dedicated sections below.

The raw value of the URI (including the scheme component) is always stored in the uri slot of the iSEEindexResource object.

Each iSEEindexResource sub-class must define the method precache().

On first use, precache() processes the raw value of the URI, downloads the resource file locally using custom code if necessary, caches the file using BiocFileCache, and returns the path to the cached file.

In subsequent uses, BiocFileCache is used to fetch the cached file directly.

Built-in resources

iSEEindexHttpsResource

This type of resource is documented in help("iSEEindexHttpsResource-class").

Structure

Briefly, this class is used to represent files that are publicly accessible online over HTTPS.

The URI must use the standard scheme “https”, followed by the URI to the file on the internet.

Example:

https://zenodo.org/record/7304331/files/ReprocessedAllenData.rds?download=1

Caching

The BiocFileCache package can handle HTTPS perfectly well.

In this instance, the precache() function has no other job than to cache the file located at the given URI using BiocFileCache.

iSEEindexLocalhostResource

Structure

This type of resource is documented in help("iSEEindexLocalhostResource-class").

Briefly, this class is used to represent files that are already present on the filesystem of the machine that runs the application.

The URI must use the custom scheme “localhost”, followed by the path – absolute or relative – to the file on disk.

Example:

localhost:///absolute/path/to/file
localhost://relative/path/to/file

Caching

Now, while the BiocFileCache package can perfectly well handle local files, it does not know how to deal with the custom scheme localhost.

In this instance, the precache() function has for only job to remove the localhost:// prefix from the URI, and cache the file located at the resulting file path using BiocFileCache.

iSEEindexRcallResource

Structure

This type of resource is documented in help("iSEEindexRcallResource-class").

Briefly, this class is used to represent files whose local file path is obtained as the result of executing R code.

The URI must use the custom scheme “rcall”, followed by the R code to execute.

This custom scheme was created mainly to dynamically fetch the example files distributed and installed with the package.

Example:

rcall://system.file(package='iSEEindex','ReprocessedAllenData_config_01.R')

Caching

The custom scheme rcall is entirely made up for the purpose described here; it is not in any way recognised as a standard scheme by the Internet Assigned Numbers Authority (IANA). As such, the BiocFileCache package cannot possibly know how to handle that custom scheme.

In this instance, the precache() function has the job to remove the rcall:// prefix from the URI, evaluate the remainder of the URI as R code, and cache the file located at the resulting file path using BiocFileCache.

iSEEindexS3Resource

Structure

This type of resource is documented in help("iSEEindexS3Resource-class").

Briefly, this class is used to represent files that are accessible from Amazon S3.

The URI must use the custom scheme “s3”, followed by the S3 URI to the file.

Example:

s3://bucket/prefix/file

Caching

Now, while the scheme s3 is recognised by the AWS Command Line Interface, the BiocFileCache package does not know how to deal with it.

In this instance, the precache() function has the job to parse the URI for information that is passed to the paws.storage package to download the file, which is then cached using BiocFileCache.

iSEEindexRunrResource

Structure

This type of resource is documented in help("iSEEindexRunrResource-class").

This class is used to represent directly objects that are generated via a call to arbitrary R code.

The URI must use the custom scheme “runr”, followed by the code itself to be run to obtain the object to explore.

Example:

runr://function_to_call(param1 = "value1", param2 = "value2")

Caching

As this class does not directly specify a path, but rather focus on the object itself, the classical BiocFileCache-based caching will not work automatically.

Nonetheless, since a typical use case would be to host a collection of datasets provided in a data package, chances are that these packages implement some form of BiocFileCache-enabled caching.

Reproducibility

The iSEEindex package (Rue-Albrecht and Marini, 2024) was made possible thanks to:

R (R Core Team, 2024)
BiocStyle (Oleś, 2024)
knitr (Xie, 2024)
RefManageR (McLean, 2017)
rmarkdown (Allaire, Xie, Dervieux, McPherson, Luraschi, Ushey, Atkins, Wickham, Cheng, Chang, and Iannone, 2024)
sessioninfo (Wickham, Chang, Flight, Müller, and Hester, 2021)
testthat (Wickham, 2011)

This package was developed using biocthis.

Code for creating the vignette

## Create the vignette
library("rmarkdown")
system.time(render("resources.Rmd", "BiocStyle::html_document"))

## Extract the R code
library("knitr")
knit("resources.Rmd", tangle = TRUE)

Date the vignette was generated.

#> [1] "2024-10-18 10:44:49 UTC"

Wallclock time spent generating the vignette.

#> Time difference of 0.584 secs

R session information.

#> ─ Session info ───────────────────────────────────────────────────────────────────────────────────
#>  setting  value
#>  version  R version 4.4.1 (2024-06-14)
#>  os       Ubuntu 22.04.5 LTS
#>  system   x86_64, linux-gnu
#>  ui       X11
#>  language en
#>  collate  en_US.UTF-8
#>  ctype    en_US.UTF-8
#>  tz       UTC
#>  date     2024-10-18
#>  pandoc   3.4 @ /usr/bin/ (via rmarkdown)
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────
#>  package     * version date (UTC) lib source
#>  backports     1.5.0   2024-05-23 [1] RSPM (R 4.4.0)
#>  bibtex        0.5.1   2023-01-26 [1] RSPM (R 4.4.0)
#>  BiocManager   1.30.25 2024-08-28 [2] CRAN (R 4.4.1)
#>  BiocStyle   * 2.33.1  2024-06-12 [1] Bioconductor 3.20 (R 4.4.0)
#>  bookdown      0.41    2024-10-16 [1] RSPM (R 4.4.0)
#>  bslib         0.8.0   2024-07-29 [2] RSPM (R 4.4.0)
#>  cachem        1.1.0   2024-05-16 [2] RSPM (R 4.4.0)
#>  cli           3.6.3   2024-06-21 [2] RSPM (R 4.4.0)
#>  desc          1.4.3   2023-12-10 [2] RSPM (R 4.4.0)
#>  digest        0.6.37  2024-08-19 [2] RSPM (R 4.4.0)
#>  evaluate      1.0.1   2024-10-10 [2] RSPM (R 4.4.0)
#>  fastmap       1.2.0   2024-05-15 [2] RSPM (R 4.4.0)
#>  fontawesome   0.5.2   2023-08-19 [2] RSPM (R 4.4.0)
#>  fs            1.6.4   2024-04-25 [2] RSPM (R 4.4.0)
#>  generics      0.1.3   2022-07-05 [1] RSPM (R 4.4.0)
#>  glue          1.8.0   2024-09-30 [2] RSPM (R 4.4.0)
#>  htmltools     0.5.8.1 2024-04-04 [2] RSPM (R 4.4.0)
#>  htmlwidgets   1.6.4   2023-12-06 [2] RSPM (R 4.4.0)
#>  httr          1.4.7   2023-08-15 [1] RSPM (R 4.4.0)
#>  jquerylib     0.1.4   2021-04-26 [2] RSPM (R 4.4.0)
#>  jsonlite      1.8.9   2024-09-20 [2] RSPM (R 4.4.0)
#>  knitr         1.48    2024-07-07 [2] RSPM (R 4.4.0)
#>  lifecycle     1.0.4   2023-11-07 [2] RSPM (R 4.4.0)
#>  lubridate     1.9.3   2023-09-27 [1] RSPM (R 4.4.0)
#>  magrittr      2.0.3   2022-03-30 [2] RSPM (R 4.4.0)
#>  pkgdown       2.1.1   2024-09-17 [2] RSPM (R 4.4.0)
#>  plyr          1.8.9   2023-10-02 [1] RSPM (R 4.4.0)
#>  R6            2.5.1   2021-08-19 [2] RSPM (R 4.4.0)
#>  ragg          1.3.3   2024-09-11 [2] RSPM (R 4.4.0)
#>  Rcpp          1.0.13  2024-07-17 [2] RSPM (R 4.4.0)
#>  RefManageR  * 1.4.0   2022-09-30 [1] RSPM (R 4.4.0)
#>  rlang         1.1.4   2024-06-04 [2] RSPM (R 4.4.0)
#>  rmarkdown     2.28    2024-08-17 [2] RSPM (R 4.4.0)
#>  sass          0.4.9   2024-03-15 [2] RSPM (R 4.4.0)
#>  sessioninfo * 1.2.2   2021-12-06 [2] RSPM (R 4.4.0)
#>  stringi       1.8.4   2024-05-06 [2] RSPM (R 4.4.0)
#>  stringr       1.5.1   2023-11-14 [2] RSPM (R 4.4.0)
#>  systemfonts   1.1.0   2024-05-15 [2] RSPM (R 4.4.0)
#>  textshaping   0.4.0   2024-05-24 [2] RSPM (R 4.4.0)
#>  timechange    0.3.0   2024-01-18 [1] RSPM (R 4.4.0)
#>  xfun          0.48    2024-10-03 [2] RSPM (R 4.4.0)
#>  xml2          1.3.6   2023-12-04 [2] RSPM (R 4.4.0)
#>  yaml          2.3.10  2024-07-26 [2] RSPM (R 4.4.0)
#> 
#>  [1] /__w/_temp/Library
#>  [2] /usr/local/lib/R/site-library
#>  [3] /usr/local/lib/R/library
#> 
#> ──────────────────────────────────────────────────────────────────────────────────────────────────

Bibliography

This vignette was generated using BiocStyle (Oleś, 2024) with knitr (Xie, 2024) and rmarkdown (Allaire, Xie, Dervieux et al., 2024) running behind the scenes.

Citations made with RefManageR (McLean, 2017).

[1] J. Allaire, Y. Xie, C. Dervieux, et al. rmarkdown: Dynamic Documents for R. R package version 2.28. 2024. URL: https://github.com/rstudio/rmarkdown.

[2] M. W. McLean. “RefManageR: Import and Manage BibTeX and BibLaTeX References in R”. In: The Journal of Open Source Software (2017). DOI: 10.21105/joss.00338.

[3] A. Oleś. BiocStyle: Standard styles for vignettes and other Bioconductor documents. R package version 2.33.1. 2024. DOI: 10.18129/B9.bioc.BiocStyle. URL: https://bioconductor.org/packages/BiocStyle.

[4] R Core Team. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing. Vienna, Austria, 2024. URL: https://www.R-project.org/.

[5] K. Rue-Albrecht and F. Marini. iSEEindex: iSEE extension for a landing page to a custom collection of data sets. R package version 1.3.3. 2024. URL: https://github.com/iSEE/iSEEindex.

[6] H. Wickham. “testthat: Get Started with Testing”. In: The R Journal 3 (2011), pp. 5–10. URL: https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf.

[7] H. Wickham, W. Chang, R. Flight, et al. sessioninfo: R Session Information. R package version 1.2.2, https://r-lib.github.io/sessioninfo/. 2021. URL: https://github.com/r-lib/sessioninfo#readme.

[8] Y. Xie. knitr: A General-Purpose Package for Dynamic Report Generation in R. R package version 1.48. 2024. URL: https://yihui.org/knitr/.

Kevin Rue-Albrecht

18 October 2024

iSEEindex resources

Overview

Implementation

Built-in resources

iSEEindexHttpsResource

Structure

Caching

iSEEindexLocalhostResource

Structure

Caching

iSEEindexRcallResource

Structure

Caching

iSEEindexS3Resource

Structure

Caching

iSEEindexRunrResource

Structure

Caching

Reproducibility

Bibliography