license: mit
language:
- en
tags:
- spatial-transcriptomics
- cell-cell-communication
InterScale
This repository contains the Python package to load and use pretrained InterScale models for spatial transcriptomics data. InterScale is a graph-transformer framework that jointly models local (cell-neighborhood) and global (tissue-level) cellular interactions from spatial omics data.
Installation
You need Python 3.10 or newer installed on your system. If you don't have Python installed, we recommend installing uv.
Default installation
Install the latest release of interscale from PyPI:
pip install interscale
Latest development version
To install the latest development version directly from GitHub:
pip install git+https://github.com/theislab/interscale.git@main
InterScale builds graphs from spatial coordinates using Squidpy and loads them as PyTorch Geometric objects using Geome.
How to use
InterScale combines a Graph Convolutional Network (local component) with a Transformer encoder (global component, masked to attend only within each cell's local neighborhood) to produce a local embedding (short-range, cell-neighborhood signal) and a global embedding (tissue-level, long-range signal) for every cell.
Pre-trained models
The following models are available from the InterScale Hugging Face repository. Use the value in the model_name column with interscale.load_config_and_model(model_name=...).
model_name |
Training corpus | Platform | Architecture | Notes |
|---|---|---|---|---|
xenium_5k_human_ovarian_adenocarcinoma |
Fresh-frozen human ovarian adenocarcinoma, ~1.16M cells, Xenium Prime 5K Human Pan Tissue and Pathways Panel (10x Genomics, 2024, CC BY 4.0) | config | Radius-based spatial graph (image-based data); trained via masked-node self-supervised learning |
Here's a basic example:
Multi-scale downstream analysis
InterScale provides functions for analysis at three scales, using the attention matrix and the learned embeddings:
- Tissue / graph level — CLS-token attention, for condition or graph-label prediction
- Cell level — normalized attention scores between sender and receiver cells, for interaction strength
- Gene level — ranking of gene contributions from local and global embedding loadings, for scale-specific driver genes
Troubleshooting
If you encounter an error when loading a pre-trained model, try the following:
- Remove the repository and clone the most recent version
- Remove the cache directory (
cache/by default) - Run again
This will force a fresh download of the pre-trained model and should resolve most loading issues.
Citation
Drummer, F., Jiménez, S., Di Marco, F., Schaar, A.C., Pentimalli, T.M., Beckman, J.L., Rajewsky, N. and Theis, F.J., 2026. InterScale reveals multi-scale cellular interaction programs in spatial transcriptomics. bioRxiv. doi: https://doi.org/10.64898/2026.05.07.723456