Scirpy: Single-cell Adaptive Immune Receptor Repertoire Analysis

Scirpy is a Python package designed for analyzing T cell receptor (TCR) or B cell receptor (BCR) repertoires from single-cell RNA sequencing (scRNA-seq) data.

It is built to integrate seamlessly with the scverse ecosystem, specifically supporting [scanpy] and [mudata]. It provides specialized modules for:

• Data import
• Analysis
• Visualization

Scirpy models immune receptors (IR) using several key biological abstractions:

Chain Types

• VJ chains: Chains assembled from V and J loci only (e.g., TCR-$\alpha$, TCR-$\gamma$, IG-$\kappa$, IG-$\lambda$).
• VDJ chains: Chains assembled from V, D, and J segments (e.g., TCR-$\beta$, TCR-$\delta$, IG-heavy).

Receptor Configurations

• Dual IR: Cells with more than one pair of VJ and VDJ sequences.
• Multichain-cell: Cells with more than two pairs of VJ and VDJ sequences. These are often technical artifacts (cell-multiplets) rather than biological reality.
• Orphan chain: A chain where the counterpart was not detected.

Loci Support

Scirpy supports all valid IMGT locus names, including:

• VJ Loci: TRA, TRG, IGL, IGK.
• VDJ Loci: TRB, TRD, IGH.

Scirpy supports the investigation of both single- and dual-IR (Immune Receptor) cells. Instead of discarding cells with multiple productive CDR3 sequences, Scirpy uses a primary/secondary model:

• Primary pair: The VJ and VDJ chains with the highest read count.
• Secondary pair: The VJ and VDJ chains with the second highest expression level.

Multichain-cells: If a cell has more than two variants of a chain recovered, Scirpy ignores the excess chains and flags the cell as a Multichain-cell. Users can then decide whether to include or discard these flagged cells in their downstream analysis.

Scirpy uses a hierarchical approach to group immune cells based on their receptor sequences:

1. Clonotypes: Defined by cells sharing identical CDR3 nucleotide sequences for both VJ and VDJ chains (e.g., both $\alpha$ and $\beta$ TCR chains).
   • Note: Scirpy can optionally require identical V-genes to enforce CDR1 and CDR2 similarity.
2. Clonotype Clusters: Defined by grouping cells based on their CDR3 amino acid sequences. This includes:
   • Identical CDR3 amino acid sequences.
   • Similar CDR3 amino acid sequences determined via pairwise sequence alignment.

This dual approach allows for both high-fidelity nucleotide-level tracking and broader epitope-focused similarity analysis using amino acid sequences.

You can build the Scirpy documentation locally using several different package managers. The documentation is built using Sphinx and supports Markdown via MyST, NumPy-style docstrings, and Jupyter notebooks via myst-nb.

Using Hatch

hatch run docs:build
hatch run docs:open

Using uv

cd docs
uv run sphinx-build -M html . _build -W
(xdg-)open _build/html/index.html

Using Pip

source .venv/bin/activate
cd docs
sphinx-build -M html . _build -W
(xdg-)open _build/html/index.html

Scirpy is a scverse core package that follows scanpy workflow principles. The API is organized into three main modules:

• scirpy.pp (preprocessing)
• scirpy.tl (tools)
• scirpy.pl (plotting)

All functions operate on anndata.AnnData or mudata.MuData objects. By default, functions modify the object inplace unless inplace=False is specified.

Note that Scirpy plotting functions (e.g., scirpy.pl.clonal_expansion) may call the corresponding tool (e.g., scirpy.tl.clonal_expansion) on-the-fly without storing the results in the object. Plotting functions return a matplotlib.axes.Axes object or a list of them.

import scanpy as sc
import scirpy as ir

To convert your own custom data formats into the Scirpy data structure, the recommended workflow is:

1. Build a list of scirpy.io.AirrCell objects.
2. Convert that list into an AnnData object using scirpy.io.from_airr_cells.

Scirpy is designed to be used alongside Scanpy. For consistency, the Scirpy API follows the Scanpy API patterns closely.

import scanpy as sc
import scirpy as ir

To utilize multiple GPUs, use the joblib Dask backend combined with dask-cuda.

1. Install dependencies:

   pip install "dask[distributed]" dask-cuda

2. Configuration:

   • Set CUDA_VISIBLE_DEVICES to a comma-separated list of GPU IDs (e.g., "0,1").
   • Set n_workers, n_jobs, and n_blocks to match the number of selected GPUs.
   • n_blocks controls the number of outer partitions distributed between workers.

Example:

import joblib
from dask.distributed import Client
from dask_cuda import LocalCUDACluster

with LocalCUDACluster(
    CUDA_VISIBLE_DEVICES="0,1",
    n_workers=2,
    threads_per_worker=1,
) as cluster, Client(cluster):
    with joblib.parallel_config(backend="dask", n_jobs=2):
        ir.pp.ir_dist(
            mdata,
            metric="gpu_hamming",
            n_blocks=2,
        )