# Sample of interest
sample <- "PT1"Loading the Data and Demultiplexing
Loads Cell Ranger RNA and antibody capture counts into a Seurat object, separating hashtag oligos (HTO) and antibody-derived tags (ADT) into their own assays. Filters empty droplets, normalizes HTO counts with CLR, and uses HTODemux to assign cells to donors and remove doublets and negatives.
hashtag oligos (HTO), antibody-derived tags (ADT), CLR normalization
Approximate time: 60 minutes
Learning objectives
In this lesson, we will:
- Load Cell Ranger RNA and antibody capture counts into a Seurat object
- Separate hashtag (HTO) and protein (ADT) counts into their own assays
- Filter empty droplets and demultiplex pooled samples with
HTODemux() - Remove doublets and negative cells, and assign each cell to its patient
Overview of lesson
When doing XYZ…
Loading the dataset into Seurat
These samples were generated with 10X kits and were therefore processed with their proprietary software. The RNA and protein information is stored in the folder ADT which was processed using the cellranger multi pipeline.
We will be starting with the ADT protein and RNA expression data for sample PT1.
Load counts matrix
First we will load in the counts matrices in the ADT folder with the Read10X() function. When we investigate the two matrices stored, we can see that we have both the “Gene Expression” (RNA) and “Antibody Capture” (ADT) matrices.
# Load raw counts data
counts <- Read10X(file.path("data", sample, "ADT"))
names(counts)[1] "Gene Expression" "Antibody Capture"
Seurat allows you to have Assays() where we can store different matrices for the same cells within a single object. To initialize our Seurat object, let us first use the CreateSeuratObject() function for the RNA expression. Note that we set assay = "RNA", which means that we can use the key “RNA” any time we want to look at the RNA expression over the protein or ATAC values.
# RNA expression matrix
counts_gex <- counts[["Gene Expression"]]
# Create seurat object
seurat <- CreateSeuratObject(
counts = counts_gex,
assay = "RNA",
project = sample)
seuratAn object of class Seurat
36601 features across 726385 samples within 1 assay
Active assay: RNA (36601 features, 0 variable features)
1 layer present: counts
Now we can see that we have created a Seurat object with 726385 cells and 36601 genes within the assay RNA.
Protein expression
Now that we have identified the hashes, we can proceed by adding the protein expression to our Seurat object.
# Protein expression
counts_protein <- counts_adt[!rownames(counts_adt) %in% hashes, ]
seurat[["ADT"]] <- CreateAssayObject(counts = counts_protein)
seuratAn object of class Seurat
36769 features across 726385 samples within 3 assays
Active assay: RNA (36601 features, 0 variable features)
1 layer present: counts
2 other assays present: HTO, ADT
So now we have the RNA, HTO, and ADT assays in our Seurat object. We could also add the ATAC assay, however we will focus on the steps to do so in a future lesson. Now we can proceed with the next step of demultiplexing.
Demultiplexing
In this step we will use the counts for each hashtag in the dataset to map each cell to the patient it belongs to.
# Set default assay to HTO
DefaultAssay(seurat) <- "HTO"When we look at the @meta.data slot of our Seurat object, we can see that there are several QC metrics that are generated by default after adding each Assay(). This includes the total number of counts (UMIs) that each cell has for each modality. These values are an important factor to determine which cells are high quality and which are not.
# Seurat metadata
seurat@meta.data %>% head()Assays()
| orig.ident | nCount_RNA | nFeature_RNA | nCount_HTO | nFeature_HTO | nCount_ADT | nFeature_ADT | |
|---|---|---|---|---|---|---|---|
| AAACAGCCAAACAACA-1 | PT1 | 30 | 29 | 0 | 0 | 0 | 0 |
| AAACAGCCAAACATAG-1 | PT1 | 2 | 2 | 1 | 1 | 1 | 1 |
| AAACAGCCAAACCCTA-1 | PT1 | 9 | 8 | 0 | 0 | 0 | 0 |
| AAACAGCCAAACCTAT-1 | PT1 | 4 | 3 | 0 | 0 | 0 | 0 |
| AAACAGCCAAACCTTG-1 | PT1 | 8 | 7 | 0 | 0 | 0 | 0 |
| AAACAGCCAAACGCGA-1 | PT1 | 186 | 169 | 0 | 0 | 0 | 0 |
Filtration
At this point it is quite evident that we have a lot of low quality cells or empty droplets. To improve the process of demultiplexing and reduce the number of calculations necessary, we want to filter out low-quality cells. First, we can take a look at the number of total HTO counts associated with each cell (nCount_HTO) to remove cells that have too few counts for the antibody to cleanly assign a sample identity.
ggplot(seurat@meta.data) +
geom_histogram(aes(x = nCount_HTO),
fill = "darkred",
bins = 100) +
scale_y_log10() +
scale_x_log10() +
theme_bw() + NoLegend() +
geom_vline(xintercept = 30)The black line is drawn at nCount_HTO = 30 to show the threshold we will be using to remove empty droplets. Following the Methods section of the paper, we will also only keep cells with RNA UMI counts ≥ 500 and ≤ 10,000.
# Filter based on HTO counts
seurat <- subset(seurat, nCount_HTO > 30)
# Filter based on RNA counts
seurat <- subset(seurat, nCount_RNA >= 500)
seurat <- subset(seurat, nCount_RNA <= 10000)
seuratAn object of class Seurat
36769 features across 5991 samples within 3 assays
Active assay: HTO (3 features, 0 variable features)
2 layers present: counts, data
2 other assays present: RNA, ADT
Normalization
At this point, we have the raw counts for the dataset. However some cells may capture more antibodies or be sequenced more deeply, which means that we cannot directly compare these values against each other. We need to normalize first. The method commonly used to normalize HTO counts is a centered log-ratio (CLR) transformation. This method is implemented in Seurat with the NormalizeData function.
For each cell, CLR first calculates the geometric mean of that cell’s hashtag counts, which represents a “typical” hashtag count for the cell. Each hashtag count in the cell is then divided by this geometric mean, and the result is log-transformed. So now each value describes how enriched a hashtag is relative to the other hashtags in that cell, rather than its absolute count. We are able to do this on a per-cell basis by setting the parameter margin = 2 in NormalizeData().
# CLR HTO normalization
seurat <- NormalizeData(
seurat,
assay = "HTO",
normalization.method = "CLR",
margin = 2
)
seuratAn object of class Seurat
36769 features across 5991 samples within 3 assays
Active assay: HTO (3 features, 0 variable features)
2 layers present: counts, data
2 other assays present: RNA, ADT
A cell that truly came from one sample will have one hashtag with a high CLR value and the remaining hashtags close to zero, regardless of how many total hashtag counts that cell had. This makes the sample of origin much easier to identify in the demultiplexing step.
k-medoids demultiplexing
To decide which sample each cell came from, HTODemux() works through a few steps (Seurat hashing vignette):
Group similar cells. Using k-medoids clustering, cells are grouped based on their normalized hashtag values. The function makes one group for each sample, plus one extra group for cells that do not clearly match any sample. Each group is defined by a cell (the medoid) that is used as a representative for that group. Other cells join the group whose representative they look most like.
Background noise. Oftentimes in real data, cells that were not stained with a hashtag will still have low levels of it. To estimate this background noise, the group with the lowest values for each hashtag is treated as the cells that did not receive that hashtag.
Set a cutoff. Using the background counts, the function sets a cutoff value that 99% of the background cells fall below (
positive.quantile = 0.99). A cell above this cutoff is very unlikely to be explained by background noise alone, so it is called positive for that hashtag.Assign each cell. Each cell is then labeled based on how many hashtags it is positive for:
- One hashtag: a singlet, assigned to that sample.
- No hashtags: a negative, typically an empty droplet.
- More than one hashtag: a doublet, where cells from two or more samples were captured in the same droplet.
# HTO demultiplexing
seurat <- HTODemux(
seurat,
assay = "HTO",
positive.quantile = 0.99,
verbose = TRUE)The results of this function call are stored in our @meta.data.
# Seurat metadata (HTODemux columns only)
seurat@meta.data %>%
select(starts_with("HTO_"), hash.ID) %>%
head()HTODemux() to demultiplex pooled cells.
| HTO_maxID | HTO_secondID | HTO_margin | HTO_classification | HTO_classification.global | hash.ID | |
|---|---|---|---|---|---|---|
| AAACAGCCAAACGGGC-1 | hashtag3 | hashtag2 | 0.2025020 | Negative | Negative | Negative |
| AAACAGCCAATATGGA-1 | hashtag3 | hashtag1 | 0.2009672 | Negative | Negative | Negative |
| AAACAGCCAATGAGGT-1 | hashtag2 | hashtag3 | 0.6558958 | hashtag2 | Singlet | hashtag2 |
| AAACAGCCAGCAAATA-1 | hashtag2 | hashtag1 | 1.3719460 | hashtag2 | Singlet | hashtag2 |
| AAACAGCCAGCAAGAT-1 | hashtag1 | hashtag2 | 0.8174715 | hashtag1 | Singlet | hashtag1 |
| AAACAGCCAGTTATCG-1 | hashtag3 | hashtag1 | 1.7683151 | hashtag3 | Singlet | hashtag3 |
HTODemux() added the following columns to gauge how well the demultiplexing step went:
| Column | What it holds |
|---|---|
HTO_maxID |
The hashtag with the highest normalized signal in that cell, whether or not it passed the threshold. |
HTO_secondID |
The hashtag with the second-highest signal. Useful for seeing which two donors a doublet came from. |
HTO_margin |
The difference between the top and second hashtag’s normalized (CLR) values. Large means one hashtag clearly dominates, small means the cell is ambiguous. |
HTO_classification |
The detailed call. A singlet gets one hashtag name (hashtag2), a doublet gets both joined with _ (hashtag1_hashtag3), and a cell with no hashtag above threshold gets Negative. |
HTO_classification.global |
The detailed call collapsed into three groups: Singlet, Doublet or Negative. |
hash.ID |
The final per-cell label. HTODemux also sets the object’s active identities to this. |
From this, we can count how many cells were assigned to each hash.ID:
# Number of cells per demultiplexed hash ID
ggplot(seurat@meta.data) +
geom_bar(aes(x = hash.ID, fill = hash.ID),
color = "black") +
# Add count above bars
geom_text(aes(x = hash.ID, label = after_stat(count)),
stat = "count", vjust = -0.5,
size = 3) +
theme_bw() +
theme(axis.text.x = element_text(angle = 90, vjust = 0.5, hjust = 1))Several of the cells are identified as Negative, meaning that a conclusive label was unable to be determined from the data. These cells are typically empty droplets that contain no cell, but may still contain ambient RNA and a small number of hashtag counts. To evaluate if we truly believe these are low-quality cells to remove, we can assess the nCount_HTO to see how many hash counts are present in those cells. If the levels are very low, we will be unable to identify which patient the cell comes from, and therefore remove them.
# Distribution of HTO counts per demultiplexed hash ID
VlnPlot(seurat,
features = "nCount_HTO",
group.by = "hash.ID",
assay = "HTO",
pt.size = 0) +
scale_y_log10()We can see why the cells that were called Negative received that label from the violin plot. These cells had very low levels of hash expression, making it difficult to confidently map them to a label.
We can also check that each hashtag is only high in the cells that were assigned to it. The RidgePlot() below has one panel per hashtag. Within each panel, every row is a group of cells with the same hash.ID, and the curve shows the distribution of normalized (CLR) values for that hashtag. If a hashtag is high in cells assigned to a different hashtag, it suggests that the demultiplexing calls may not be reliable.
# HTO expression by demultiplexed hash ID
RidgePlot(
seurat,
features = df_hash$hash,
group.by = "hash.ID",
assay = "HTO")In our RidgePlot(), each hashtag is clearly high only in the cells assigned to it, giving us confidence in our demultiplexed calls.
Removing doublets and negatives
Now that we are confident in our demultiplexed calls, we can remove the cells labeled Doublet and Negative. These will only introduce noise into the dataset so we will remove them from our analysis.
# Remove doublets and negatives
seurat_demux <- subset(seurat, subset = (hash.ID %in% df_hash$hash))
seurat_demuxAn object of class Seurat
36769 features across 4823 samples within 3 assays
Active assay: HTO (3 features, 0 variable features)
2 layers present: counts, data
2 other assays present: RNA, ADT
And now we can take the mapping of hash to patient and add it to the metadata of our Seurat object. This way, moving forward, we are able to associate each cell with a specific patient. We will do a left_join() to merge together this information.
# Add patient to metadata by matching hash
meta <- left_join(seurat_demux@meta.data,
df_hash, by = c("hash.ID" = "hash"))
rownames(meta) <- Cells(seurat_demux)
seurat_demux@meta.data <- metaOftentimes when you run left_join() of dataframes, you lose the rownames of the original dataframe. If we were to put this back into the Seurat object without the cell barcodes, we would get many errors in future steps. Hence why we explicitly set the rownames(meta) as a secondary step.
Loading processed seurat object
Now that we understand the basics of how demultiplexing works, we can go back to the full dataset which contains all our samples. To save time and computation, we have generated the merged and demultiplexed seurat object for you to load into your R session.
# Load the processed seurat object
seurat_demux <- readRDS("data/processed_seurat_objects/seurat_demux.RDS")
seurat_demuxAn object of class Seurat
36774 features across 34984 samples within 3 assays
Active assay: RNA (36601 features, 2000 variable features)
3 layers present: counts, data, scale.data
2 other assays present: ADT, HTO
3 dimensional reductions calculated: pca_rna, harmony_rna, umap_rna
For more information on how this object was created, we have created a detailed lesson on how each sample was loaded in an automated fashion with a for loop. The RNA assay was also processed following a standard scRNA-seq workflow.
After merging together each sample, these were the following steps that were performed on the RNA assay:
# Load libraries
library(tidyverse)
library(Seurat)
library(harmony)
### Process RNA
DefaultAssay(seurat) <- "RNA"
seurat <- NormalizeData(seurat)
seurat <- FindVariableFeatures(seurat, nfeatures = 2000)
seurat <- ScaleData(seurat)
seurat <- RunPCA(seurat, npcs = 50, reduction.name = "pca_rna", verbose = FALSE)
seurat <- RunHarmony(seurat, group.by.vars = "orig.ident",
reduction.use = "pca_rna", dims.use = 1:30,
reduction.save = "harmony_rna", verbose = FALSE)
seurat <- RunUMAP(seurat, reduction = "harmony_rna", dims = 1:30,
reduction.name = "umap_rna", reduction.key = "rnaUMAP_",
verbose = FALSE, seed.use = 123456789L)
seurat <- FindNeighbors(seurat, reduction = "harmony_rna", dims = 1:30,
graph.name = c("nn_rna", "snn_rna"))
seurat <- FindClusters(seurat, graph.name = "snn_rna", resolution = 0.8,
algorithm = 4, random.seed = 123456789L)As a starting point to better understand the dataset that we loaded, we can assess how many cells we have per patient.
# Number of cells per patient
ggplot(seurat_demux@meta.data) +
geom_bar(aes(x = patient,
fill = hiv_status),
color = "black") +
geom_text(aes(x = patient,
label = after_stat(count)),
stat = "count", vjust = -0.5,
size = 3) +
theme_bw() +
theme(axis.text.x = element_text(angle = 90, vjust = 0.5, hjust = 1))