---
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/iSEE/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 [iSEEhub](https://github.com/iSEE/iSEEhub/).
- 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"))
```