Path2Space Codebase

Overview

This repository contains the codebase for Path2Space, a model designed for predicting spatial transcriptomics (ST) from Hematoxylin and Eosin (H&E) stained slides.

Included Content

This repository includes:

- `scripts/` : a repository containing all necessary source code
- `tutorials/` : a repository containing a detailed tutorial to run Path2Space on a small example dataset
- `input_data/` : a repository containing the necessary inputs to run the tutorial
- `docs/` : a repository with an installation guide for all the required dependencies

System Requirements

Software Dependencies:
The software requires Python (3.10.8) and the following libraries:

- NumPy (1.24.4)
- Pandas (2.2.2)
- scikit-learn (1.5.1)
- Matplotlib (3.7.2)
- Seaborn (0.13.2)
- OpenSlide (1.3.1; for TGGA slides)
- OpenCV (4.6.0)
- Pillow (9.2.0; for ST slides)
- PyTorch (2.4.0+cu121)

Operating Systems Tested On:
- Linux 4.18.0-425.19.2.el8_7.x86_64

Hardware Requirements:
No special hardware is required; the code runs on a standard desktop computer. For large datasets, a GPU is recommended for faster processing.The code was tested on a system with the following specifcations

- Processor: x86_64
- CPU Cores: 28 (Physical), 56 (Logical)
- Total RAM: 251.50 GB
- GPU: Tesla K802. Installation Guide

Installation Instructions:
Follow instructions in `docs/INSTALLATION_GUIDE.md`

Estimated Installation Time:
Typically, it takes about 10–15 minutes on a standard desktop computer.

Demo

Instructions to Run Demo:
1. Navigate to the `tutorials/` folder.
2. Use the provided sample dataset and the provided tutorials to test the feature extraction, regression, and prediction pipelines.

- 1.STprediction_example.ipynb
- 2.CellTypeModel_example.ipynb
- 3.SPAND_example.ipynb

Expected Output:
- Example outputs and prediction results are stored in the `output_data/` folder.

Instructions for Use

Running on Your Data:
1. Prepare your data following the format provided in the demo dataset (`input_data/` folder).
2. Run the relevant scripts as described in the Usage section below.

Reproduction Instructions:
To reproduce all quantitative results described in the manuscript:

1. Use the full dataset specified in the Data Avalaibility section of the manuscript.
2. Follow the same pipeline steps as outlined above.

Usage

1.1. Feature Extraction:
- Navigate to `1.ST_prediction/1.1.Feature_extraction`.
- Run `1main_feature_extraction.py` for extracting features from H&E slide images.

1.2. Regression Tasks:
- Navigate to `1.ST_prediction/1.2.Regression`.
- Use `1main_regression.py` to train a regression model for ST prediction from H&E image features (output of 1.1).

1.3. Prediction Tasks:
- Navigate to `1.ST_prediction/1.3.Prediction`.
- Use `Prediction.py` to predict ST from features (output of 1.1) on a new dataset using a previously trained model (output of 1.2).

2.1. Cell Type Fraction Model Training:
- Navigate to `2.Cell_type_fraction_model/`.
- Use `2.1.main_cell_type_model.py` to train a cell type fraction prediction model from inferred ST values (output of 1.2 or 1.3).

2.2. Cell Type Fraction Prediction:
- Navigate to `2.Cell_type_fraction_model/`.
- Use `2.2.prediction.py` to predict cell type fractions from inferred ST values (output of 1.2 or 1.3) using a trained model (output of 2.1).

3. SPAND Analysis:
- Open `SPAND/SPAND.py` to calculate SPAND for a given slide and a given gene from inferred ST values (output of 1.2 or 1.3).

License and Terms of Use

This model and its associated code have been filed for a provisional US patent (application no. 63/703,060, United States, 2024) and are permitted solely for non-commercial, academic research purposes. Commercial use, sale, or any form of monetization of the DEPLOY model is strictly prohibited without prior approval. Commercial entities interested in utilizing the model should contact the corresponding authors for authorization.