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