Bio Single Cell Doublet Detection

Version Compatibility

Reference examples tested with: scanpy 1.10+, scDblFinder 1.16+, Seurat 5.0+

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.

Doublet Detection

"Remove doublets from my data" -> Flag droplets that captured two or more cells, which masquerade as fake intermediate cell states.

• Python: sc.pp.scrublet() per sample on raw counts
• R: scDblFinder(sce, samples=...) per sample on raw counts

Governing Principle

Doublets fabricate fake biology, so the goal is not a "doublet-free" dataset but avoiding false conclusions. Three facts govern every decision.

Doublets create fake intermediate populations. A heterotypic doublet (two distinct types, e.g. T cell + monocyte) sums to a profile that lands between clusters and reads as a novel "transitional" state - the most damaging failure mode, because it corrupts trajectory inference and RNA velocity by building false bridges between lineages. Treat any small cluster co-expressing two lineage programs (CD3+LYZ, EPCAM+PTPRC) as doublet-suspect until proven otherwise.

Detect per sample, before integration or clustering. A doublet is a physical event within one droplet in one capture, so two cells from different samples can never share one - any cross-sample doublet called on a merged object is meaningless. Merging also corrupts the kNN/PCA neighborhood that scoring depends on. scDblFinder's samples= handles this internally; Scrublet and DoubletFinder must be looped per sample. All three want raw counts after basic QC.

Removal is never complete, and over-removal deletes real cells. Homotypic doublets (two cells of the same type) sum to a profile that looks like one bigger cell of that type and are nearly invisible to any expression-based method, so reported "doublet rates" only cover the heterotypic-detectable fraction. Conversely, doublet scores correlate with total counts, the same axis as count-based QC, so aggressive filtering on both double-penalizes and strips genuine high-RNA populations (megakaryocytes, plasma cells, large neurons). Coordinate the two filters and prefer flag-and-inspect over blind deletion.

Expected Doublet Rate

10X Chromium loading is near-Poisson, so the multiplet rate scales roughly linearly with recovered cells: ~0.8% per 1,000 cells recovered (dbr.per1k = 0.008).

Rule: rate ~= 0.008 x recovered/1000. Always set the expected rate from the actual recovered-cell count of that lane; Scrublet's flat expected_doublet_rate=0.05 is a placeholder, not a recommendation. High-throughput chips have lower per-cell rates. For multiplexed pools (genotype/HTO-demultiplexed), the physical doublet rate is set by TOTAL lane loading, not the demultiplexed subset: deriving the rate from one sample's cells underestimates it (four 5k samples in one 20k lane is ~15% real, not the ~3.9% implied by 5k), so set the rate from the total lane cell count.

Heterotypic, Homotypic, Neotypic

modelHomotypic-style adjustments only change the number expected to be detectable; they cannot recover undetectable homotypic doublets.

Choosing a Method

scDblFinder is the 2024-2026 best-balance default and is recommended by sc-best-practices. The older Xi and Li 2021 ranking ("DoubletFinder is most accurate") predates major scDblFinder improvements and is superseded - do not cite it against current scDblFinder. Methods compete and drift; verify current standing against the installed tool's docs before committing.

scDblFinder (R, recommended)

Goal: Call doublets with a fast gradient-boosted classifier, per sample, with the rate inferred from cell count.

Approach: Convert to SingleCellExperiment, pass the per-sample key so each capture is processed independently, then read the class/score back.

library(scDblFinder)
library(SingleCellExperiment)

sce <- as.SingleCellExperiment(seurat_obj)                 # or build directly from a counts matrix
sce <- scDblFinder(sce, samples = 'sample_id')             # per-capture; dbr defaults from cell count via dbr.per1k=0.008
table(sce$scDblFinder.class)                               # adds scDblFinder.class ('singlet'/'doublet') and .score
seurat_obj$scDblFinder_class <- sce$scDblFinder.class
seurat_obj$scDblFinder_score <- sce$scDblFinder.score

clusters=NULL (default) generates purely random artificial doublets and is generally recommended; pass a vector for cluster-based generation. dbr=NULL computes the rate from cell count; set dbr/dbr.sd explicitly to encode a known loading.

Scrublet (Python)

Goal: Score doublets in a scanpy pipeline, per sample, with the rate set from recovered cells.

Approach: Use the maintained sc.pp.scrublet path on raw counts; set expected_doublet_rate per lane; inspect the histogram when the auto-threshold looks wrong.

import scanpy as sc

n_cells = adata.n_obs
expected_rate = 0.008 * n_cells / 1000                     # from recovered cells, not the 0.05 placeholder
sc.pp.scrublet(adata, expected_doublet_rate=expected_rate)  # adds obs['doublet_score'], obs['predicted_doublet']
# auto-threshold needs a bimodal histogram; if unimodal, inspect uns['scrublet'] and set threshold manually
adata_singlets = adata[~adata.obs['predicted_doublet']].copy()

For pooled samples, loop sc.pp.scrublet(adata[adata.obs.sample == s], ...) per sample (or pass batch_key), never on the merged object.