---
title: 'Learning CD56 NK cells from CITE-seq PBMCs'
date: Compiled `r Sys.Date()`
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mapping cells from CITE-seq PBMCs from 10X Genomics to another data set}
  %\VignetteEngine{knitr::rmarkdown_notangle}
  %\VignetteEncoding{UTF-8}
---

In Figure 4 of the [pre-print](https://www.biorxiv.org/content/10.1101/2021.02.01.429207v3.full), we demonstrated that SignacX mapped cell type labels from one single cell data set to another; learning CD56<sup>bright</sup> NK cells from CITE-seq data. In this vignette, we reproduced this analysis, which can be used to map cell populations (or clusters of cells) from one data set to another. We also provide interactive access to the single cell data that were annotated with the CD56<sup>bright</sup> NK cell-model in the SignacX data portal (Note: the CD56<sup>bright</sup> NK cells appear in the "CellStates" annotation layer as red cells).

This vignette shows how to use SignacX with Seurat and SPRING to learn a new cell type category from single cell data.

## Load data

We start with CITE-seq data that were already classified with SignacX using the SPRING pipeline.

```{r setupSeurat, message = F, eval = F}
library(Seurat)
library(SignacX)
```

Load CITE-seq data from 10X Genomics processed with SPRING and classified with SignacX already.

```{r setup, message = F, eval = F}
# load CITE-seq data
data.dir = './CITESEQ_EXPLORATORY_CITESEQ_5K_PBMCS/FullDataset_v1_protein'
E = CID.LoadData(data.dir = data.dir)

# Load labels
json_data = rjson::fromJSON(file=paste0(data.dir,'/categorical_coloring_data.json'))
```

Create a Seurat object for the protein expression data; we will use this as a reference.

```{r Seurat, eval = F}
# separate protein and gene expression data
logik = grepl("Total", rownames(E))
P = E[logik,]
E = E[!logik,]

# CLR normalization in Seurat
colnames(P) <- 1:ncol(P)
colnames(E) <- 1:ncol(E)
reference <- CreateSeuratObject(E)
reference[["ADT"]] <- CreateAssayObject(counts = P)
reference <- NormalizeData(reference, assay = "ADT", normalization.method = "CLR")
```

Identify CD56 bright NK cells based on protein expression data.

```{r Seurat 2, eval = F}
# generate labels 
lbls = json_data$CellStates$label_list
lbls[lbls != "NK"] = "Unclassified"
CD16 = reference@assays$ADT@counts[rownames(reference@assays$ADT@counts) == "CD16-TotalSeqB-CD16",]
CD56 = reference@assays$ADT@counts[rownames(reference@assays$ADT@counts) == "CD56-TotalSeqB-CD56",]
logik = log2(CD56) > 10 & log2(CD16) < 7.5 & lbls == "NK"; sum(logik)
lbls[logik] = "NK.CD56bright"
```

## SignacX

Generate a training data set from the reference data and save it for later use. Note:

* SignacBoot performs feature selection, bootstrapping, imputation and normalization to derive a training data set from single cell data.

```{r Signac, message = T, eval = F}
# generate bootstrapped single cell data
R_learned = SignacBoot(E = E, spring.dir = data.dir, L = c("NK", "NK.CD56bright"), labels = lbls, logfc.threshold = 1)

# save the training data
save(R_learned, file = "training_NKBright_v207.rda")
```

## Classify a new data set with the model

Load expression data for a different data set (this was also previously processed through SPRING and SignacX)
```{r Seurat Visualization 0, message = F, eval = F}
# Classify another data set with new model
# load new data
new.data.dir = "./PBMCs_5k_10X/FullDataset_v1"
E = CID.LoadData(data.dir = new.data.dir)
# load cell types identified with Signac
json_data = rjson::fromJSON(file=paste0(new.data.dir,'/categorical_coloring_data.json'))
```

Generate new labels. Note:

* Signac trains an ensemble of 100 neural network classifiers using the new training data set built above (R_learned), and then classifies unseen data (E).

```{r Seurat Visualization 1, message = F, eval = F}
# generate new labels
cr_learned = Signac(E = E, R = R_learned, spring.dir = new.data.dir)
```

Now we amend the existing labels (classified previously with SignacX); we add the new labels and generate a new SPRING layout.Note:

* We usually copy the existing SPRING files from "FullDataset_v1" to "FullDataset_v1_Learned" to generate a new layout while preserving the existing layout.

```{r Seurat Visualization 2, message = F, eval = F}
# modify the existing labels
cr = lapply(json_data, function(x) x$label_list)
logik = cr$CellStates == 'NK'
cr$CellStates[logik] = cr_learned[logik]
logik = cr$CellStates_novel == 'NK'
cr$CellStates_novel[logik] = cr_learned[logik]
new.data.dir = paste0(new.data.dir, "_Learned")
```

Save results

```{r Seurat Visualization 3, message = F, eval = F}
# save
dat = CID.writeJSON(cr, spring.dir = new.data.dir, new_colors = c('red'), new_populations = c( 'NK.CD56bright'))
```

<details>
  <summary>**Session Info**</summary>
```{r, echo=FALSE}
sessionInfo()
```
</details>
