Phylospatial optimal transport for single-cell and spatial transcriptomics data integration. SpOTr maps dissociated cancer cells to the spots of spatial transcriptomics data, using the concordance between the evolutionary tree of the cells and their spatial distribution. It combines the spot deconvolution model of cell2location with Fused Gromov–Wasserstein optimal transport: the tree draws related cells to nearby spots, and the deconvolution determines how many cancer cells each spot holds. SpOTr recovers the spatial locations of clones that are hard to distinguish by their expression, places sub-lineages that no reference signature describes, and draws the phylogeny of a tumor in the tissue. When no tree is available, it can use clone labels alone.
Installation
pip install phylospatial-spotr
The package is named phylospatial-spotr on PyPI, where spotr is an unrelated project, and is imported as spotr.
Optional extras: [tree] (networkx, to read trees as graphs), [plot] (scanpy and squidpy, for the notebook) and [c2l] (cell2location, for its reference signatures), as in pip install "phylospatial-spotr[plot]".
The development version installs with pip install git+https://github.com/pedrofale/spotr.git.
Quick start
SpOTr follows the interface of scvi-tools models such as DestVI. The dissociated cells (raw counts) carry each cell's type and each cancer cell's clone; a tree over the cancer cells is optional, as a Newick string, a networkx graph, a TreeData object or an .obsp matrix of tree distances. The spots carry raw counts and their positions.
import spotr
spotr.SpOTr.setup_anndata(
sc_adata,
labels_key="cell_type", # every cell's type
clone_key="clone", # each cancer cell's clone (NaN for the other cells)
tree=newick, # optional: leaves named by sc_adata.obs_names
)
model = spotr.SpOTr(sc_adata, st_adata, spatial_key="spatial")
model.train(alpha=0.2)
model.get_proportions() # spots x (cell types + clones), also in st_adata.obsm["spotr_proportions"]
model.get_mapping() # cancer cells x spots
model.get_cell_locations() # cancer cells x 2, also in sc_adata.obsm["spotr_spatial"]
model.choose_alpha([0, 0.1, 0.2, 0.4, 0.95]) # the elbow of the expression and structural costs
Without a tree, SpOTr draws the cells of each clone together. model.train(clade_weights={"clone 3": 0.0}) maps a clone known to be dispersed through the tissue by its expression alone.
Example
notebooks/spotr_toy_example.ipynb runs SpOTr on a toy tumor (spotr.datasets.toy_tumor()) whose clones are hard to distinguish by their expression but each hold their own territory, and compares it with SpOTr without the tree.
Reproducibility
The simulation benchmark, the analyses of the PEtracer and HTAN data, and every figure of the paper are in reproducibility/.
Citation
Pedro F. Ferreira, Oskar Kviman, Jens Lagergren. Phylospatial optimal transport for single-cell and spatial transcriptomics data integration (2026).
Metadata
Release files for phylospatial-spotr 0.1.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 |
|---|---|---|---|---|
| phylospatial_spotr-0.1.0.tar.gz | 20.0 kB | With provenance | Details for phylospatial_spotr-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| phylospatial_spotr-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for phylospatial_spotr-0.1.0-py3-none-any.whl |
Total release size: 42.3 kB
Release files / phylospatial_spotr-0.1.0.tar.gz
| Download URL | phylospatial_spotr-0.1.0.tar.gz |
|---|---|
| Size | 20.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e441e83e611415b49693d7de4b82f672975c6f1544fe627b2e0e2c57fc2b16d
|
|
BLAKE2b-256 checksum How to use checksums |
65b6cdd35ea0397d5fa1a31a3d1572469c822af21eaeb7f15670e6217bdd0c06
|
| 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 Nov 5, 2026.
Transparency logRelease files / phylospatial_spotr-0.1.0-py3-none-any.whl
| Download URL | phylospatial_spotr-0.1.0-py3-none-any.whl |
|---|---|
| Size | 22.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
32fc3e8b2ffcf9f2343d92cadeb2c178c97e8114c9a153158b669c06adc67171
|
|
BLAKE2b-256 checksum How to use checksums |
7684c4801e147c4b7c97e13dd15d373c6242336dd3c4d3b8d207d186066b2efb
|
| 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 Nov 5, 2026.
Transparency logSecurity for phylospatial-spotr 0.1.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 phylospatial_spotr-0.1.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 Nov 5, 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.