# Contributing to iSEEhub

# 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, 2025) was made possible thanks to:

- R (R Core Team, 2025)
- BiocStyle (Oleś, 2025)
- knitr (Xie, 2025)
- RefManageR (McLean, 2017)
- rmarkdown (Allaire, Xie, Dervieux, McPherson, Luraschi, Ushey, Atkins, Wickham, Cheng, Chang, and Iannone, 2025)
- sessioninfo (Wickham, Chang, Flight, Müller, and Hester, 2025)
- 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] "2025-11-15 07:32:00 UTC"

Wallclock time spent generating the vignette.

    #> Time difference of 0.424 secs

R session information.

    #> ─ Session info ───────────────────────────────────────────────────────────────────────────────────────────────────────
    #>  setting  value
    #>  version  R version 4.5.2 (2025-10-31)
    #>  os       Ubuntu 24.04.3 LTS
    #>  system   x86_64, linux-gnu
    #>  ui       X11
    #>  language (EN)
    #>  collate  C
    #>  ctype    en_US.UTF-8
    #>  tz       Etc/UTC
    #>  date     2025-11-15
    #>  pandoc   3.6.3 @ /usr/local/bin/ (via rmarkdown)
    #>  quarto   1.8.24 @ /usr/local/bin/quarto
    #>
    #> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────────────────────────
    #>  package     * version date (UTC) lib source
    #>  backports     1.5.0   2024-05-23 [2] RSPM (R 4.5.0)
    #>  bibtex        0.5.1   2023-01-26 [2] RSPM (R 4.5.0)
    #>  BiocManager   1.30.27 2025-11-14 [2] https://cran.r-universe.dev (R 4.5.2)
    #>  BiocStyle   * 2.38.0  2025-10-29 [2] https://bioc-release.r-universe.dev (R 4.5.2)
    #>  bslib         0.9.0   2025-01-30 [2] RSPM (R 4.5.0)
    #>  buildtools    1.0.0   2025-11-11 [3] local (/pkg)
    #>  cachem        1.1.0   2024-05-16 [2] RSPM (R 4.5.0)
    #>  cli           3.6.5   2025-04-23 [2] RSPM (R 4.5.0)
    #>  digest        0.6.38  2025-11-12 [2] RSPM (R 4.5.0)
    #>  evaluate      1.0.5   2025-08-27 [2] RSPM (R 4.5.0)
    #>  fastmap       1.2.0   2024-05-15 [2] RSPM (R 4.5.0)
    #>  generics      0.1.4   2025-05-09 [2] RSPM (R 4.5.0)
    #>  glue          1.8.0   2024-09-30 [2] RSPM (R 4.5.0)
    #>  htmltools     0.5.8.1 2024-04-04 [2] RSPM (R 4.5.0)
    #>  httr          1.4.7   2023-08-15 [2] RSPM (R 4.5.0)
    #>  jquerylib     0.1.4   2021-04-26 [2] RSPM (R 4.5.0)
    #>  jsonlite      2.0.0   2025-03-27 [2] RSPM (R 4.5.0)
    #>  knitr         1.50    2025-03-16 [2] RSPM (R 4.5.0)
    #>  lifecycle     1.0.4   2023-11-07 [2] RSPM (R 4.5.0)
    #>  lubridate     1.9.4   2024-12-08 [2] RSPM (R 4.5.0)
    #>  magrittr      2.0.4   2025-09-12 [2] RSPM (R 4.5.0)
    #>  maketools     1.3.2   2025-01-25 [3] RSPM (R 4.5.0)
    #>  plyr          1.8.9   2023-10-02 [2] RSPM (R 4.5.0)
    #>  R6            2.6.1   2025-02-15 [2] RSPM (R 4.5.0)
    #>  Rcpp          1.1.0   2025-07-02 [2] RSPM (R 4.5.0)
    #>  RefManageR  * 1.4.0   2022-09-30 [2] RSPM (R 4.5.0)
    #>  rlang         1.1.6   2025-04-11 [2] RSPM (R 4.5.0)
    #>  rmarkdown     2.30    2025-09-28 [2] RSPM (R 4.5.0)
    #>  sass          0.4.10  2025-04-11 [2] RSPM (R 4.5.0)
    #>  sessioninfo * 1.2.3   2025-02-05 [2] RSPM (R 4.5.0)
    #>  stringi       1.8.7   2025-03-27 [2] RSPM (R 4.5.0)
    #>  stringr       1.6.0   2025-11-04 [2] RSPM (R 4.5.0)
    #>  sys           3.4.3   2024-10-04 [2] RSPM (R 4.5.0)
    #>  timechange    0.3.0   2024-01-18 [2] RSPM (R 4.5.0)
    #>  xfun          0.54    2025-10-30 [2] RSPM (R 4.5.0)
    #>  xml2          1.4.1   2025-10-27 [2] RSPM (R 4.5.0)
    #>  yaml          2.3.10  2024-07-26 [2] RSPM (R 4.5.0)
    #>
    #>  [1] /tmp/RtmpmMQX1K/Rinst1940602e3fc5
    #>  [2] /github/workspace/pkglib
    #>  [3] /usr/local/lib/R/site-library
    #>  [4] /usr/lib/R/site-library
    #>  [5] /usr/lib/R/library
    #>  * ── Packages attached to the search path.
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

# Bibliography

This vignette was generated using BiocStyle (Oleś, 2025) with knitr (Xie, 2025) and rmarkdown (Allaire, Xie, Dervieux et al., 2025) 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.30. 2025. 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.38.0. 2025. 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, 2025. URL: https://www.R-project.org/.

[5] K. Rue-Albrecht. iSEEhub: iSEE for the Bioconductor ExperimentHub. R package version 1.12.0. 2025. 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/articles/RJ-2011-002/.

[7] H. Wickham, W. Chang, R. Flight, et al. sessioninfo: R Session Information. R package version 1.2.3. 2025. 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.50. 2025. URL: https://yihui.org/knitr/.