importing_pySCENIC.Rmd

---
title: "Importing pySCENIC results"
subtitle: Importing pySCENIC output into R
output:
  html_document:
    number_sections: no
    toc: yes
    toc_float: false
    css: corrected.css
  html_notebook:
    toc: yes
  pdf_document:
    toc: yes
vignette: >
  %\VignetteIndexEntry{Importing pySCENIC output} 
  %\VignetteEngine{knitr::rmarkdown} 
  %\VignetteEncoding{UTF-8}
---

```{r libraries, echo=FALSE, message=FALSE, warning=FALSE}
# Suppress loading messages when building the HTML
suppressPackageStartupMessages({
  library(SCENIC)
  library(data.table)
  library(GSEABase)
  library(AUCell)
  library(SCopeLoomR)
})
```

This vignette is deprecated. pySCENIC (VSN) results are now saved into a loom file by default. 
See section **Loading results from a .loom file** from the main vignette.


**pySCENIC** (https://pyscenic.readthedocs.io/) provides a faster implementation of SCENIC (in Python) that can be easily paralelized with Dask (e.g. to take advantage distributed systems). The results of pySCENIC can easily be imported into R.

The main results of SCENIC analysis are stored in the loom file:

- Regulons 

- Regulon activity (AUC matrix and thresholds)

- Embeddings (e.g. t-SNE and UMAP on the regulon activity)

The **motif enrichment analysis** and **co-expression modules** (e.g. GRNBoost/GENIE3 output) are stored in independent text files (mostly due to their bigger size).

```{r setDirectories, message=FALSE, warning=FALSE}
# Output directories (adjust to yours):
pyScenicDir <- "pySCENIC_example/out"

library(SCENIC)
```

# Reading the loom file

`SCopeLoomR` provides functions to import the regulons, AUC, and embeddings from the loom file: 

```{r loomSCENIC}
library(SCopeLoomR)

pyScenicLoomFile <- file.path(pyScenicDir, "SCENIC.loom")
loom <- open_loom(pyScenicLoomFile, mode="r")

# Read information from loom file
# Regulons:
regulons_incidMat <- get_regulons(loom) # as incid matrix
regulons_motif <- regulonsToGeneLists(regulons_incidMat) # convert to list

regulons_ChIP <- regulonsToGeneLists(get_regulons(loom, attrName = "TrackRegulons"))

# Regulon AUC and thresholds
regulonsAUC <- get_regulonsAuc(loom)
regulonsAucThresholds <- get_regulonThresholds(loom)

# Embeddings (tsne/umap)
embeddings <- get_embeddings(loom)
```

In addition, the loom file also stores the expression matrix, and allows to save information about the cells (e.g. cell annotations), or results from previous clustering analyses: 

```{r loomExtra, eval=FALSE}
exprMat <- get_dgem(loom)
# cellInfo <- get_cellAnnotation(loom) # will also contain AUC values, etc... you can filter them out
clusterings <- get_clusterings_withName(loom)
```

```{r}
close_loom(loom)
```

# Motif enrichment analysis

The motif enrichment results provided by pySCENIC are in a slightly different format than the table provided by RcisTarget (e.g. R implementation of SCENIC) but they are equivalent. This table can be read from the text file and visualized/explored in a similar way: 

```{r motifEnrichment}
sampleName <- "yourSampleName"
# Read table
motifsDf <- data.table::fread(file.path(pyScenicDir, "out/scenic/",sampleName,"/cistarget/",sampleName,"__reg_mtf.csv"), header = T, sep="\t")
maxRows <- 20 # (low value only for the tutorial)

# Visualize
tableSubset <- motifsDf[TF=="Dlx5"]
tableSubset <- tableSubset[1:maxRows,] 
colsToShow <- colnames(motifsDf)[-c(2,9:11)]
viewMotifs(tableSubset, colsToShow=colsToShow)
```

# GRNBoost/GENIE3 results

```{r GRNBoost}
GRNBoost_linkList <- importArboreto(file.path(pyScenicDir,  "adjacencies.tsv"))
head(GRNBoost_linkList)
```