README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
    eval = FALSE,
    collapse = TRUE,
    comment = "#>",
    dpi = 900,
    fig.path = "man/figures/README-",
    out.width = "100%"
)
```

# seuratTools

This package includes a set of Shiny apps for exploring single cell RNA datasets processed with <a href="https://github.com/satijalab/seurat" target="_blank" rel="noopener noreferrer">Seurat</a>

A demo using a human gene transcript dataset from Shayler et al. (link) is available <a href="https://docker.saban.chla.usc.edu/cobrinik/app/seuratApp/" target="_blank" rel="noopener noreferrer">here</a>

There are also convenient functions for:

-   Clustering and Dimensional Reduction of Raw Sequencing Data.
-   <a href="https://satijalab.org/seurat/archive/v3.0/integration.html" target="_blank" rel="noopener noreferrer">Integration and Label Transfer</a>
-   Louvain Clustering at a Range of Resolutions
-   Cell cycle state regression and labeling
-   RNA velocity calculation with <a href="https://velocyto.org/" target="_blank" rel="noopener noreferrer">Velocyto.R</a> and <a href="https://scvelo.readthedocs.io/" target="_blank" rel="noopener noreferrer">scvelo</a>

> [!WARNING]
> seuratTools was designed for full-length smart-seq based single cell data. Default settings may not be appropriate for droplet (10x) data, though most can be adjusted. Keep in mind [best practices](https://satijalab.org/seurat/articles/pbmc3k_tutorial) regarding normalization, dimensional reduction, etc. when using. 

## Installation

You can install the released version of seuratTools from <a href="https://github.com/whtns/seuratTools" target="_blank" rel="noopener noreferrer">github</a> with:

### Install locally and run in three steps:

You can install seuratTools locally using the following steps:

```{r, eval=FALSE}
install.packages("devtools")
devtools::install_github("whtns/seuratTools")
seuratTools::create_project_db()
```

You can also customize the location of the app using these steps:

```{r, eval=FALSE}
devtools::install_github("whtns/seuratTools")
seuratTools::create_project_db(destdir = "/your/path/to/app")
```


## Getting Started

First, load seuratTools and all other packages required 

```{r}
library(seuratTools)
library(Seurat)
library(tidyverse)
library(ggraph)
```

## TLDR

seuratTools provides a single command to:

-   construct a Seurat object

-   filter genes by minimum expression and ubiquity

-   normalize and scale expression by any of several methods packaged in Seurat

## Run clustering on a single seurat object

By default clustering will be run at ten different resolutions between 0.2 and 2.0. Any resolution can be specified by providing the resolution argument as a numeric vector.

```{r, cache = FALSE, eval = FALSE}
clustered_seu <- clustering_workflow(human_gene_transcript_seu,
    experiment_name = "seurat_hu_trans",
    organism = "human"
)
```

## Get a first look at a processed dataset using an interactive shiny app

```{r, eval = FALSE}
minimalSeuratApp(human_gene_transcript_seu)
```

## Set up a seurat object

We start with a gene by cell matrix of count/UMI values and a table of cell metadata

```{r, eval=FALSE}
human_count[1:5, 1:5]

head(human_meta)
```

```{r, eval = FALSE, echo=FALSE}
knitr::kable(human_count[1:5, 1:5])

knitr::kable(head(human_meta))
```

We can then create a seurat object in the usual manner using `CreatSeuratObject` function

```{r}
myseu <- CreateSeuratObject(human_count, assay = "gene", meta.data = human_meta)
```

## Preprocess the seurat object

seuratTools includes a handy function to preprocess the data that handles normalization and scaling required for downstream analysis. If needed, parameters can be specified by the user.

```{r, message = FALSE}
myseu <- seurat_preprocess(myseu)
```

This single function includes seurat sub-functions that normalizes, identifies highly variable features and scales the data

## Perform dimension reduction

seuratTools also implements a standardized dimension reduction step to select variable features at a user-specified threshold and perform PCA, tSNE, and UMAP. The default assay the dimension reduction is being run on is "gene".

```{r, results=FALSE, warning = FALSE, message=FALSE}
myseu <- seurat_reduce_dimensions(myseu, assay = "RNA")
```


## Community detection by clustering

Clustering analysis is performed via Louvain(default) or alternative algorithms available in Seurat. Clustering is performed at a range of resolutions with default value ranging from 0.2 to 2 and pca reduction

```{r, message = FALSE, result = FALSE, chache = FALSE, warning = FALSE}
seu <- seurat_cluster(seu = Dim_Red_seu, resolution = seq(0.2, 2, by = 0.2))
```

This function produces clustering analysis via two steps performed using two different sub-functions


## Split included dataset based on collection technology

seuratTools includes a function, `SplitObject`, which is capable of splitting the dataset into subsets based on a single attribute indicated by the split.by argument 

```{r}
split_human <- SplitObject(human_gene_transcript_seu, split.by = "dataset")
```
In this example the `split_human` object consists of a list of subsetted objects which are split based on batch


## Run seurat batch integration on 'child' projects

When joint analysis of 2 or more datasets is to be performed `integration_workflow` function can be used, which takes in a list of seurat objects as input and returns an integrated seurat object

```{r, results="hide", cache = FALSE}
integrated_seu <- integration_workflow(split_human)
```

## View analysis details

```{r, eval = FALSE}
Misc(integrated_seu, "experiment") %>%
    tibble::enframe() %>%
    knitr::kable()
```