README.md

---
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][]:

```bash
pip install interscale
```

### Latest development version

To install the latest development version directly from GitHub:

```bash
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=...)`. <!-- CONFIRM: actual loading API -->

| `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](https://www.10xgenomics.com/datasets/xenium-prime-fresh-frozen-human-ovary), CC BY 4.0) | [config]() | Radius-based spatial graph (image-based data); trained via masked-node self-supervised learning |

Here's a basic example: <!-- CONFIRM: function/argument names below follow scConcept's API as a template — adjust to InterScale's actual package interface. -->


### 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:

1. Remove the repository and clone the most recent version
2. Remove the cache directory (`cache/` by default)
3. 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

[uv]: https://github.com/astral-sh/uv
[Squidpy]: https://github.com/scverse/squidpy
[Geome]: https://github.com/theislab/geome
[pypi]: https://pypi.org/project/interscale