---
title: "SiPSiC - Infer Biological Pathway Activity from Single-Cell RNA-Seq Data"
package: "`r pkg_ver('SiPSiC')`"
abstract: >
  Single Pathway analysis in Single Cells (SiPSiC) enables you to calculate a per-cell score for a biological pathway of your choice from single-cell RNA-seq (scRNA-seq) data. 
  Its only function is the getPathwayScores function, which takes scRNA-seq data and an array containing the names of the genes comprising the relevant biological pathway, and calculates pathway scores for each cell in the data. 
  Have the data in Transcripts-Per-Miilion (TPM) or Counts-Per-Million (CPM) units for best results.
vignette: >
  %\VignetteIndexEntry{Infer Biological Pathway Activity from Single-Cell RNA-Seq Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output: 
  BiocStyle::html_document:
    toc: yes
    number_sections: false
  pdf_document:
    toc: yes
  html_notebook:
    toc: yes
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
suppressPackageStartupMessages({library(SiPSiC)})
```

# Introduction
Single cell RNA sequencing is a prevelant practice to interrogate tissue characteristics and heterogeneity in health and disease. Finding which gene sets (pathways) are enriched in single cells allows to unravel
the different subpopulations of cells that exist in the interrogated tissue and elucidate their biological and functional underpinnings. Different methods have been developed for this purpose, the most prominent 
of which is AUCell. However, some of these methods, including AUCell, use gene rankings to test for such enrichment and avoid using data of different cells when calculating pathway scores for a specific cell. 
While AUCell and other methods produced insightful results in prior research, we found that some important findings might be missed by using them. We therefore developed SiPSiC to allow the dissection of tissue 
heterogeneity and unravel the function and biological traits of cell subpopulations. By using gene counts and the transcriptome of different cells in the data when calculating pathway scores for an individual cell, 
SiPSiC allows to unveil subpopulation characteristics which are sometimes missed by other methods, hence it has been deposited to Bioconductor.  

# Installation
Install SiPSiC by executing the following commands in an R session:

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

BiocManager::install("SiPSiC")
```

# Code Example
```{r Example, warning=FALSE}
library(SiPSiC)
geneCountsMatrix <- matrix(rpois(16, lambda = 10), ncol = 4, nrow = 4)
geneCountsMatrix <- as(geneCountsMatrix, "dgCMatrix")

## Make sure your matrix is indeed a sparse matrix (of type dgCMatrix)! 

rownames(geneCountsMatrix) <- c("Gene1", "Gene2", "Gene3", "Gene4")
colnames(geneCountsMatrix) <- c("Cell1", "Cell2", "Cell3", "Cell4")
assayData <- SingleCellExperiment(assays = list(counts = geneCountsMatrix))
pathwayGenesList <- c("Gene1", "Gene2", "Gene4")
scoresAndIndices <- getPathwayScores(counts(assayData), pathwayGenesList)
pathwayScoresOfCells <- scoresAndIndices$pathwayScores
pathwayGeneIndices <- scoresAndIndices$index
```
# SiPSiC's Algorithm
Taking an scRNA-seq data matrix and the list of genes of which the relevant pathway consists, SiPSiC uses five steps to calculate the score for all the cells in the data; These are:

## 1. Pathway data extraction 
Pick only genes which belong to the pathway.

## 2. Score normalization 
For each gene separately: If none of the cells transcribe the gene, keep the values as they are (all zeros); Otherwise, calculate the median of the 5% top expressing cells, divide all values by this median and keep them. If the median is zero, however, the values are divided by the maximum value across all cells instead.
The reason behind this step is that scRNA-seq data are normally sparse, namely, the fraction of zeros in the data is large; Thus, by selecting the median of the top 5% cells there is a high likelihood that for most genes the value will be greater than zero, while on the other hand it will also not be an outlier, which may perturb further processing steps.

## 3. Normalized gene rankings calculation
Independently of step 2, rank the genes by their total counts (TPM or CPM) across all cells, then divide the ranks by the total number of genes; This normalization ensures that all the ranks remain within the range (0,1] regardless of the total number of genes.

## 4. Gene weighing
Multiply the results of each gene from step 2 by its normalized ranking from step 3.

## 5. Pathway scoring
Set each cell’s pathway score as the average of its values across all genes, as provided by step 4. Note that the higher the total number of counts for a gene is, the more it affects the pathway scores of all the cells in the data. We find this reasonable as the transcription of genes with higher total counts is likely to differ to a greater extent between cells, allowing us to reveal biological differences more accurately.


# Session Information
Following is the output of the 'sessionInfo()' function observed on the system on which the package was built:
```{r}
sessionInfo()
```