Scaling up spatial transcriptomics for large-sized tissues with iSCALE

Figure:iSCALE workflow

iSCALE (Inferring Spatially resolved Cellular Architectures for Large-sized tissue Environments) is a novel framework designed to integrate multiple daughter captures and utilize H&E information from large tissue samples, enabling prediction of gene expression with near single-cell resolution across whole-slide tissues.

---

🔧 Installation & Setup

Clone the repository (recommended) or download the .zip directly from GitHub:

git clone https://github.com/amesch441/iSCALE.git
cd iSCALE-main

Option A (recommended): Conda

conda env create -f environment.yml
conda activate iSCALE_env
cd iSCALE

Option B: Pip

python -m venv iSCALE_env
source iSCALE_env/bin/activate # Linux/Mac# or: .\iSCALE_env\Scripts\activate # Windows
pip install -r requirements.txt
cd iSCALE

⚡ GPU usage is strongly recommended for speed and scalability. CPU mode is supported but slower.

---

📦 Download Demo Data & Checkpoints

Download from Box link.

• Place the model checkpoint files:

  • vit4k_xs_dino.pth
  • vit256_small_dino.pth
    into:

  iSCALE-main/iSCALE/checkpoints/
  

• Place the demo folder into:

  iSCALE-main/iSCALE/data/
  

---

▶️ Running iSCALE

To run the demo, submit the appropriate job script depending on your cluster scheduler:

bsub < _run_iSCALE_bsub.sh # For LSF systems
sbatch _run_iSCALE_sbatch.sh # For SLURM systems

with prefix="Data/demo/".
Ground truth for this demo gastric tumor tissue can be found in the cnts-truth-agg folder.

• Use _run_iSCALE_sbatch.sh if your system uses SLURM.
• Use _run_iSCALE_bsub.sh if your system uses LSF.
  (These scripts are identical except for scheduler setup.)

⚠️Important: Make sure to edit the header of the run script (#SBATCH for SLURM or #BSUB for LSF) to set the correct queue/partition name for your system, as well as any resource requests (GPUs, memory, runtime).

---

📂 Repository Structure

iSCALE-main/
│
├── environment.yml # conda environment specification
├── requirements.txt # pip requirements
│
├── iSCALE/
│ ├── checkpoints/ # pretrained models (place downloaded .pth files here)
│ ├── data/ # input data (demo folder goes here)
│ ├── Alignment_scripts/ # tools for semi-automatic alignment
│ ├── logs/ # log directory
│ │ ├── logs_output/ # job standard output logs
│ │ └── logs_errors/ # job error logs
│ ├── *.py # main Python scripts
│ ├── *.sh # run scripts (SLURM/LSF)
│ └── ...

---

📂 Input Data & Formats

Each project has the following structure:

iSCALE-main/iSCALE/Data/<project_name>/
│
├── DaughterCaptures/
│ ├── UnallignedToMother/ # raw ST data (Visium, Visium HD, Xenium, CosMx)
│ │ ├── D1/
│ │ │ ├── cnts.tsv # count matrix (genes × spots)
│ │ │ ├── locs.tsv # coordinates (spot_id, x, y)
│ │ │ └── he.* # H&E image (see formats below)
│ │ ├── D2/
│ │ └── ...
│ │
│ └── AllignedToMother/ # aligned data (produced after registration)
│ ├── D1/
│ │ ├── cnts.tsv
│ │ └── locs.tsv
│ ├── D2/
│ └── ...
│
└── MotherImage/
├── he-raw.* # raw H&E (before scaling)
├── he-scaled.* # scaled H&E (after resizing)
├── he.tiff # final processed H&E with padding
├── radius-raw.txt # raw spot radius in pixels
├── radius.txt # scaled radius in pixels (auto-generated if missing using rescale_locs.py)
└── markers.csv (optional) # marker genes for auto-annotation

Notes

• Always run preprocess.py to generate the final he.tiff file for the MotherImage folder.
• Supported input H&E formats for mother image:
  .tiff, .tif, .svs, .ome.tif, .ome.tiff, .jpg, .png, .ndpi, .scn, .mrxs
• locs.tsv: must contain

  spot x y
  

• cnts.tsv: genes × spots matrix (tab-delimited).
• markers.csv (optional):

  gene,label
  MKI67,Tumor
  KRT20,Mucosa
  ...
  

---

⚙️ Input Parameters

Parameters are set in the run scripts (_run_iSCALE_sbatch.sh or _run_iSCALE_bsub.sh).

Parameter	Description	Default Example
prefix_general	Project directory path (must contain DaughterCaptures and MotherImage)	Data/demo/
daughterCapture_folders	List of daughter capture folders	("D1" "D2" "D3" "D4" D5")
device	Compute device: "cuda" (GPU) or "cpu"	"cuda"
pixel_size_raw	Pixel size (µm/pixel) of raw H&E	0.252
pixel_size	Desired pixel size after rescaling	0.5
n_genes	Number of most variable genes to impute	100
n_clusters	Number of clusters for downstream analysis	20
dist_ST	Smoothing parameter across ST captures (integration sharpness)	100

Notes

• prefix_general is the main project folder.
• dist_ST=100 works well in most cases, but check QC plots in iSCALE_output/spot_level_st_plots/spots-integrated to tune if needed.
• n_genes=100 is used in the demo because the Xenium dataset has a small targeted panel. For Visium and other platforms with larger gene counts, much higher values (e.g. 3000) are appropriate.

---

📤 Output

All results are saved to iSCALE_output/:

• spot_level_st_plots/
  QC plots to confirm correct alignment of daughter captures onto mother image.
• super_res_gene_expression/
  Imputed super-resolution expression (pickle files).
  • refined/ subfolder updates predictions for regions unlikely to contain cells.
• super_res_ST_plots/
  Visualizations of super-resolution gene expression.
  • includes refined/.
• clusters-gene_#/
  Clustering results using imputed gene expression.
• annotation/
  Cell-type/region annotations if markers.csv was provided.

---

📖 Citation

If you use iSCALE, please cite:

Schroeder A., et al. Scaling up spatial transcriptomics for large-sized tissues: uncovering cellular-level tissue architecture beyond conventional platforms.
Nature Methods (2025).
https://www.nature.com/articles/s41592-025-02770-8

---

📜 License

This project is licensed under the terms of the LICENSE file included in this repository.