Update main vignette (#20)

README.Rmd

@@ -65,7 +65,7 @@ if (interactive()) {
 }
 ```
 
-<img src="man/figures/landing_page.png" width="100%" />
+<img src="vignettes/screenshots/landing_page_overview.png" width="100%" />
 
 ## Citation
 

README.md

@@ -17,15 +17,15 @@ coverage](https://codecov.io/gh/kevinrue/iSEEhub/branch/main/graph/badge.svg)](h
 <!-- badges: end -->
 
 The goal of `iSEEhub` is to provide an interface to the Bioconductor
-*[ExperimentHub](https://bioconductor.org/packages/3.15/ExperimentHub)*
-directly within an *[iSEE](https://bioconductor.org/packages/3.15/iSEE)*
+*[ExperimentHub](https://bioconductor.org/packages/3.16/ExperimentHub)*
+directly within an *[iSEE](https://bioconductor.org/packages/3.16/iSEE)*
 web-application.
 
 The main functionality of this package is to define a custom landing
 page allowing users to browse the Bioconductor
-*[ExperimentHub](https://bioconductor.org/packages/3.15/ExperimentHub)*
+*[ExperimentHub](https://bioconductor.org/packages/3.16/ExperimentHub)*
 and directly load objects into an
-*[iSEE](https://bioconductor.org/packages/3.15/iSEE)* web-application.
+*[iSEE](https://bioconductor.org/packages/3.16/iSEE)* web-application.
 
 ## Installation instructions
 
@@ -54,6 +54,7 @@ This is a basic example which shows you how to solve a common problem:
 
 ``` r
 library("iSEEhub")
+#> Warning: package 'BiocGenerics' was built under R version 4.2.1
 #> Warning: package 'GenomeInfoDb' was built under R version 4.2.1
 library(ExperimentHub)
 ehub <- ExperimentHub()
@@ -65,7 +66,7 @@ if (interactive()) {
 }
 ```
 
-<img src="man/figures/landing_page.png" width="100%" />
+<img src="vignettes/screenshots/landing_page_overview.png" width="100%" />
 
 ## Citation
 
@@ -129,7 +130,7 @@ contributing to this project, you agree to abide by its terms.
     *[rcmdcheck](https://CRAN.R-project.org/package=rcmdcheck)*
     customized to use [Bioconductor’s docker
     containers](https://www.bioconductor.org/help/docker/) and
-    *[BiocCheck](https://bioconductor.org/packages/3.15/BiocCheck)*.
+    *[BiocCheck](https://bioconductor.org/packages/3.16/BiocCheck)*.
 -   Code coverage assessment is possible thanks to
     [codecov](https://codecov.io/gh) and
     *[covr](https://CRAN.R-project.org/package=covr)*.
@@ -145,7 +146,7 @@ contributing to this project, you agree to abide by its terms.
 For more details, check the `dev` directory.
 
 This package was developed using
-*[biocthis](https://bioconductor.org/packages/3.15/biocthis)*.
+*[biocthis](https://bioconductor.org/packages/3.16/biocthis)*.
 
 ## Code of Conduct
 

vignettes/contributing.Rmd

@@ -0,0 +1,175 @@
+---
+title: "Contributing to iSEEhub"
+author: 
+  - name: Kevin Rue-Albrecht
+    affiliation:
+    - University of Oxford
+    email: kevin.rue-albrecht@imm.ox.ac.uk
+output: 
+  BiocStyle::html_document:
+    self_contained: yes
+    toc: true
+    toc_float: true
+    toc_depth: 2
+    code_folding: show
+date: "`r doc_date()`"
+package: "`r pkg_ver('iSEEhub')`"
+vignette: >
+  %\VignetteIndexEntry{Contributing to iSEEhub}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}  
+---
+
+```{r setup, include = FALSE}
+knitr::opts_chunk$set(
+    collapse = TRUE,
+    comment = "#>",
+    crop = NULL ## Related to https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016656.html
+)
+```
+
+
+```{r vignetteSetup, echo=FALSE, message=FALSE, warning = FALSE}
+## Track time spent on making the vignette
+startTime <- Sys.time()
+
+## Bib setup
+library("RefManageR")
+
+## Write bibliography information
+bib <- c(
+    R = citation(),
+    BiocStyle = citation("BiocStyle")[1],
+    knitr = citation("knitr")[1],
+    RefManageR = citation("RefManageR")[1],
+    rmarkdown = citation("rmarkdown")[1],
+    sessioninfo = citation("sessioninfo")[1],
+    testthat = citation("testthat")[1],
+    iSEEhub = citation("iSEEhub")[1]
+)
+```
+
+
+# Initial app configurations
+
+## Overview
+
+Initial app configurations configure the set of panels and their respective initial state when the main `r Biocpkg("iSEE")` app is launched.
+
+Initial app configurations are implemented as _R_ scripts that are stored in the `inst/initial` subdirectory of the `r Biocpkg("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 `r Biocpkg("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 `r Biocpkg("iSEE")` package -- so-called built-in panels -- and other packages that extend `r Biocpkg("iSEE")` functionality.
+That is, packages like `r Biocpkg("iSEEu")` and `r Biocpkg("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 `r Biocpkg("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](https://github.com/kevinrue/iSEEhub/).
+- Create and/or edit appropriate files and directories within the `inst/initial` directory.
+- Test your new configuration(s) locally; install the updated `r Biocpkg("iSEEhub")` package, launch the app, and load dataset(s) using the new configuration(s).
+- Open a pull request on the GitHub repository.
+- Wait for maintainers to review and approve the pull request.
+
+# Reproducibility
+
+The `r Biocpkg("iSEEhub")` package `r Citep(bib[["iSEEhub"]])` was made possible thanks to:
+
+* R `r Citep(bib[["R"]])`
+* `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])`
+* `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])`
+* `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`
+* `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])`
+* `r CRANpkg("sessioninfo")` `r Citep(bib[["sessioninfo"]])`
+* `r CRANpkg("testthat")` `r Citep(bib[["testthat"]])`
+
+This package was developed using `r BiocStyle::Biocpkg("biocthis")`.
+
+
+Code for creating the vignette
+
+```{r createVignette, eval=FALSE}
+## 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.
+
+```{r reproduce1, echo=FALSE}
+## Date the vignette was generated
+Sys.time()
+```
+
+Wallclock time spent generating the vignette.
+
+```{r reproduce2, echo=FALSE}
+## Processing time in seconds
+totalTime <- diff(c(startTime, Sys.time()))
+round(totalTime, digits = 3)
+```
+
+_R_ session information.
+
+```{r reproduce3, echo=FALSE}
+## Session info
+library("sessioninfo")
+options(width = 120)
+session_info()
+```
+
+
+
+# Bibliography
+
+This vignette was generated using `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])`
+with `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])` and `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])` running behind the scenes.
+
+Citations made with `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`.
+
+```{r vignetteBiblio, results = "asis", echo = FALSE, warning = FALSE, message = FALSE}
+## Print bibliography
+PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html"))
+```

vignettes/iSEEhub.Rmd

@@ -55,7 +55,7 @@ bib <- c(
 
 ## Install `iSEEhub`
 
-`R` is an open-source statistical environment which can be easily modified to enhance its functionality via packages. `r Biocpkg("iSEEhub")` is a `R` package available via the [Bioconductor](http://bioconductor.org) repository for packages. `R` can be installed on any operating system from [CRAN](https://cran.r-project.org/) after which you can install `r Biocpkg("iSEEhub")` by using the following commands in your `R` session:
+_R_ is an open-source statistical environment which can be easily modified to enhance its functionality via packages. `r Biocpkg("iSEEhub")` is a _R_ package available via the [Bioconductor](http://bioconductor.org) repository for packages. _R_ can be installed on any operating system from [CRAN](https://cran.r-project.org/) after which you can install `r Biocpkg("iSEEhub")` by using the following commands in your _R_ session:
 
 ```{r "install", eval = FALSE}
 if (!requireNamespace("BiocManager", quietly = TRUE)) {
@@ -80,7 +80,7 @@ If you are asking yourself the question "Where do I start using Bioconductor?" y
 
 ## Asking for help
 
-As package developers, we try to explain clearly how to use our packages and in which order to use the functions. But `R` and `Bioconductor` have a steep learning curve so it is critical to learn where to ask for help. The blog post quoted above mentions some but we would like to highlight the [Bioconductor support site](https://support.bioconductor.org/) as the main resource for getting help: remember to use the `iSEEhub` tag and check [the older posts](https://support.bioconductor.org/t/iSEEhub/). Other alternatives are available such as creating GitHub issues and tweeting. However, please note that if you want to receive help you should adhere to the [posting guidelines](http://www.bioconductor.org/help/support/posting-guide/). It is particularly critical that you provide a small reproducible example and your session information so package developers can track down the source of the error.
+As package developers, we try to explain clearly how to use our packages and in which order to use the functions. But _R_ and _Bioconductor_ have a steep learning curve so it is critical to learn where to ask for help. The blog post quoted above mentions some but we would like to highlight the [Bioconductor support site](https://support.bioconductor.org/) as the main resource for getting help: remember to use the `iSEEhub` tag and check [the older posts](https://support.bioconductor.org/t/iSEEhub/). Other alternatives are available such as creating GitHub issues and tweeting. However, please note that if you want to receive help you should adhere to the [posting guidelines](http://www.bioconductor.org/help/support/posting-guide/). It is particularly critical that you provide a small reproducible example and your session information so package developers can track down the source of the error.
 
 ## Citing `iSEEhub`
 
@@ -91,6 +91,10 @@ We hope that `r Biocpkg("iSEEhub")` will be useful for your research. Please use
 citation("iSEEhub")
 ```
 
+Here is an example of you can cite your package inside the vignette:
+
+* `r Biocpkg("iSEEhub")` `r Citep(bib[["iSEEhub"]])`
+
 
 
 # Quick start to using to `iSEEhub`
@@ -100,7 +104,7 @@ The main functionality of the package is available through the function `iSEEhub
 The function returns a `r Biocpkg("shiny")` app that can then be launched using the function `shiny::runApp()`.
 
 ```{r "start", message=FALSE}
-library("iSEEhub")
+library(iSEEhub)
 library(ExperimentHub)
 ehub <- ExperimentHub()
 
@@ -111,27 +115,92 @@ if (interactive()) {
 }
 ```
 
-Here is an example of you can cite your package inside the vignette:
+<img src="screenshots/landing_page_overview.png" width="100%" />
 
-* `r Biocpkg("iSEEhub")` `r Citep(bib[["iSEEhub"]])`
 
 
+# The ExperimentHub pane
+
+Datasets available in the _Bioconductor_ `r Biocpkg("ExperimentHub")` are listed -- along with metadata -- in the interactive table on the left.
+
+The table may be filtered and sorted using any metadata column, to efficiently browse the datasets available.
+
+By default, only a subset of metadata columns are displayed.
+The selectize input labelled `Show columns:` at the top of the pane may be used to add, remove, or reorder columns in the table.
+
+No more than one dataset may be selected at any time.
+
+
+
+# The Selected Dataset pane
+
+## Overview
+
+The pane on the right updates with the currently selected dataset.
+
+This pane contains information and the users inputs required to load the currently selected dataset in the main about the currently selected dataset in the main `r Biocpkg("iSEE")` app.
+
+The pane is composed of two tabs described in the following sections.
+
+## The Info tab
+
+The `Info` tab displays the full metadata associated with the currently selected dataset -- the same metadata as in the `ExperimentHub` table -- in formatted text.
 
-# Managing data set dependencies
+As such, users can uses a minimal subset of columns in the table to efficiently browse available datasets, while having a full overview of the currently selected dataset in this tab.
 
-Each data set in the Bioconductor `r Biocpkg("ExperimentHub")` is associated with package dependencies that are required to handle the data set in an _R_ session.
-Package dependencies must be installed in the _R_ library before the corresponding data set can be loaded.
+## The Config tab
 
-The list of packages associated with all data sets types supported by `r Biocpkg("iSEEhub")` is regularly updated in the `Suggests:` field of the `DESCRIPTION` file.
+The `Config` tab displays a selectize input offering users a choice of initial app configurations that are specific to the currently selected dataset.
+
+For all datasets, an option `Default` is available.
+That option does not provide any specific instruction with respect to the initial set of panels, their layout, nor their respective initial settings.
+Instead, the `Default` option prompts the app to automatically identify all the built-in `r Biocpkg("iSEE")` panel classes that are compatible with the loaded dataset, initialising an app that contains one instance of each of those panels.
+
+The number of panels and data points to draw for large datasets makes the `Default` option a showcase mode for demonstration and for new users, more than one optimised for a short loading time or featuring specific aspects of the dataset.
+
+For some datasets, additional choices of initial settings are available.
+Configurations are provided as scripts that define the list of panels and their respective initial configuration when the main `r Biocpkg("iSEE")` app is launched.
+
+To contribute new scripts, please refer to the vignette [Contributing to iSEEhub](contributing.html).
+
+For demonstration, a simple example `config_1.R` is included for the dataset `EH1`.
+When selected, the contents of the configuration file are shown in the pane -- including any comment from the authors -- allowing users to review the script before using it.
+
+When the apropriate configuration is selected, users may click the `Launch!` button to load the dataset into the main `r Biocpkg("iSEE")` app.
+
+<img src="screenshots/landing_page_config.png" width="100%" />
+
+# The main iSEE app
+
+Once the dataset is successfully loaded into the _R_ session, the app will switch to the main `r Biocpkg("iSEE")` view.
+
+<img src="screenshots/isee_eh1.png" width="100%" />
+
+# Managing dataset dependencies
+
+## Overview
+
+Each dataset in the Bioconductor `r Biocpkg("ExperimentHub")` is associated with package dependencies that are required to handle the dataset in an _R_ session.
+Package dependencies must be installed in the _R_ library before the corresponding dataset can be loaded.
+
+The list of packages associated with all datasets types supported by `r Biocpkg("iSEEhub")` is regularly updated in the `Suggests:` field of the `DESCRIPTION` file.
 However, those packages are not automatically installed in a minimal installation of the `r Biocpkg("iSEEhub")` package.
 
+## From the _R_ console
+
 By default, `iSEEhub(..., runtime_install = FALSE)` prevents the app from installing those dependencies at runtime.
 In that case, when users identify a missing dependency, they must interrupt the app, install the required package(s) using the _R_ console, and re-launch the app.
 We recommend this approach for applications hosted on public web-servers.
 
+<img src="screenshots/dependencies_missing_blocked.png" width="100%" />
+
+## From the live app
+
 Alternatively, `iSEEhub(..., runtime_install = TRUE)` can be used to launch an app that prompts users interactively (i.e., within the app) for their consent to install missing dependencies.
 We recommend this approach for applications run on personal computers (unless users prefer to install packages themselves, of course).
 
+<img src="screenshots/dependencies_missing_prompt.png" width="100%" />
+
 
 
 # Reproducibility
@@ -176,7 +245,7 @@ totalTime <- diff(c(startTime, Sys.time()))
 round(totalTime, digits = 3)
 ```
 
-`R` session information.
+_R_ session information.
 
 ```{r reproduce3, echo=FALSE}
 ## Session info