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
Every panel above is a spaclone figure on public data: the StereoIR mouse spleen (Stereo-seq) and an AIR-SPACE mouse lymph node (GEO GSE286452), drawn by make_hero.py.
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, on public data: 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 |
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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| spaclone-1.0.0.tar.gz | 1.4 MB | With provenance | Details for spaclone-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spaclone-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for spaclone-1.0.0-py3-none-any.whl |
Total release size: 2.3 MB
Release files / spaclone-1.0.0.tar.gz
| Download URL | spaclone-1.0.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9f487f53655ac86dc6a6900fa157a33c55be79c75e4a3b21a4465f5e1ac18ff0
|
|
BLAKE2b-256 checksum How to use checksums |
a5e92a16f64b3f7dd98b93dcccb8eb4b7ee88eb8801ce6e9feb2232b39d56f6a
|
| 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 30, 2026.
Transparency logRelease files / spaclone-1.0.0-py3-none-any.whl
| Download URL | spaclone-1.0.0-py3-none-any.whl |
|---|---|
| Size | 911.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8b69687e42a9b5b7369400e825ff29c26266a52116814a5ee4271f52d5cd06a5
|
|
BLAKE2b-256 checksum How to use checksums |
a8a7f52f108d990cd5095f9d372fe74c668b5266a2f2abd4433d8f87fb5e5641
|
| 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 30, 2026.
Transparency logSecurity for spaclone 1.0.0
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.
Attestation for spaclone-1.0.0.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 30, 2026.
Transparency logA 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.