scirpy-immune-repertoire

name	scirpy-immune-repertoire
description	Single-cell immune receptor analysis with Scirpy for scanpy, anndata, and scvi-tools projects. Use for TCR/BCR V(D)J import, clonotype definition, clonal expansion, repertoire overlap, immune receptor QC, MuData/AnnData integration, and Scanpy-linked immune repertoire visualization.

Scirpy Immune Repertoire

Use this skill for TCR/BCR repertoire analysis in single-cell immune profiling projects. It complements scanpy, anndata, and scvi-tools by adding immune receptor chains, clonotypes, clonal expansion, and repertoire overlap.

Workflow

1. Load gene expression data with Scanpy.
2. Load V(D)J annotations from 10x or AIRR-like outputs.
3. Merge receptor annotations with expression metadata.
4. Run receptor QC:
   • productive chains
   • chain pairing
   • multichain cells
   • missing receptor calls
5. Define clonotypes using CDR3 sequence, V/J genes, or distance-based criteria.
6. Quantify clonal expansion and repertoire overlap across samples, clusters, tissues, or conditions.
7. Visualize clonotypes on UMAP/spatial embeddings and summarize top clones.

Common API Shape

import scanpy as sc
import scirpy as ir

adata = sc.read_h5ad("gex.h5ad")
vdj = ir.io.read_10x_vdj("filtered_contig_annotations.csv")
ir.pp.merge_with_ir(adata, vdj)
ir.tl.chain_qc(adata)
ir.tl.define_clonotypes(adata)
ir.tl.clonal_expansion(adata)

Checks

• Keep sample IDs and cell barcodes synchronized before merging.
• Decide whether alpha/beta or heavy/light chain pairing is required for the biological question.
• Do not compare raw clonotype counts across samples without accounting for cell recovery and sampling depth.
• Report clonotype definition criteria; conclusions can change substantially with different rules.