Skip to contents

Contributing to iSEEhub

Kevin Rue-Albrecht

University of Oxford

18 October 2024

Source: vignettes/contributing.Rmd
contributing.Rmd

Initial app configurations

Overview

Initial app configurations configure the set of panels and their respective initial state when the main iSEE app is launched.

Initial app configurations are implemented as R scripts that are stored in the inst/initial subdirectory of the iSEEhub package. Within that directory, the app expects a subdirectory named exactly as the EH identifier of each dataset for which additional configurations are made available. Within each dataset-specific directory, the app expects any number of R scripts, each script defining one configuration.

Contributions to initial app configurations are welcome to the iSEEhub as pull requests, both as new configurations and edits to existing configurations.

Requirements

An initial configuration script must define at least one object called initial, that contains a list of instances of panel classes defined in the iSEE package – so-called built-in panels – and other packages that extend iSEE functionality. That is, packages like iSEEu and iSEEhex.

Other objects created by configuration scripts are ignored. We encourage users to refrain from creating any other object than initial, to avoid any unexpected behaviour in the app.

Example

For demonstration, the package includes two configurations for the dataset EH1.

The scripts that define those configurations are stored within the directory inst/initial/EH1. Within that directory, the files are named config_1.R and config_error.R.

The script config_1.R defines an initial app state that contains only one panel, namely a ComplexHeatmapPlot, that is configured to span half the width of the app (6 out of 12 units in shiny units), and displays the metadata gender and status as color bars next to the heat map.

## EH1/config_1.R
library(iSEE)

initial <- list(
    ComplexHeatmapPlot(
        PanelWidth = 6L,
        ColumnData = c("gender", "tumor_status")
    )
)

Conversely, the script config_error.R provides a brutal example of an invalid script that throws an error. This script is only included in the package to test and demonstrate that the app fails elegantly when an invalid configuration is supplied (which should never happen in the first place).

## EH1/config_error.R
# This script demonstrates how the app handles a bad configuration.

stop("Bad config script!")

Process for contributing

  • Fork the GitHub repository for iSEEhub.
  • Create and/or edit appropriate files and directories within the inst/initial directory.
  • Test your new configuration(s) locally; install the updated iSEEhub package, launch the app, and load dataset(s) using the new configuration(s).
  • Open a pull request on the GitHub repository iSEEhub.
  • Wait for maintainers to review and approve the pull request.

Reproducibility

The iSEEhub package (Rue-Albrecht, 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("iSEEhub.Rmd", "BiocStyle::html_document"))

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

Date the vignette was generated.

#> [1] "2024-10-18 12:10:47 UTC"

Wallclock time spent generating the vignette.

#> Time difference of 0.56 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)
#>  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. iSEEhub: iSEE for the Bioconductor ExperimentHub. R package version 1.7.1. 2024. URL: https://github.com/iSEE/iSEEhub.

[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/.