init repo + ReadMe

README.md

@@ -1,3 +1,103 @@
 ---
 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. -->
+
+```python
+from interscale import InterScale
+import scanpy as sc
+import squidpy as sq
+
+# Load your spatial transcriptomics data
+adata = sc.read_h5ad("your_data.h5ad")
+
+# Normalize and log-transform (InterScale performs best with max normalized values of 4)
+sc.pp.normalize_total(adata)
+sc.pp.log1p(adata)
+
+# Build the spatial neighborhood graph
+# Use a radius-based graph for image-based data (e.g. Xenium, MERFISH, IMC),
+# or a hexagonal grid-based graph for sequencing-based data (e.g. Visium)
+sq.gr.spatial_neighbors(adata, coord_type="generic", radius=<INSERT RADIUS>)
+
+# Initialize InterScale and load a pretrained model
+model = InterScale(cache_dir="./cache/")
+model.load_config_and_model(model_name="<INSERT MODEL NAME>")
+
+# Extract local and global embeddings
+result = model.extract_embeddings(adata=adata)
+adata.obsm["X_interscale_local"] = result["local_emb"]
+adata.obsm["X_interscale_global"] = result["global_emb"]
+```
+
+### 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