Assign cells to their sample of origin from cell or nucleus hashing (CITE-seq HTOs, MULTI-seq lipid/cholesterol tags, CellPlex CMOs) and call cross-sample doublets using Seurat HTODemux/MULTIseqDemux, hashsolo, demuxEM, GMM-Demux, and demuxmix. Use when assigning pooled hashed cells back to their sample, calling cross-sample doublets from HTO counts, choosing a demultiplexing method, deciding between hashtag and genetic demultiplexing, or rescuing an oversized Negative pile from weak HTO staining or ambient spillover.
Assign cells to their sample of origin from cell or nucleus hashing (CITE-seq HTOs, MULTI-seq lipid/cholesterol tags, CellPlex CMOs) and call cross-sample doublets using Seurat HTODemux/MULTIseqDemux, hashsolo, demuxEM, GMM-Demux, and demuxmix. Use when assigning pooled hashed cells back to their sample, calling cross-sample doublets from HTO counts, choosing a demultiplexing method, deciding between hashtag and genetic demultiplexing, or rescuing an oversized Negative pile from weak HTO staining or ambient spillover.
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
Modality
Needs
Cross-sample doublets
Cannot do
Tools
Hashtag/HTO (this skill)
HTO/lipid/CMO library at pooling
Yes (two tags high)
Nothing without a hashing library; sensitive to staining and ambient
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
Method
Model
Use when
Fails when
HTODemux (Seurat)
k-medoids cluster per HTO + negative-distribution quantile
Standard antibody HTO, clean bimodal staining, Seurat workflow
Weak/low-depth staining or heavy ambient; clustering unstable on near-zero HTOs
MULTIseqDemux (Seurat)
Per-HTO KDE, threshold between maxima, quantile sweep
MULTI-seq lipid/cholesterol tags; want autoThresh to optimize the quantile
Few cells; unimodal density when one tag dominates
hashsolo (scanpy/solo)
Bayesian over negative/singlet/doublet
Few hashtags (works at 2), many negatives, scanpy-native pipeline
Very low signal; priors mis-set for the actual doublet rate
demuxEM (pegasus)
EM with background estimated from empty droplets
High ambient; nucleus hashing; raw matrix with empties available
Empty droplets filtered out before calling; very sparse signal
GMM-Demux (CLI)
Gaussian mixture on normalized HTO, explicit MSM multiplets
Want explicit multiplet accounting or experiment planning
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.
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.
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.
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.
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.
Model ambient background explicitly (Python / R)
Goal: Recover correct calls when ambient HTO or weak staining inflates the background.
Approach: demuxEM estimates the background from empty droplets before assigning signal; demuxmix fits a negative-binomial regression mixture using the number of detected genes as a covariate, both of which are more robust than a fixed quantile.
import pegasus as pg
pg.estimate_background_probs(hashing_data)
pg.demultiplex(rna_data, hashing_data, min_signal=10.0)
rna_data.obs['demux_type'].value_counts() # singlet / doublet / unknown
rna_data.obs['assignment'] # sample name per cell
min_signal=10.0 marks cells with too little signal as unknown; lower it to rescue low-capture nucleus hashing, raise it for cleaner singlets. demuxmix's RNA covariate is what makes it robust to per-tag staining differences.
Threshold and parameter reference
Parameter
Default
Rationale and when to change
HTODemux positive.quantile
0.99
Quantile of the negative distribution defining "positive"; raise for stricter calls (more Negatives), lower to rescue weak staining
NormalizeData CLR margin
1 (Seurat default); 2 common for HTO
margin=2 normalizes each tag across cells, correcting per-tag capture bias; pick per the staining and verify
MULTIseqDemux quantile / autoThresh
0.7 / FALSE
autoThresh sweeps the quantile to maximize singlets; use when a fixed threshold over- or under-calls
hashsolo priors
(0.01, 0.8, 0.19)
[negative, singlet, doublet]; the doublet prior should track expected loading doublets (~0.8% per 1000 cells on 10x)
demuxEM min_signal
10.0
Cells below this signal are unknown; lower for low-capture nuclei, raise for cleaner singlets
Common Errors
Symptom
Cause
Fix
Huge Negative pile, few singlets
Weak staining or high ambient inflating background; quantile too strict
Lower positive.quantile / min_signal; switch to demuxEM (empty-droplet background) or demuxmix (RNA covariate)
Cross-sample doublet rate near zero but expression doublets high
Hashing thresholds too loose, or doublet prior too low
Tighten the quantile; raise hashsolo doublet prior; reconcile against the expected loading doublet rate
HTODemux errors on a zero-count cluster
Cells with all-zero HTO counts cluster together
Filter cells with no HTO counts before HTODemux; check the HTO matrix barcodes match the GEX cells
Calls flip with normalization choice
CLR margin=1 vs margin=2 shifts per-tag thresholds
Choose margin deliberately (margin=2 corrects tag-efficiency bias); compare both and inspect ridge plots
Genetic demux cannot split two samples
Both samples are the same donor (identical genotype)
Use hashtag demux; genetic methods cannot separate same-donor samples
Cross-sample doublets present but homotypic doublets remain
Hashing is blind to within-sample doublets
Run expression-doublet detection (single-cell/doublet-detection) in addition
Nucleus hashing yields mostly Negatives
Lower tag capture in nuclei than whole cells
Use demuxEM (designed for nuclei); lower min_signal; expect a larger Negative fraction
Looks clean (low Negatives, low doublets) but nearly all cells are one sample
Staining failure where one tag dominates all cells (mispipetted/over-concentrated antibody, or all samples got the same tag)
Sanity-check the per-tag singlet distribution against the expected pooling; one tag capturing nearly all cells means staining failed even though Negatives look low
One sample silently lost or contaminating while others demultiplex fine
A single antibody failed to stain, so its cells fall into Negative or misassign to the nearest-ambient tag
Check each tag has a non-trivial positive population; one near-zero tag means a failed antibody dropped or misassigned that sample
The rare sample in unequal pooling is under-recovered
Very unequal pooling (e.g. 80/10/10) leaves the minority tag too few positives to form a clean cluster or negative distribution
Inspect per-tag ridge plots; consider demuxmix for the minority tag, whose regression mixture is more stable on small components
Many cells flagged generic "Doublet"
Cells positive for 3+ tags collapsed to one label, hiding over-loading or heavy ambient
Inspect the multiplet tag-count distribution (GMM-Demux MSM); 3+ tags high is a run-quality diagnostic, not an ordinary 2-cell doublet
