Skip to main content

Claude (Anthropic) develops, tests and pushes all code in this repository, and keeps it up to date as its dependencies change.

spaclone

Spatial BCR and TCR analysis, from raw tables to biology, with every position checked against random placement

PyPI version Python versions MIT licence tests

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.

spaclone.pl.hotspot_overview on an AIR-SPACE mouse lymph node, day 21: the switched share (CSR) and the mutated share (SHM) over the node, with the CSR hotspots outlined and numbered

spaclone.pl.hotspot_overview on the StereoIR mouse spleen: switched-share and mutated-share maps with the CSR and SHM hotspots and the numbered regions where they overlap

spaclone.pl.csr_map on the AIR-SPACE lymph node: switched share, dominant switched class and one map per isotype in IgH locus order, arcs for the class switches within clones and the isotype mix of each region

spaclone.pl.csr_map on the StereoIR spleen: switched share, dominant switched class and one map per isotype in IgH locus order, arcs for the class switches within clones and the isotype mix of each region

spaclone.pl.csr_flow on the AIR-SPACE lymph node: sciCSR class-switch potential of every bead, with the transition flow of the chain as streamlines

spaclone.pl.csr_flow on the StereoIR spleen: sciCSR class-switch potential of every bin, with the transition flow of the chain as streamlines

spaclone.pl.region_zoom on the StereoIR spleen: one region where CSR and SHM hotspots overlap, with its isotypes, mutated loci and transcriptome identity

spaclone.pl.lineage_tree on the StereoIR spleen: a germline-rooted lineage tree with every tip joined to its position on the section

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.

Get started

pip install spaclone            # core: reading, QC, trust tests, BCR and TCR analysis, plots
pip install "spaclone[full]"    # + every package in "Integrates" below
import spaclone as spc

report = spc.run(spc.read("section.h5ad", "airr_rearrangement.tsv"))

Cell-type columns and own types are detected when unambiguous (cell_type_key="auto", own_types="auto") and otherwise named in the report.

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, on the same data:

data = spc.read("section.h5ad", "airr_rearrangement.tsv")
hot = spc.bcr.hotspot_workflow(data)                # CSR and SHM hotspots, their overlap regions, GEX identity
spc.pl.hotspot_atlas(hot)                           # the flagship figure
spc.pl.csr_map(hot)                                 # isotypes and class switches along the IgH locus
trees = spc.bcr.lineage_workflow(hot)               # lineage trees with every tip on the tissue
spc.pl.lineage_gallery(trees, "lineages")           # one figure per tree and an index table

Lineage 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 cannot give trees, and bcr.lineage_workflow says so.

What it does

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).

Integrates

Package What spaclone does with it, spatially Install
scanpy · anndata Transcriptome workflow on spots: QC, clusters, regions (germinal centres, ASC foci, 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 Transition kernels on spatial neighbour graphs (tl.transition_model) [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.

Tutorials

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
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
Hotspots and lineages The flagship on a Stereo-seq spleen: trust report, CSR/SHM hotspot atlas, lineage trees, sciCSR flow, Threadfin states
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

Reading data, concepts and the full API: docs.

How to cite

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).

Credits

Chen Satoshi (@Reynold4k) and Claude Opus 5.5 (Anthropic)

Licence

MIT, see LICENSE.

Metadata

Release files for spaclone 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spaclone 1.0.1
File Size Uploaded Provenance Actions
spaclone-1.0.1.tar.gz 1.4 MB With provenance Details for spaclone-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spaclone 1.0.1
File Interpreter ABI Platform Actions
spaclone-1.0.1-py3-none-any.whl Python 3 none any Details for spaclone-1.0.1-py3-none-any.whl

Total release size: 2.3 MB

Release files / spaclone-1.0.1.tar.gz

Download URL spaclone-1.0.1.tar.gz
Size 1.4 MB
Tags Source
SHA-256 checksum
How to use checksums
2c65f43f385ee780efa49642416430e86c8dab24d8a04859ba92d1cc398e2b56
BLAKE2b-256 checksum
How to use checksums
cc872c3b8d65f093a9494bac7c1963ab6a75b381304ada195fa26003ccc3d724
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Release files / spaclone-1.0.1-py3-none-any.whl

Download URL spaclone-1.0.1-py3-none-any.whl
Size 923.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3bc0c94cac6631d48c1d316847eac206a1def2b15726ac9d27ff73ce4dac2442
BLAKE2b-256 checksum
How to use checksums
e3b7811f3263a961b74a7c9f79045affecc27825e18c8ac6c0c71760db902209
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Security for spaclone 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for spaclone-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page