Doublet detection - Single-cell best practices

Steps

yml

Install conda:
- Before creating the environment, ensure that conda is installed on your system.
Save the yml content:
- Copy the content from the yml tab into a file named environment.yml.
Create the environment:
- Open a terminal or command prompt.
- Run the following command:
```
conda env create -f environment.yml
```
Activate the environment:
- After the environment is created, activate it using:
```
conda activate <environment_name>
```
- Replace <environment_name> with the name specified in the environment.yml file. In the yml file it will look like this:
```
name: <environment_name>
```
Verify the installation:
- Check that the environment was created successfully by running:
```
conda env list
```

surface_protein.yml

name: surface-protein
channels:
  - conda-forge
dependencies:
  - python=3.13
  - scanpy=1.12
  - muon=0.1.9
  - python-igraph=1.0.0
  - ipykernel=7.2.0
  - pip==26.0.1
  - pip:
      - lamindb==2.3.1
      - harmonypy==0.0.9
      - ipywidgets==8.1.8

This book uses lamindb to store, share, and load datasets and notebooks using the theislab/sc-best-practices instance. We acknowledge free hosting from Lamin Labs.

Install lamindb
- Install the lamindb Python package:
```
pip install lamindb
```
Optionally create a lamin account
- Sign up and log in following the instructions
Verify your setup
- Run the lamin connect command:
```
import lamindb as ln

ln.Artifact.connect("theislab/sc-best-practices").df()
```
You should now see up to 100 of the stored datasets.
Accessing datasets (Artifacts)
- Search for the datasets on the Artifacts page
- Load an Artifact and the corresponding object:
```
import lamindb as ln
af = ln.Artifact.connect("theislab/sc-best-practices").get(key="key_of_dataset", is_latest=True)
obj = af.load()
```
The object is now accessible in memory and is ready for analysis. Adapt the lamindb.Artifact.connect("theislab/sc-best-practices").get("SOMEIDXXXX") suffix to get respective versions.
Accessing notebooks (Transforms)
- Search for the notebook on the Transforms page
- Load the notebook:
```
lamin load <notebook url>
```
which will download the notebook to the current working directory. Analogously to Artifacts, you can adapt the suffix ID to get older versions.

Motivation¶

In the Quality Control chapter, we removed cells that potentially reflect doublets based only on their high count content. We also filtered cells based on sample-wise distribution. Now, we will focus on heterotypic doublets, that is, doublets that contain cells from different cell types. With ADT data, we can detect them using cell type specific surface markersSun et al., 2021.

Environment setup¶

import warnings

import scanpy as sc

warnings.filterwarnings("ignore")
sc.settings.verbosity = 0
sc.set_figure_params(
    dpi=80,
    facecolor="white",
    frameon=False,
)

import lamindb as ln

ln.track()

→ connected lamindb: theislab/sc-best-practices
→ found notebook doublet_detection.ipynb, making new version -- anticipating changes
→ created Transform('xo1WtNUmrJCK0007', key='doublet_detection.ipynb'), re-started Run('33z2HhX1JxiWbGxS') at 2026-07-29 11:07:33 UTC
→ notebook imports: lamindb-core==2.3.1 muon==0.1.9 scanpy==1.12.3
• recommendation: to identify the notebook across renames, pass the uid: ln.track("xo1WtNUmrJCK")

Loading the data¶

We load the MuData object we saved at the end of the previous chapter, Normalization:

af = ln.Artifact.connect("theislab/sc-best-practices").get(
    key="surface-protein/cite_normalization.h5mu", is_latest=True
)
mdata = af.load()
mdata

Doublets detected with cell type markers¶

We are now going to look at cell type markers that are mutually exclusive. An example is CD3 (T cell marker) vs CD19 (B cell marker) to identify T/B cells doublets. As cells expressing both specific B and T cell markers do not exist under physiological conditions, those droplets contain T/B cell doublets.

The same is true for cells expressing both T cell (CD3) and monocyte (CD14) markers.

sc.pl.scatter(mdata["prot"], x="CD3", y="CD19-1", color="log1p_total_counts")

In this plot, we can see a large number of cells not expressing T or B cell markers in the lower left, cells expressing only one marker in the upper left and lower right as well as some cells expressing both markers (upper right).

The cells expressing both markers are doublets and can be removed.

We can also use CD3 and CD14 to detect T/monocyte doublets.

sc.pl.scatter(mdata["prot"], x="CD3", y="CD14-1", color="log1p_total_counts")

It looks like cells that have an expression level above 25 in both markers are doublets. We use an expression level above 25 in both markers to flag doublets.

genes2filter = ["CD3", "CD19-1", "CD14-1"]
temp = mdata["prot"][:, genes2filter].X.T.tolist()

mdata["prot"].obs["doublets_markers"] = [
    (temp[0][i] > 25 and temp[1][i] > 25) or (temp[0][i] > 25 and temp[2][i] > 25)
    for i in range(mdata.shape[0])
]
mdata["prot"].obs["doublets_markers"] = (
    mdata["prot"].obs["doublets_markers"].astype(str)
)

Doublets usually have a higher count due to the presence of increased counts from more than one cell. We can see this effect in the cells classified as doublets using our markers:

sc.pl.violin(mdata["prot"], keys="log1p_total_counts", groupby="doublets_markers")

We leave out cells expressing both markers.

mdata = mdata[mdata["prot"].obs["doublets_markers"] == "False"].copy()
mdata

We removed 608 doublets from the data.

In this chapter, we removed doublets using the ADT data by removing cells that highly expressed two mutually exclusive markers. Another option to remove doublets would be utilizing methods that detect doublets based on the scRNA-seq data. For those methods, we refer to the Doublet Detection chapter of scRNA-seq preprocessing and visualization.

af_doublet_detection = ln.Artifact.from_mudata(
    mdata,
    key="surface-protein/cite_doublet_detection.h5mu",
    description="CITE-seq data after doublet detection",
)
af_doublet_detection.save()

→ returning artifact with same hash: Artifact(uid='I1sQCEySclEA4f2N0005', key='surface-protein/cite_doublet_detection.h5mu', description='CITE-seq data after doublet detection', suffix='.h5mu', kind='dataset', otype='MuData', size=1452761836, hash='FhXN0hS1nI7WfLBybIFE9g', n_files=None, n_observations=105907, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=112, schema_id=None, created_by_id=7, created_at=2026-07-29 11:07:15 UTC, is_locked=False, version_tag=None, is_latest=True); to track this artifact as an input, use: ln.Artifact.get()
... uploading tu0VvP9QqQazgAiZ0000.h5mu: 100.0%
• replacing the existing cache path /var/cache/user/marchena/.cache/lamindb/lamin-eu-central-1/VPwcjx3CDAa2/surface-protein/cite_doublet_detection.h5mu

Artifact(uid='I1sQCEySclEA4f2N0005', key='surface-protein/cite_doublet_detection.h5mu', description='CITE-seq data after doublet detection', suffix='.h5mu', kind='dataset', otype='MuData', size=1452761836, hash='FhXN0hS1nI7WfLBybIFE9g', n_files=None, n_observations=105907, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=112, schema_id=None, created_by_id=7, created_at=2026-07-29 11:07:15 UTC, is_locked=False, version_tag=None, is_latest=True)

ln.finish()

• please hit CTRL + s to save the notebook in your editor ... ✓
→ finished Run('33z2HhX1JxiWbGxS') after 27s at 2026-07-29 11:08:00 UTC
→ go to: https://lamin.ai/theislab/sc-best-practices/transform/xo1WtNUmrJCK0007
→ to update your notebook from the CLI, run: lamin save /groups/nils/members/javier/single-cell-best-practices/jupyter-book/surface_protein/doublet_detection.ipynb

Contributors¶

We gratefully acknowledge the contributions of:

Authors¶

Javier Marchena-Hurtado
Daniel Strobl
Ciro Ramírez-Suástegui

Reviewers¶

Lukas Heumos
Anna Schaar

References¶

Sun, B., Bugarin-Estrada, E., Overend, L. E., Walker, C. E., Tucci, F. A., & Bashford-Rogers, R. J. M. (2021). Double-jeopardy: scRNA-seq doublet/multiplet detection using multi-omic profiling. Cell Reports Methods, 1(1), 100008. 10.1016/j.crmeth.2021.100008