iSEEde.Rmd

---
title: "Introduction to iSEEde"
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('iSEEde')`"
vignette: >
  %\VignetteIndexEntry{Introduction to iSEEde}
  %\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
)
options(width = 100)
```

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

# Basics

## Install `iSEEde`

`r fontawesome::fa("r-project")` is an open-source statistical environment which can be easily modified to
enhance its functionality via packages. `r Biocpkg("iSEEde")` is an `r fontawesome::fa("r-project")` package
available via the [Bioconductor](http://bioconductor.org) repository for
packages. `r fontawesome::fa("r-project")` can be installed on any operating system from
[CRAN](https://cran.r-project.org/) after which you can install 
`r Biocpkg("iSEEde")` by using the following commands in your `r fontawesome::fa("r-project")` session:

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

BiocManager::install("iSEEde")

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

## Required knowledge

`r Biocpkg("iSEEde")` is based on many other packages and in particular on
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 fontawesome::fa("r-project")` 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 `iSEEde` tag and 
check
[the older posts](https://support.bioconductor.org/t/iSEEde/). 
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 `iSEEde`

We hope that `r Biocpkg("iSEEde")` 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("iSEEde")
```

# Quick start to using to `iSEEde`

The example below demonstrates how to use `r Biocpkg("iSEEde")` functionality in a simple differential expression workflow.

Specifically, the `r Biocpkg("DESeq2")` package is used to perform a simple differential expression analysis.
Then, the results of one contrast -- extracted using the function `DESeq2::results()` function -- are embedded into the `r Biocpkg("SummarizedExperiment")` object `airway` using the function `iSEEde::embedContrastResults()`.
This ensures that the differential expression results for that contrast are accessible to specialised interactive panels in `r Biocpkg("iSEE")` applications.

```{r "start", message=FALSE, warning=FALSE}
library("iSEEde")
library("airway")
library("DESeq2")
library("iSEE")

# Example data ----

data("airway")
airway$dex <- relevel(airway$dex, "untrt")

dds <- DESeqDataSet(airway, ~ 0 + dex + cell)

dds <- DESeq(dds)
res_deseq2 <- results(dds, contrast = list("dextrt", "dexuntrt"))
head(res_deseq2)

# iSEE / iSEEde ---

airway <- embedContrastResults(res_deseq2, airway, name = "dex: trt vs untrt")
contrastResults(airway)

app <- iSEE(airway, initial = list(
  DETable(ContrastName="dex: trt vs untrt", HiddenColumns = c("baseMean", 
    "lfcSE", "stat"), PanelWidth = 4L),
  VolcanoPlot(ContrastName="dex: trt vs untrt", PanelWidth = 4L),
  MAPlot(ContrastName="dex: trt vs untrt", PanelWidth = 4L)
))

if (interactive()) {
    shiny::runApp(app)
}
```

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

# Reproducibility

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

## Extract the R code
library("knitr")
knit("iSEEde.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 fontawesome::fa("r-project")` 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"))
```