# Implementing custom iSEEindex resources

Kevin Rue-Albrecht1*

1University of Oxford

*kevin.rue-albrecht@imm.ox.ac.uk

#### 1 May 2024

#### Package

iSEEindex 1.2.0

# 1 iSEEindex resources

## 1.1 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.

## 1.2 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.

# 2 Built-in resources

## 2.1 iSEEindexHttpsResource

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

### 2.1.1 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

### 2.1.2 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.

## 2.2 iSEEindexLocalhostResource

### 2.2.1 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

### 2.2.2 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.

## 2.3 iSEEindexRcallResource

### 2.3.1 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')

### 2.3.2 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.

## 2.4 iSEEindexS3Resource

### 2.4.1 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

### 2.4.2 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.

# 3 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 et al., 2024)
- sessioninfo (Wickham, Chang, Flight et al., 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-05-01 19:38:19 EDT"

Wallclock time spent generating the vignette.

    #> Time difference of 0.581 secs

`R` session information.

    #> ─ Session info ───────────────────────────────────────────────────────────────────────────────────
    #>  setting  value
    #>  version  R version 4.4.0 beta (2024-04-15 r86425 ucrt)
    #>  os       Windows Server 2022 x64 (build 20348)
    #>  system   x86_64, mingw32
    #>  ui       RTerm
    #>  language (EN)
    #>  collate  C
    #>  ctype    English_United States.utf8
    #>  tz       America/New_York
    #>  date     2024-05-01
    #>  pandoc   2.7.3 @ C:/PROGRA~1/Pandoc/ (via rmarkdown)
    #>
    #> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────
    #>  package              * version date (UTC) lib source
    #>  abind                  1.4-5   2016-07-21 [2] CRAN (R 4.4.0)
    #>  backports              1.4.1   2021-12-13 [2] CRAN (R 4.4.0)
    #>  bibtex                 0.5.1   2023-01-26 [2] CRAN (R 4.4.0)
    #>  Biobase              * 2.64.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  BiocFileCache        * 2.12.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  BiocGenerics         * 0.50.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  BiocManager            1.30.22 2023-08-08 [2] CRAN (R 4.4.0)
    #>  BiocStyle            * 2.32.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  bit                    4.0.5   2022-11-15 [2] CRAN (R 4.4.0)
    #>  bit64                  4.0.5   2020-08-30 [2] CRAN (R 4.4.0)
    #>  blob                   1.2.4   2023-03-17 [2] CRAN (R 4.4.0)
    #>  bookdown               0.39    2024-04-15 [2] CRAN (R 4.4.0)
    #>  bslib                  0.7.0   2024-03-29 [2] CRAN (R 4.4.0)
    #>  cachem                 1.0.8   2023-05-01 [2] CRAN (R 4.4.0)
    #>  circlize               0.4.16  2024-02-20 [2] CRAN (R 4.4.0)
    #>  cli                    3.6.2   2023-12-11 [2] CRAN (R 4.4.0)
    #>  clue                   0.3-65  2023-09-23 [2] CRAN (R 4.4.0)
    #>  cluster                2.1.6   2023-12-01 [2] CRAN (R 4.4.0)
    #>  codetools              0.2-20  2024-03-31 [2] CRAN (R 4.4.0)
    #>  colorspace             2.1-0   2023-01-23 [2] CRAN (R 4.4.0)
    #>  colourpicker           1.3.0   2023-08-21 [2] CRAN (R 4.4.0)
    #>  ComplexHeatmap         2.20.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  crayon                 1.5.2   2022-09-29 [2] CRAN (R 4.4.0)
    #>  curl                   5.2.1   2024-03-01 [2] CRAN (R 4.4.0)
    #>  DBI                    1.2.2   2024-02-16 [2] CRAN (R 4.4.0)
    #>  dbplyr               * 2.5.0   2024-03-19 [2] CRAN (R 4.4.0)
    #>  DelayedArray           0.30.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  digest                 0.6.35  2024-03-11 [2] CRAN (R 4.4.0)
    #>  doParallel             1.0.17  2022-02-07 [2] CRAN (R 4.4.0)
    #>  dplyr                  1.1.4   2023-11-17 [2] CRAN (R 4.4.0)
    #>  DT                     0.33    2024-04-04 [2] CRAN (R 4.4.0)
    #>  evaluate               0.23    2023-11-01 [2] CRAN (R 4.4.0)
    #>  fansi                  1.0.6   2023-12-08 [2] CRAN (R 4.4.0)
    #>  fastmap                1.1.1   2023-02-24 [2] CRAN (R 4.4.0)
    #>  filelock               1.0.3   2023-12-11 [2] CRAN (R 4.4.0)
    #>  fontawesome            0.5.2   2023-08-19 [2] CRAN (R 4.4.0)
    #>  foreach                1.5.2   2022-02-02 [2] CRAN (R 4.4.0)
    #>  generics               0.1.3   2022-07-05 [2] CRAN (R 4.4.0)
    #>  GenomeInfoDb         * 1.40.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  GenomeInfoDbData       1.2.12  2024-04-16 [2] Bioconductor
    #>  GenomicRanges        * 1.56.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  GetoptLong             1.0.5   2020-12-15 [2] CRAN (R 4.4.0)
    #>  ggplot2                3.5.1   2024-04-23 [2] CRAN (R 4.4.0)
    #>  ggrepel                0.9.5   2024-01-10 [2] CRAN (R 4.4.0)
    #>  GlobalOptions          0.1.2   2020-06-10 [2] CRAN (R 4.4.0)
    #>  glue                   1.7.0   2024-01-09 [2] CRAN (R 4.4.0)
    #>  gtable                 0.3.5   2024-04-22 [2] CRAN (R 4.4.0)
    #>  highr                  0.10    2022-12-22 [2] CRAN (R 4.4.0)
    #>  htmltools              0.5.8.1 2024-04-04 [2] CRAN (R 4.4.0)
    #>  htmlwidgets            1.6.4   2023-12-06 [2] CRAN (R 4.4.0)
    #>  httpuv                 1.6.15  2024-03-26 [2] CRAN (R 4.4.0)
    #>  httr                   1.4.7   2023-08-15 [2] CRAN (R 4.4.0)
    #>  igraph                 2.0.3   2024-03-13 [2] CRAN (R 4.4.0)
    #>  IRanges              * 2.38.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  iSEE                   2.16.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  iSEEindex            * 1.2.0   2024-05-01 [1] Bioconductor 3.19 (R 4.4.0)
    #>  iterators              1.0.14  2022-02-05 [2] CRAN (R 4.4.0)
    #>  jquerylib              0.1.4   2021-04-26 [2] CRAN (R 4.4.0)
    #>  jsonlite               1.8.8   2023-12-04 [2] CRAN (R 4.4.0)
    #>  knitr                  1.46    2024-04-06 [2] CRAN (R 4.4.0)
    #>  later                  1.3.2   2023-12-06 [2] CRAN (R 4.4.0)
    #>  lattice                0.22-6  2024-03-20 [2] CRAN (R 4.4.0)
    #>  lifecycle              1.0.4   2023-11-07 [2] CRAN (R 4.4.0)
    #>  listviewer             4.0.0   2023-09-30 [2] CRAN (R 4.4.0)
    #>  lubridate              1.9.3   2023-09-27 [2] CRAN (R 4.4.0)
    #>  magrittr               2.0.3   2022-03-30 [2] CRAN (R 4.4.0)
    #>  Matrix                 1.7-0   2024-03-22 [2] CRAN (R 4.4.0)
    #>  MatrixGenerics       * 1.16.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  matrixStats          * 1.3.0   2024-04-11 [2] CRAN (R 4.4.0)
    #>  memoise                2.0.1   2021-11-26 [2] CRAN (R 4.4.0)
    #>  mgcv                   1.9-1   2023-12-21 [2] CRAN (R 4.4.0)
    #>  mime                   0.12    2021-09-28 [2] CRAN (R 4.4.0)
    #>  miniUI                 0.1.1.1 2018-05-18 [2] CRAN (R 4.4.0)
    #>  munsell                0.5.1   2024-04-01 [2] CRAN (R 4.4.0)
    #>  nlme                   3.1-164 2023-11-27 [2] CRAN (R 4.4.0)
    #>  paws.common            0.7.2   2024-04-09 [2] CRAN (R 4.4.0)
    #>  paws.storage           0.5.0   2024-01-09 [2] CRAN (R 4.4.0)
    #>  pillar                 1.9.0   2023-03-22 [2] CRAN (R 4.4.0)
    #>  pkgconfig              2.0.3   2019-09-22 [2] CRAN (R 4.4.0)
    #>  plyr                   1.8.9   2023-10-02 [2] CRAN (R 4.4.0)
    #>  png                    0.1-8   2022-11-29 [2] CRAN (R 4.4.0)
    #>  promises               1.3.0   2024-04-05 [2] CRAN (R 4.4.0)
    #>  purrr                  1.0.2   2023-08-10 [2] CRAN (R 4.4.0)
    #>  R6                     2.5.1   2021-08-19 [2] CRAN (R 4.4.0)
    #>  RColorBrewer           1.1-3   2022-04-03 [2] CRAN (R 4.4.0)
    #>  Rcpp                   1.0.12  2024-01-09 [2] CRAN (R 4.4.0)
    #>  RefManageR           * 1.4.0   2022-09-30 [2] CRAN (R 4.4.0)
    #>  rintrojs               0.3.4   2024-01-11 [2] CRAN (R 4.4.0)
    #>  rjson                  0.2.21  2022-01-09 [2] CRAN (R 4.4.0)
    #>  rlang                  1.1.3   2024-01-10 [2] CRAN (R 4.4.0)
    #>  rmarkdown              2.26    2024-03-05 [2] CRAN (R 4.4.0)
    #>  RSQLite                2.3.6   2024-03-31 [2] CRAN (R 4.4.0)
    #>  S4Arrays               1.4.0   2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  S4Vectors            * 0.42.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  sass                   0.4.9   2024-03-15 [2] CRAN (R 4.4.0)
    #>  scales                 1.3.0   2023-11-28 [2] CRAN (R 4.4.0)
    #>  sessioninfo          * 1.2.2   2021-12-06 [2] CRAN (R 4.4.0)
    #>  shape                  1.4.6.1 2024-02-23 [2] CRAN (R 4.4.0)
    #>  shiny                * 1.8.1.1 2024-04-02 [2] CRAN (R 4.4.0)
    #>  shinyAce               0.4.2   2022-05-06 [2] CRAN (R 4.4.0)
    #>  shinydashboard         0.7.2   2021-09-30 [2] CRAN (R 4.4.0)
    #>  shinyjs                2.1.0   2021-12-23 [2] CRAN (R 4.4.0)
    #>  shinyWidgets           0.8.6   2024-04-24 [2] CRAN (R 4.4.0)
    #>  SingleCellExperiment * 1.26.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  SparseArray            1.4.0   2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  stringi                1.8.3   2023-12-11 [2] CRAN (R 4.4.0)
    #>  stringr                1.5.1   2023-11-14 [2] CRAN (R 4.4.0)
    #>  SummarizedExperiment * 1.34.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  tibble                 3.2.1   2023-03-20 [2] CRAN (R 4.4.0)
    #>  tidyselect             1.2.1   2024-03-11 [2] CRAN (R 4.4.0)
    #>  timechange             0.3.0   2024-01-18 [2] CRAN (R 4.4.0)
    #>  triebeard              0.4.1   2023-03-04 [2] CRAN (R 4.4.0)
    #>  UCSC.utils             1.0.0   2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  urltools               1.7.3   2019-04-14 [2] CRAN (R 4.4.0)
    #>  utf8                   1.2.4   2023-10-22 [2] CRAN (R 4.4.0)
    #>  vctrs                  0.6.5   2023-12-01 [2] CRAN (R 4.4.0)
    #>  vipor                  0.4.7   2023-12-18 [2] CRAN (R 4.4.0)
    #>  viridisLite            0.4.2   2023-05-02 [2] CRAN (R 4.4.0)
    #>  xfun                   0.43    2024-03-25 [2] CRAN (R 4.4.0)
    #>  xml2                   1.3.6   2023-12-04 [2] CRAN (R 4.4.0)
    #>  xtable                 1.8-4   2019-04-21 [2] CRAN (R 4.4.0)
    #>  XVector                0.44.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>  yaml                   2.3.8   2023-12-11 [2] CRAN (R 4.4.0)
    #>  zlibbioc               1.50.0  2024-05-01 [2] Bioconductor 3.19 (R 4.4.0)
    #>
    #>  [1] F:/biocbuild/bbs-3.19-bioc/tmpdir/Rtmpc7QPOQ/Rinst452c2d6d4728
    #>  [2] F:/biocbuild/bbs-3.19-bioc/R/library
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────────────

# 4 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.26. 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.32.0. 2024. URL: https://github.com/Bioconductor/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.2.0. 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. 2021. URL: https://CRAN.R-project.org/package=sessioninfo.

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