Bio Single Cell Hashing Demultiplexing

Version Compatibility

Reference examples tested with: Seurat 5.0+, scanpy 1.10+, pegasus 1.8+, demuxmix 1.4+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• R: packageVersion('<pkg>') then ?function_name to verify parameters

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Hashtag Demultiplexing and Cross-Sample Doublet Calling

"Which sample did each cell come from, and which barcodes are cross-sample doublets?" -> Classify every cell's HTO count vector to the one tag that dominates its background, and flag cells where two tags are both high.

• R: Seurat::HTODemux (antibody HTOs), Seurat::MULTIseqDemux (MULTI-seq lipid tags), demuxmix (regression mixture, robust to bad staining)
• Python: scanpy.external.pp.hashsolo (Bayesian), pegasus.demultiplex / demuxEM (background from empty droplets)
• CLI: GMM-Demux (Gaussian mixture with explicit multiplet accounting)

Governing principle

In cell or nucleus hashing, each sample is labeled before pooling with a unique oligo-tagged reagent: a barcoded antibody (CITE-seq HTO), a lipid- or cholesterol-modified oligo (MULTI-seq), or a CellPlex CMO. A true singlet's HTO count vector is dominated by ONE tag standing well above a background of ambient and spillover counts, so sample assignment reduces to one question per cell: which tag, if any, exceeds that cell's background. Cross-sample doublets fall out directly - two tags both high - which is the decisive advantage of hashing over expression-only doublet detection.

Hashtag demux, genetic demux, and expression-doublet detection answer three DIFFERENT questions and should be combined, not substituted. Hashtag and genetic demux both assign samples and catch cross-sample doublets, but expression-doublet detection (single-cell/doublet-detection) catches within-sample and homotypic doublets that hashing and genetics are blind to, because two cells from the same sample carry the same tag and the same genotype. Conversely, expression methods miss cross-sample doublets when the two samples are transcriptionally similar. The cross-sample doublet rate also calibrates the expected TOTAL doublet rate: with two pooled samples within- and cross-sample doublets are equally frequent, while with k samples cross-sample doublets dominate and within-sample ones fall to about 1/k of all doublets, so hashing still misses that within-sample fraction (expression-doublet detection stays necessary) and a hashing doublet rate far below the expression-doublet rate is a red flag that staining or thresholds are off.

The hard part is the background, not the dominant tag. Ambient HTO from lysed cells, spillover between tags, staining failure, and batch differences in tag-capture efficiency all inflate the background and grow the "Negative" pile (real cells whose true tag never cleared background, distinct from true empty droplets removed upstream). Nucleus hashing is harder than whole-cell because tag capture is lower. Methods differ mainly in how they model that background.

Choosing a demultiplexing modality

Genetic demux is the fallback when no hashing was done but samples come from different donors; it cannot resolve multiple samples from one donor, which hashing can. Pair whichever sample-assignment method applies with expression-doublet detection for the doublets it cannot see.

Choosing a hashtag caller

The EM and regression methods (demuxEM, demuxmix) model the background explicitly and are the robust choice when staining is marginal, and they handle a two-tag pool as readily as a many-tag one (their failure mode is too few cells per mixture component, not too few tags), so weak staining even at two tags routes to demuxmix or demuxEM rather than hashsolo; HTODemux and MULTIseqDemux are fast defaults for clean data; hashsolo handles few hashes and many negatives. When callers disagree, run a consensus (cellhashR wraps several callers) and verify current best practice against installed docs before trusting any single call.

Normalize HTO counts before calling

Goal: Put HTO counts on a scale where the dominant tag separates from background.

Approach: Apply the centered log-ratio (CLR) transform to the HTO assay. CLR margin=1 normalizes the tags within each cell and is the Seurat default that the canonical HTO vignette uses; margin=2 normalizes each tag across cells and is a common alternative for HTO/ADT because it corrects per-tag capture-efficiency differences. Choose deliberately and compare both rather than blindly accepting the default.

library(Seurat)

hto <- CreateSeuratObject(counts = gex_counts)
hto[['HTO']] <- CreateAssay5Object(counts = hto_counts)
hto <- NormalizeData(hto, assay = 'HTO', normalization.method = 'CLR', margin = 2)

Classify samples and doublets with HTODemux (R)

Goal: Assign each cell to a single HTO or label it a cross-sample doublet or Negative.

Approach: Cluster cells per HTO, model the low-count (negative) cluster, and call a cell positive for any tag whose count exceeds the positive.quantile of that negative distribution; one positive is a singlet, two or more a doublet, none a Negative.

hto <- HTODemux(hto, assay = 'HTO', positive.quantile = 0.99)

table(hto$HTO_classification.global)        # Singlet / Doublet / Negative
table(hto$hash.ID)                          # per-sample singlet counts + Doublet + Negative
singlets <- subset(hto, subset = HTO_classification.global == 'Singlet')

positive.quantile = 0.99 is the quantile of the inferred negative distribution above which a cell counts as positive; raise it to be stricter (fewer false singlets, more Negatives), lower it to rescue cells when staining is weak. HTO_classification.global holds Singlet/Doublet/Negative; hash.ID holds the sample name (or Doublet/Negative) and becomes the active identity.

Demultiplex MULTI-seq tags with MULTIseqDemux (R)

Goal: Classify MULTI-seq lipid/cholesterol-tagged samples, optimizing the threshold automatically.

Approach: For each tag, find the threshold between the two density maxima; with autoThresh=TRUE, sweep the quantile over qrange to maximize the number of singlets.

hto <- MULTIseqDemux(hto, assay = 'HTO', autoThresh = TRUE)
table(hto$MULTI_ID)                          # sample / Doublet / Negative

MULTI_ID carries the per-cell call. Use a fixed quantile = 0.7 instead of autoThresh only when the automated sweep over- or under-calls on a particular dataset.

Demultiplex in scanpy with hashsolo (Python)

Goal: Bayesian sample assignment that behaves with few hashtags and many negatives.

Approach: Place raw HTO counts as columns in adata.obs, then run hashsolo with priors over the negative, singlet, and doublet hypotheses; the doublet prior should track the expected loading doublet rate.

import scanpy as sc
import scanpy.external as sce

hto_cols = ['HTO_A', 'HTO_B', 'HTO_C', 'HTO_D']
adata.obs[hto_cols] = hto_counts_df[hto_cols]
sce.pp.hashsolo(adata, cell_hashing_columns=hto_cols, priors=(0.01, 0.8, 0.19))

adata.obs['Classification'].value_counts()   # barcode name / 'Negative' / 'Doublet'
singlets = adata[~adata.obs['Classification'].isin(['Negative', 'Doublet'])].copy()

priors are ordered [negative, singlet, doublet]; raise the doublet prior for higher loading. Output columns include Classification, most_likely_hypothesis, and the per-hypothesis probabilities.