Spatial BCR and TCR analysis, from raw tables to biology, with every position checked against random placement
Each figure below is the spaclone function named in its header, on an AIR-SPACE mouse lymph node (public, GEO GSE286452) and, as a showcase, the StereoIR mouse spleen (Stereo-seq, BGI; data not yet public), drawn by make_homepage.py.
Every other figure, with the code that draws it, is in the tutorials.
Spatial immune-repertoire analysis is young. The closest public work (October 2026):
- Stereo-XCR-seq analysis code (Zhan et al., Nat Commun 2026, doi): Stereo-seq BCR maps, a Gi* SHM hotspot map and per-cell class switching.
- AIR-SPACE (Jiang et al., PNAS 2026, doi): bead-level BCR maps, regional SHM and IgPhyML trees with tips on beads.
- Spatial VDJ (Engblom et al., Science 2023): Visium BCR/TCR, isotype regions, putative class-switch events and trees split by follicle.
- BAITS (2026): a Python package for per-location QC, clone families and B-cell aggregates.
- McEnany, Good & Cvijović (bioRxiv 2025, doi): lineage trees with follicle-labelled tips and a migration model.
- Platypus had a Visium spatial module in 2022 (isotype and SHM on the image, lineage arrows); it was removed in version 3.6.0.
- Single-cell building blocks: sciCSR and Dowser (class-switch models and tests on trees), scirpy, Dandelion and Immcantation.
spaclone adds the following, and the public record shows none of it elsewhere:
- location-trust tests against depth-matched random placement;
- CSR and SHM hotspots with family-wise thresholds and clone-level nulls, and tested overlap regions with their transcriptome identity;
- class-switch potential, transitions and fluxes on spatial graphs;
- Threadfin clone states on tissue;
- one package across sequencing technologies.
pip install spaclone # core: reading, QC, trust tests, BCR and TCR analysis, plots
pip install "spaclone[datasets]" # + the downloader of the public example data used below
pip install "spaclone[full]" # + every package in "Integrates" below (the downloader included)Or with conda, from Bioconda:
conda install -c conda-forge -c bioconda spaclone # the core; the extras come from pip in the same environmentimport spaclone as spc
# a public AIR-SPACE lymph node, day 21 (GEO GSE286452): 78 MB, downloaded once and checked by sha256
data = spc.read(*spc.datasets.airspace("D21")) # your own section: spc.read("section.h5ad", "airr.tsv")
report = spc.run(data)
print(report.verdict)Cell-type columns and own types are detected when unambiguous (cell_type_key="auto", own_types="auto") and
otherwise named in the report. From the shell, spaclone run writes the same report
(command line).
spc.read recognises both files from their contents: the transcriptome (h5ad from scanpy, squidpy or Stereopy, Space
Ranger Visium SD / HD, Stereo-seq GEF / GEM, Xenium, Slide-seq, SpatialData) and the receptor table (AIRR from Cell
Ranger, TRUST4, IgBLAST / Change-O, MiXCR, scirpy or Dandelion; 10x contigs; MiXCR 3 / 4; TRUST4 reports; Change-O;
Dandelion; scirpy). Other tables (immunoSEQ, BD, Parse, VDJtools, immunarch …) read with a column mapping;
spc.io.sniff(path) shows what was detected. spc.run filters the records and runs every location-trust test the
data allow:
| You get back | |
|---|---|
report.verdict |
Can clone positions be trusted? With report.verdict_molecule and report.verdict_clone, one per level |
report.tests() |
One row per test and locus: observed, chance, ratio, p, BH q, verdict |
report.plot() |
The one-page trust report |
report.methods() |
A methods paragraph with every parameter and reference |
Then the biology. Class switching and hypermutation, on the same AIR-SPACE node:
hot = spc.bcr.hotspot_workflow(data) # CSR and SHM hotspots, their regions, GEX identity
spc.pl.hotspot_atlas(hot) # the flagship figure
spc.pl.csr_map(hot) # isotypes and class switches along the IgH locusLineage trees need each record's contig and its V alignment (the AIRR fields sequence, v_sequence_alignment,
v_germline_alignment and v_germline_start, as IgBLAST (-outfmt 19) and TRUST4 write them). Clone tables without
sequences, such as AIR-SPACE's, cannot give trees, and bcr.lineage_workflow says so. A synthetic section has them,
with lineages planted to check the trees against:
# synthetic section (simulated, no download): contigs with V alignments and planted B-cell lineages
syn = spc.datasets.synthetic_example(sequences=True)
trees = spc.bcr.lineage_workflow(syn) # lineage trees with every tip on the section
spc.pl.lineage_gallery(trees, "lineages") # one figure per tree and an index table
spc.sim.score_lineages(trees, syn) # each tree against the planted one| Read anything Spatial transcriptome and receptor files, detected automatically |
Trust first Molecule- and clone-level tests against random placement that keeps local Ig RNA depth |
Class switching and hypermutation Switched- and mutated-share maps with family-wise hotspots |
| Hotspot atlas Where CSR and SHM hotspots overlap, and the transcriptome identity of each region |
CSR dynamics sciCSR's CSR potential, transition models and fluxes, on tissue |
Lineages Germline-rooted trees with every tip on the section |
| Repertoire in space Expansion, diversity, overlap, networks and public clonotypes by region |
Where clones gather Calibrated clonal scans, niche profiles and clone states |
Your own test Any statistic against random placement with nulls.placebo |
Every statistic reproduces the numbers of the analyses it came from (AIR-SPACE and Stereo-XCR-seq LUAD, public; StereoIR, BGI data not yet public): of 4,001 recorded values, 3,302 are equal, 310 agree within Monte-Carlo tolerance, 17 have no archived value, 7 differ for documented reasons and 365 are new or informational (validation).
| Package | What spaclone does with it, spatially | Install |
|---|---|---|
| scanpy · anndata | Transcriptome workflow on spots: QC, clusters, regions (germinal centres, areas of antibody-secreting cells (ASC: plasmablasts and plasma cells), T zones), DE with regions as replicates; one container for spots and receptor records | core |
| squidpy | Neighbourhood enrichment, co-occurrence and spatial autocorrelation of receptor-derived labels (ext.squidpy) |
[squidpy] |
| scirpy | Clonotypes, expansion, diversity, overlap and V(D)J usage per spatial unit, mapped back to tissue (ext.scirpy) |
[scirpy] |
| SpatialData | SpatialData in and out: records as points, spots as shapes (io.to_spatialdata) |
[spatialdata] |
| Dandelion | Clone calls written back to records and loci, and compared with spaclone's (ext.dandelion) |
[dandelion] |
| Immcantation: IgBLAST · Change-O · SHazaM · dowser · IgPhyML | Germlines, mutation counts and lineage trees that keep their tissue positions (ext.immcantation) |
[immcantation] + IgBLAST, R |
| sciCSR | CSR potential, SHM score, transition models and transition-path fluxes on tissue (bcr.csr_potential, tl.tpt_flux, pl.csr_flow), and a bridge to the R package (ext.scicsr; 103 of 103 parity checks match sciCSR 0.3.5) |
[scicsr] |
| CellRank · deeptime | CellRank's transition kernels on spatial neighbour graphs (tl.transition_model), deeptime's transition path theory (tl.tpt_flux) |
[scicsr] |
| Threadfin | Clone-state landscapes on spots and loci, with calibrated spatial readouts (ext.threadfin) |
[threadfin] |
| OLGA | Generation probabilities of public TCR clonotypes (tl.public) |
[tcr] |
spc.check_install() shows which of these work on your machine and the command that enables each missing one.
| Quick start | One call on data with and without real positions |
| Is my data spatial? | AIR-SPACE against Stereo-XCR-seq LUAD; a published QC metric under placebo. Needs the LUAD chip, downloaded by hand (below) |
| Class switching and mutation | CSR maps and hotspots, SHM, lineages in germinal centres |
| Transcriptome and repertoire | GEX workflow, regions, DE, diversity, networks, niches |
| Your own placebo | Test any statistic against random placement. Needs the LUAD chip, downloaded by hand (below) |
| Hotspots and lineages | Showcase: the flagship on a Stereo-seq spleen (trust report, CSR/SHM hotspot atlas, lineage trees, sciCSR flow, Threadfin states). BGI data, not yet public: the notebook cannot be re-run until they are released; tutorial 08 runs the same functions on data anyone can get |
| AIR-SPACE time course | Every analysis on all six public AIR-SPACE lymph nodes, Mock to day 21, with the package defaults and one table of the key numbers |
| Lineages, zooms and clone states | Lineage trees on a synthetic section with planted lineages, checked against the truth; a region zoom, the sciCSR stationary distribution and Threadfin clone-axis profiles and spanning clones on a public AIR-SPACE node |
| Interactive figures | The explorer on all six AIR-SPACE lymph nodes in one HTML file (sample switcher, gene picker, clone search, region counts), and the interactive form of the other figures |
Running them needs Jupyter and the extras each notebook names in its first cell (pip install "spaclone[full]" jupyter covers all).
Tutorials 02 and 05 also need one file that is not downloaded for you: the Stereo-XCR-seq LUAD chip GSM9684211_D06047A2.h5ad
(0.98 GB; GEO sample GSM9684211, series GSE328481, download):
put it next to the notebook or set the environment variable SPACLONE_LUAD_H5AD to its path.
Reading data, the command line, concepts and the full API: docs.
The spatial figures and the main other ones also come as one HTML file with their data inside: it opens offline in a browser, can be e-mailed, and is what a notebook shows inline. Zoom into a region, switch sample or layer, pick a gene, search clones, and count what a box or a free shape holds.
spaclone.pl.explore(sections, hotspots=hot).save("explorer.html") # sections = {"Mock": sa_mock, ..., "D21": sa_d21}
spaclone.pl.interactive.hotspot_atlas(hot) # the interactive form of pl.hotspot_atlasNo kernel, server, WebGL or extra package is involved; where a notebook viewer does not run scripts (an untrusted notebook, a PDF export), it shows the figure's picture. Where they work, their limits and which functions have an interactive form: docs/interactive.md.
Please cite spaclone as in CITATION.cff (GitHub: "Cite this repository") and also cite the packages you use through it; docs/citing.md lists which function uses which package. spaclone is MIT-licensed; optional packages and programs keep their own licences (install).
Chen Zhu (@Reynold4k) and Claude Opus 5.5 (Anthropic)
MIT, see LICENSE.








