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.

Related repositories

Two companion GitHub repositories accompany this codebase:

• path2space-extended — extended analysis components beyond the core inference code: QC pipeline, cell-type deconvolution, SpatioType clustering, treatment-response prediction, SPAND analysis, benchmarking against 16 ST prediction methods, and additional downstream analyses reproducing figures from the paper.
  https://github.com/eldadshulman/path2space-extended 
  
  
• path2space-companion — installable Python package with the core Path2Space model and inference utilities.
  https://github.com/eldadshulman/path2space-companion 

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. Full list of Python package dependencies with pinned versions is in requirements.txt (or use environment.yml for conda). See README.txt for installation instructions.

System Dependencies (required before pip install): libopenslide must be installed at the OS level (openslide-python is a Python wrapper for a C library). Ubuntu/Debian: sudo apt install libopenslide-dev. macOS: brew install openslide. HPC: module load openslide or build from source.

Alternative installation: use the provided environment.yml file with `conda env create -f environment.yml` to install all Python and system-level dependencies in one step. 

Operating Systems Tested On: Linux (RHEL 8 / Rocky 8)

Hardware Requirements: For inference and small-scale experiments, the code runs on a standard desktop or laptop with sufficient RAM. For training and large-scale prediction, an NVIDIA GPU with CUDA 12 support and at least 16 GB of GPU memory is recommended. The work in the associated publication was performed on the NIH Biowulf HPC cluster.

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 Path2Space model is strictly prohibited without prior approval. Commercial entities interested in utilizing the model should contact the corresponding authors for authorization.