---
title: "scRNAseqApp Guide"
author: "Jianhong Ou"
bibliography: bibliography.bib
csl: nature.csl
vignette: >
  %\VignetteIndexEntry{scRNAseqApp Vignette}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
    toc_depth: 4
runtime: shiny
---

```{r, echo=FALSE, results="hide", warning=FALSE, message=FALSE}
suppressPackageStartupMessages({
    library(scRNAseqApp)
})
knitr::opts_chunk$set(warning=FALSE, message=FALSE, fig.width=5, fig.height=3.5)
```

# Introduction

Single-cell RNA sequencing (scRNA-seq) is a powerful technique to study gene
expression, cellular heterogeneity, and cell states within samples in
single-cell level. The development of scRNA-seq shed light to address the
knowledge gap about the cell types, cell interactions, and key genes involved
in biological process and their dynamics.

To increase the re-usability and reproducibility of scientific findings,
more and more publishers require raw data and detailed descriptions of how the
data were analyzed. However, difficulties arise due to the highly concise
descriptions of analysis and the differences of the computing environments.
Furthermore, to precisely meet the publishing requirement, the communication of
the bioinformatician with researchers is a time-consuming step.
Multiple interactive visualization tools were developed to provide the
researchers access to the details of the data. Those tools include,
but not limited to,
alona[@franzen2020alona],
ASAP[@gardeux2017asap],
Asc-Seurat[@pereira2021asc],
BingleSeq[@dimitrov2020bingleseq],
CellView[@bolisetty2017cellview],
cellxgene VIP[@li2022cellxgene],
Cerebro[@hillje2020cerebro],
CHARTS[@bernstein2021charts],
ChromSCape[@prompsy2020interactive],
Cirrocumulus[@li2020cumulus],
CReSCENT[@mohanraj2020crescent],
Cytosplore Viewer[@tasic2018shared],
Granatum[@zhu2017granatum],
InterCellar[@interlandi2022intercellar],
iS-CellR[@patel2018cellr],
iSEE[@rue2018isee],
loom-viewer,
Loupe Cell Browser,
PIVOT[@zhu2018pivot],
SC1[@moussa2021sc1],
SCANNER[@cai2022scanner],
scClustViz[@innes2018scclustviz],
SCope[@davie2018single],
scSVA[@tabaka2019scsva],
scVI[@lopez2018deep],
SeuratV3Wizard[@yousif2020nasqar]/NASQAR,
ShinyArchRUiO[@sharma2022shinyarchr],
ShinyCell[@ouyang2021shinycell],
singleCellTK[@hong2022comprehensive],
Single Cell Explorer (scExplorer)[@feng2019single],
Single Cell Interactive Application (SCiAp)[@moreno2021user] and
UCSC Cell Browser[@speir2021ucsc],
SPRING[@weinreb2018spring],
WASP[@hoek2021wasp], and
Vitessce[@keller2021vitessce].

The basic information of the tools are list in the following tables
(the table was created at 12/06/2022):

| Tool               | platform       | plot type                              |
|:-------------------|:---------------|:---------------------------------------|
| alona              | web-based      | scatters, bar                          |
| ASAP               | web-based      | scatters                               |
| Asc-Seurat     | shiny package  | scatters, heatmap, violin, dot, trajectory |
| BingleSeq          | shiny package  | scatters, heatmap, violin, ridge       |
| CellView           | shiny package  | scatters                               |
| cellxgene VIP      | web-based      | scatters, bar, and visualization plugin|
| Cerebro/cerebroApp | shiny package  | scatters, 3D scatters                  |
| CHARTS             | web-based      | scatters, bar                          |
| ChromSCape         | shiny package  | scatters, heatmap                      |
| Cirrocumulus       | python package |                                        |
| CReSCENT           | web-based      | scatters, violin                       |
| Cytosplore Viewer  | Cytosplore     | scatters, phylogeny                    |
| Granatum           | shiny package  | scatters, bar, trajectory, ppi         |
| InterCellar        | shiny package  | dot, ppi, circos, radar, pie           |
| iS-CellR           | shiny package  | scatters, heatmap, violin, bar, dot    |
| iSEE               | shiny package  | scatters, heatmap, violin, bar         |
| loom-viewer        | python package |                                        |
| Loupe Cell Browser | Desktop        | scatters                               |
| PIVOT              | shiny package  | scatters, heatmap, violin, bar, pie    |
| SC1                | web-based      | scatters, heatmap, violin, bar         |
| SCANNER            | web-based      | scatters                               |
| scClustViz         | shiny package  | scatters, heatmap, violin, bar, dot    |
| scExplorer         | web-based      | scatters, heatmap                      |
| SCope              | web-based      | scatters                               |
| scSVA              | shiny package  | scatters, 3D scatters                  |
| scVI               | python package | scatters, heatmap, violin, bar         |
| seuratv3wizard     | web-based      | scatters                               |
| ShinyArchRUiO      | shiny package  | scatters, heatmap, track               |
| ShinyCell          | shiny package  | scatters, heatmap, violin, bar         |
| SCiAp[^1]          | galaxy         |                                        |
| singleCellTK   | shiny package  | scatters, heatmap, violin, dot, trajectory |
| SPRING             | python package | scatters                               |
| UCSC Cell Browser  | web-based      | scatters                               |
| Vitessce           | python package | scatters, heatmap                      |
| WASP               | shiny package  | scatters, heatmap                      |
[^1]: short name for Single Cell Interactive Application

| Tool           | languages  | license | starts | watching | forks | citation |
|:---------------|:-----------|:--------|:-------|:---------|:------|:---------|
| alona          | python     | GPL-3   | 12     | 3        | 5     | 24       |
| ASAP           | Java,R,Python  | GPL-3 | 18   | 6        | 8     | 88       |
| Asc-Seurat     | R          | GPL-3   | 12     | 2        | 6     | 10       |
| BingleSeq      | R          | MIT     | 18     | 2        | 6     | 4        |
| CellView       | R          | MIT     | 16     | 9        | 8     | 8        |
| cellxgene VIP  | python,R,JavaScript  | MIT    | 81   | 6 | 24    | 10       |
| Cerebro/cerebroApp | R,JavaScript,C   | MIT    | 79   | 7 | 18    | 41       |
| CHARTS         | python     | MIT     | 2      | 6        | 0     | 7        |
| ChromSCape     | R          | GPL-3   | 11     | 2        | 4     | 13       |
| Cirrocumulus   | JavaScript,Python  | BSD-3   | 38    | 7 | 9     | 78       |
| CReSCENT       | R,Perl     | GPL-3   | 8      | 1        | 4     | 11       |
| Cytosplore Viewer  | java,javascript  |  |     |          |       |          |
| Granatum       | R          | Apache2 | 18     | 4        | 11    | 65       |
| InterCellar    | R          | MIT     | 7      | 1        | 3     | 4        |
| iS-CellR       | R          | GPL-3   | 21     | 6        | 6     | 15       |
| iSEE           | R          | MIT     | 201    | 14       | 39    | 41       |
| loom-viewer    | python,JavaScript   | BSD-2   | 32   | 9 | 6     |          |
| Loupe Cell Browser |        |         |        |          |       |          |
| PIVOT          | R          |         | 27     | 6        | 15    | 27       |
| SC1            | R          |         |        |          |       | 5        |
| SCANNER        | R          |         | 0      | 2        | 1     | 1        |
| scClustViz     | R          | MIT     | 41     | 12       | 10    | 36       |
| scExplorer     | JavaScript,Python   | GPL-3   | 7    | 3 | 6     | 16       |
| SCope          | python,JavaScript   | GPL-3   | 60   | 8 | 14    | 438[^2]  |
| scSVA          | R          | GPL-3   | 20     | 6        | 7     | 8        |
| scVI           | python     | BSD-3   | 840    | 27       | 263   | 787      |
| seuratv3wizard | R          | GPL-3   | 29     | 8        | 13    | 28[^3]   |
| ShinyArchRUiO  | R          | GPL-3   | 11     | 2        | 4     | 3        |
| ShinyCell      | R          | GPL-3   | 70     | 9        | 23    | 28       |
| SCiAp          |            |         |        |          |       | 16       |
| singleCellTK   | R          | MIT     | 105    | 12       | 61    | 6        |
| SPRING         | python,matlab,JavaScript |    | 59   | 10   | 29 | 250      |
| UCSC Cell Browser | JavaScript,Python,R  | GPL-3   | 3   | 1 | 39 | 46       |
| Vitessce       | JavaScript,Python,R     | MIT     | 92  | 6 | 23 | 2        |
| WASP           | R,python   |         | 2      | 1        | 0     | 3        |
[^2]: the package contribute partial to the citation
[^3]: citation is from NASQAR

| Tool              | source code                                              |
|:------------------|:---------------------------------------------------------|
| alona             | https://github.com/oscar-franzen/adobo/                  |
| ASAP              | https://github.com/DeplanckeLab/ASAP                     |
| Asc-Seurat        | https://github.com/KirstLab/asc_seurat/                  |
| BingleSeq         | https://github.com/dbdimitrov/BingleSeq/                 |
| CellView          | https://github.com/mohanbolisetty/CellView               |
| cellxgene   VIP   | https://github.com/interactivereport/cellxgene_VIP       |
| Cerebro/cerebroApp| https://github.com/romanhaa/Cerebro                      |
| CHARTS            | https://github.com/stewart-lab/CHARTS                    |
| ChromSCape        | https://github.com/vallotlab/ChromSCape                  |
| Cirrocumulus      | https://github.com/lilab-bcb/cirrocumulus                |
| CReSCENT          | https://github.com/pughlab/crescent                      |
| Cytosplore Viewer |                                                          |
| Granatum          | https://github.com/lanagarmire/Granatum                  |
| InterCellar       | https://github.com/martaint/InterCellar                  |
| iS-CellR          | https://github.com/immcore/iS-CellR                      |
| iSEE              | https://github.com/iSEE/iSEE                             |
| loom-viewer       | https://github.com/linnarsson-lab/loom-viewer            |
| Loupe Cell Browser|                                                          |
| PIVOT             | https://github.com/kimpenn/PIVOT                         |
| SC1               |                                                          |
| SCANNER           | https://github.com/GuoshuaiCai/scanner                   |
| scClustViz        | https://github.com/BaderLab/scClustViz                   |
| scExplorer        | https://github.com/d-feng/scExplorer                     |
| SCope             | https://github.com/aertslab/Scope                        |
| scSVA             | https://github.com/klarman-cell-observatory/scSVA        |
| scVI              | https://github.com/scverse/scvi-tools                    |
| seuratv3wizard    | https://github.com/nasqar/seuratv3wizard                 |
| ShinyArchRUiO     | https://github.com/EskelandLab/ShinyArchRUiO             |
| ShinyCell         | https://github.com/SGDDNB/ShinyCell                      |
| SCiAp             |                                                          |
| singleCellTK      | https://github.com/compbiomed/singleCellTK               |
| SPRING            | https://github.com/AllonKleinLab/SPRING_dev              |
| UCSC Cell Browser | https://github.com/ucscGenomeBrowser/cellBrowser         |
| Vitessce          | https://github.com/vitessce/vitessce                     |
| WASP              | https://github.com/andreashoek/wasp                      |

| Tool              | demo                                                     |
|:------------------|:---------------------------------------------------------|
| alona             | https://alona.panglaodb.se/                              |
| ASAP              | https://asap.epfl.ch/                                    |
| Asc-Seurat        |                                                          |
| BingleSeq         |                                                          |
| CellView          | https://mbolisetty.shinyapps.io/CellView/                |
| cellxgene   VIP   | https://cellxgenevip-ms.bxgenomics.com/                  |
| Cerebro/cerebroApp|                                                          |
| CHARTS            | https://charts.morgridge.org/                            |
| ChromSCape        | https://vallotlab.shinyapps.io/ChromSCape/               |
| Cirrocumulus      |                                                          |
| CReSCENT          | https://crescent.cloud/                                  |
| Cytosplore Viewer |                                                          |
| Granatum          | http://granatum.dcmb.med.umich.edu:8103/                 |
| InterCellar       |                                                          |
| iS-CellR          |                                                          |
| iSEE              | https://marionilab.cruk.cam.ac.uk/iSEE_allen/            |
| loom-viewer       |                                                          |
| Loupe Cell Browser|                                                          |
| PIVOT             |                                                          |
| SC1               | https://sc1.engr.uconn.edu/                              |
| SCANNER           | https://www.thecailab.com/scanner/                       |
| scClustViz        | https://innesbt.shinyapps.io/scclustvizdemoapp/          |
| scExplorer        | http://singlecellexplorer.org                            |
| SCope             | https://scope.aertslab.org/                              |
| scSVA             |                                                          |
| scVI              |                                                          |
| seuratv3wizard    | https://nasqar.abudhabi.nyu.edu/SeuratV3Wizard/          |
| ShinyArchRUiO     | https://cancell.medisin.uio.no/ShinyArchR.UiO/           |
| ShinyCell         | http://shinycell1.ddnetbio.com/                          |
| SCiAp             | https://humancellatlas.usegalaxy.eu/                     |
| singleCellTK      | https://sctk.bu.edu/                                     |
| SPRING.           | https://kleintools.hms.harvard.edu/tools/                |
|                   | springViewer_1_6_dev.html?datasets/mouse_HPCs/           |
|                   | basal_bone_marrow/full[^4]                               |
| UCSC Cell Browser | https://cells.ucsc.edu/                                  |
| Vitessce          | http://vitessce.io/                                      |
| WASP              |                                                          |

| Tool              | visualization tutorial                                   |
|:------------------|:---------------------------------------------------------|
| alona             | https://alona.panglaodb.se/faq.html                      |
| ASAP              | https://asap.epfl.ch/home/tutorial?t=fca                 |
| Asc-Seurat        | https://asc-seurat.readthedocs.io/en/latest/index.html   |
| BingleSeq   | https://github.com/dbdimitrov/BingleSeq/blob/master/README.md  |
| CellView          |                                                          |
| cellxgene VIP|https://interactivereport.github.io/cellxgene_VIP/tutorial/docs|
| Cerebro/cerebroApp| https://romanhaa.github.io/cerebroApp/                   |
| CHARTS      | https://github.com/stewart-lab/CHARTS/blob/master/README.md    |
| ChromSCape  | https://vallotlab.github.io/ChromSCape/articles/vignette.html  |
| Cirrocumulus      | https://cirrocumulus.readthedocs.io/en/latest/           |
| CReSCENT          | https://pughlab.github.io/crescent-frontend/             |
| Cytosplore Viewer | https://viewer.cytosplore.org/                           |
| Granatum | https://github.com/lanagarmire/Granatum/blob/master/doc/          |
|                   | Granatum_manual_0.92.pdf[^4]                             |
| InterCellar       |                                                          |
| iS-CellR          |                                                          |
| iSEE              |                                                          |
| loom-viewer       | https://github.com/linnarsson-lab/loom-viewer            |
| Loupe Cell Browser|                                                          |
| PIVOT | https://rawgit.com/qinzhu/PIVOT/master/inst/app/www/manual_file.html |
| SC1               |                                                          |
| SCANNER           |                                                          |
| scClustViz        |                                                          |
| scExplorer        | http://singlecellexplorer.org/tutorial.html              |
| SCope             | https://github.com/aertslab/SCope/blob/master/README.md  |
| scSVA             | https://github.com/klarman-cell-observatory/scSVA/blob/  |
|                   | master/docs/index.md[^4]                                 |
| scVI           | https://docs.scvi-tools.org/en/stable/user_guide/index.html |
| seuratv3wizard|https://github.com/nasqar/seuratv3wizard/blob/master/README.md|
| ShinyArchRUiO     |                                                          |
| ShinyCell         | https://github.com/SGDDNB/ShinyCell/blob/master/README.md|
| SCiAp             |                                                          |
| singleCellTK      |                                                          |
| SPRING            | https://kleintools.hms.harvard.edu/tools/spring.html     |
| UCSC Cell Browser|https://cellbrowser.readthedocs.io/en/master/interface.html|
| Vitessce          | http://vitessce.io/docs/                                 |
| WASP              | https://github.com/andreashoek/wasp/blob/main/README.md  |
[^4]: URL shown in multiple lines

# Motivation

Based on [_ShinyCell_](https://github.com/SGDDNB/ShinyCell),
The _scRNAseqApp_ package is developed with multiple highly interactive
visualizations of how cells and subsets of cells cluster behavior.
The end users can discover the expression of genes in multiple interactive
manners with highly customized filter conditions by selecting metadata
supplied with the publications and download the ready-to-use results for
republishing. 

# Quick start

Here is an example using _scRNAseqApp_ with a subset of scRNA-seq data.

## Installation
First, install _scRNAseqApp_ and other packages required to run 
the examples.
Please note that the example dataset used here is from a small subset of
PBMC[@satija2015spatial].
Additional package are also required for enhancement functions such 
trajectory analysis or cell communication analysis.

```{r, eval=FALSE}
library(BiocManager)
BiocManager::install("scRNAseqApp")
```

## Load library

```{r}
library(scRNAseqApp)
```

## Initial the database

```{r}
publish_folder=tempdir()
scInit(app_path=publish_folder)
```

## Start shiny app
```{r}
scRNAseqApp(app_path = publish_folder)
```

# Create a new data

There are two ways to create a new data.

- from the administrator mode
- use R session

## by administrator

Log in to admin by `Switch User` tab and click `administrator button` in the 
right-bottom corner of screen. Click `UploadData` and upload a Seurat object.

## via R session

There are two steps to create a new data via R session.
First, create the config file with description of the data and
second create the data from a Seurat object.

```{r}
library(Seurat)
appconf <- createAppConfig(
            title="pbmc_small_test",
            destinationFolder = "pbmc_small_test",
            species = "Homo sapiens",
            doi="10.1038/nbt.3192",
            datatype = "scRNAseq",
            abstract = 'Put the description of the data here.')
createDataSet(
    appconf,
    pbmc_small,
    datafolder=file.path(publish_folder, "data"))
dir(file.path(publish_folder, 'data'))
```

# Add downloadable file

If you have files intended for user download, kindly save them in the
`www/download` folder.
The application will then generate a list, differentiating between files and
user folder names, for convenient access to download options.
The file named as `readme` in text format in each folder will be used as 
descriptions for the files.

# Distribute to a shiny server

There are two steps to distribute to a shiny server. First, install the package
in the server as root user. Second, in a R session run `scInit()` after load 
the `scRNAseqApp` library. If you initialed the app offline, copy the app folder
to the shiny server.

Note: the following files need to be writable for shiny: `www/database.sqlite`,
`www/counter.tsv` and the app `www` folder should also be writable because the 
user manager is depend on SQLite, and the SQLite needs to be able to 
create a journal file in the same directory as the DB, 
before any modifications can take place. 
The journal is used to support transaction rollback.

# SessionInfo

```{r}
sessionInfo()
```


# References
