---
title: "Introduction to iSEEindex"
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('iSEEindex')`"
vignette: >
  %\VignetteIndexEntry{Introduction to iSEEindex}
  %\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, eval=!exists("SCREENSHOT"), include=FALSE}
SCREENSHOT <- function(x, ...) knitr::include_graphics(x)
```

```{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],
    iSEEindex = citation("iSEEindex")[1]
)
```

# Basics

## Install `iSEEindex`

`R` is an open-source statistical environment which can be easily modified to enhance its functionality via packages. `r Biocpkg("iSEEindex")` 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("iSEEindex")` by using the following commands in your `R` session:

```{r "install", eval = FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE)) {
      install.packages("BiocManager")
  }

BiocManager::install("iSEEindex")

## Check that you have a valid Bioconductor installation
BiocManager::valid()
```

## Required knowledge

`r Biocpkg("iSEEindex")` is based on many other packages and in particular those that have implemented the infrastructure needed for dealing with omics data and interactive visualisation.
That is, packages like `r BiocStyle::Biocpkg("SummarizedExperiment")`, `r BiocStyle::Biocpkg("SingleCellExperiment")`, `r BiocStyle::Biocpkg("iSEE")` and `r BiocStyle::Biocpkg("shiny")`.

If you are asking yourself the question "Where do I start using Bioconductor?" you might be interested in [this blog post](http://lcolladotor.github.io/2014/10/16/startbioc/#.VkOKbq6rRuU).

## 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 `iSEEindex` tag and check [the older posts](https://support.bioconductor.org/t/iSEEindex/). 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 `iSEEindex`

We hope that `r Biocpkg("iSEEindex")` will be useful for your research. Please use the following information to cite the package and the overall approach. Thank you!

```{r "citation"}
## Citation info
citation("iSEEindex")
```

# Quick start to using `iSEEindex`

This is a basic example which shows you how to launch an application that lists publicly available data sets hosted on [zenodo.org][zenodo-repository]:

```{r "start", message=FALSE, warning=FALSE}
library("iSEEindex")
library("BiocFileCache")

bfc <- BiocFileCache(cache = tempdir())

dataset_fun <- function() {
    x <- yaml::read_yaml(system.file(package="iSEEindex", "example.yaml"))
    x$datasets
}

initial_fun <- function() {
    x <- yaml::read_yaml(system.file(package="iSEEindex", "example.yaml"))
    x$initial
}

app <- iSEEindex(bfc, dataset_fun, initial_fun)

if (interactive()) {
  shiny::runApp(app, port = 1234)
}
```

```{r, echo=FALSE}
SCREENSHOT("screenshots/landing_page.png", delay=20)
```

Let's break down this example step by step, to illustrate the functionality and flexibility of `r Biocpkg("iSEEindex")`.

First, we load the `r Biocpkg("iSEEindex")` and `r Biocpkg("BiocFileCache")` packages, to access their functionality.

Next, we use the `BiocFileCache::BiocFileCache()` function, to create a persistent on-disk cache of files that the app can use for adding and retrieving data files between sessions.
This is particularly useful in this example, as we demonstrate the hosting of data sets and configuration scripts in RDS files and R scripts remotely, in a [zenodo.org repository][zenodo-repository].

Next, we define a function -- in this example, named `dataset_fun` -- that returns a `list` of metadata for available data sets.
In this example, the information is parsed from an example file distributed in the `inst/` directory of the package.
However, users may define a function that fetches that information in any way they see fit, e.g. authenticating and accessing data from privately accessible sources.
Requirements for that function are detailed in the help page `?iSEEindex`, for the argument `FUN.datasets`.

Next, we define another function -- in this example, named `initial_fun` -- that returns a `list` of metadata for available initial configurations of the application state, for each individual data set.
In this example, the information is parsed from an example file distributed in the `inst/` directory of the package.
However, similarly to the previous function, users may define a function that fetches that information in any way they see fit.
Requirements for that function are detailed in the help page `?iSEEindex`, for the argument `FUN.initial`.

Then, we pass the `BiocFileCache` object and the two custom functions defined above to the `iSEEindex::iSEEindex()` function, to create an `r Biocpkg("iSEE")` application that incorporates a landing page offering users the choice of data sets and initial configurations fetched by the custom functions.

Finally, we use the `shiny::runApp()` function to launch the app.



# Reproducibility

The `r Biocpkg("iSEEindex")` package `r Citep(bib[["iSEEindex"]])` 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("iSEEindex.Rmd", "BiocStyle::html_document"))

## Extract the R code
library("knitr")
knit("iSEEindex.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 = 100)
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"))
```

<!-- Links -->

[zenodo-repository]: https://zenodo.org/record/7304331