Loading the Data and Demultiplexing

Demultiplexing
Quality control
Seurat
Protein (HTO/ADT)

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.

Author

Noor Sohail

Published

October 27, 2026

Keywords

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.

# Sample of interest
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)

seurat
An 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.

Hashtags

Some runs are comprised of multiple, pooled samples that are tagged with specific antibodies called hashtags. The way to identify which sample a cell comes from is to use these hashtag sequences to demultiplex the cells. The hashtag counts are stored in the “Antibody Capture” matrix, alongside the protein (ADT) counts.

# Protein expression matrix (ADT and HTO)
counts_adt <- counts[["Antibody Capture"]]

The rownames of this matrix are the names of the proteins and hashtags, which we can see by looking at the first few entries:

# View first few protein names
rownames(counts_adt) %>% head()
[1] "GPR56_TotalA"              "ArmenianHamsterIgG_TotalA"
[3] "CD13_TotalA"               "CD57_Recombinant_TotalA"  
[5] "CD272_TotalA"              "CD88_TotalA"              

All the proteins have the string _TotalA appended, so we are going to remove it for easy searching now and in the future. Once we accomplish that, we can find the hashtags by searching for any name that contains the string hashtag.

# Remove appended _TotalA string from protein names
rownames(counts_adt) <- str_replace_all(rownames(counts_adt), "_TotalA", "")

# Looking for hashes in the dataset
hashes <- rownames(counts_adt)[str_detect(rownames(counts_adt), "hashtag")]
hashes
[1] "hashtag1" "hashtag2" "hashtag3" "hashtag4" "hashtag5" "hashtag6" "hashtag7"
[8] "hashtag8"

Next, we need to know which hashtag corresponds to which patient. Any time you are designing an experiment that requires pooling, it is very important to keep track of this information. For this dataset, we have a file titled hashing_info.txt.gz for each pooled sample that maps each hashtag to a patient.

# Map of hash to patient
df_hash <- read.csv(file.path("data",
                              sample,
                              "ADT", "hashing_info.txt.gz"),
                    header = FALSE, sep = ":",
                    col.names = c("hash", "patient")) %>%
  # data wrangling
  mutate(hash = str_replace(hash, "H", "h"),
         hash = str_replace(hash, " ", ""))
df_hash
Table 1: Table of hashing information for each patient.
hash patient
hashtag1 35
hashtag2 37
hashtag3 40
More hashes than expected

The hashing table (df_hash) shows that only 3 hashtags were used to label the patients in PT1, but our matrix contains 8 hashtags (hashes). This is because the sequences for all 8 hashtags were included in the reference used by Cell Ranger, even though only 3 of them were used on these cells. The unused hashtags should only have background counts and will not affect the results.

To keep only the relevant hashtags, we will subset the counts matrix to the 3 hashtags listed in df_hash$hash in the next step.

Now that we know which hashtags were used, we can pull those antibody captures out and store them as HTO in our Seurat object with the CreateAssayObject() function.

# Grab counts for just the hashes used in this sample
counts_hash <- counts_adt[df_hash$hash, ]

# Add HTO assay to our seurat object
seurat[["HTO"]] <- CreateAssayObject(counts = counts_hash)
seurat
An object of class Seurat 
36604 features across 726385 samples within 2 assays 
Active assay: RNA (36601 features, 0 variable features)
 1 layer present: counts
 1 other assay present: HTO

To confirm that we added the HTO assay successfully, we can check that there are 3 Features() in the assay, which should correspond to each of the hashes.

# Name of features in the HTO assay
Features(seurat[["HTO"]])
[1] "hashtag1" "hashtag2" "hashtag3"

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)

seurat
An 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()
Table 2: Metadata generated by default after adding 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)
Figure 1: Histogram of hash counts per cell.

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)
seurat
An 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
  )
seurat
An 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):

  1. 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.

  2. 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.

  3. 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.

  4. 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()
Table 3: Metadata after running 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))
Figure 2: Number of cells per demultiplexed hash ID.

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()
Figure 3: Distribution of hash counts, grouped by demultiplexed hash IDs.

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")
Figure 4: Ridge plot of HTO normalized expression for each hash.

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_demux
An 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 <- meta

Oftentimes 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_demux
An 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))
Figure 5: Number of cells per patient in the full dataset.

Next Lesson >>

Back to Schedule

Reuse

CC-BY-4.0