spHOT

Phenotype-associated spatial biomarker discovery in spatial transcriptomics with spHOT

🧬 Description

🔥spHOT🔥 is a framework for localizing phenotype-associated spatial biomarkers from multi-sample, multi-patient spatial transcriptomics datasets with sample-level case/control labels. spHOT integrates spatial foundation model embeddings, a hierarchical domain tree, and a dual-branch teacher–student multiple instance learning architecture to convert sample-level phenotype labels into spatially coherent cell-level biomarker scores.

⚙️ Installation

Option 1 — PyPI

pip install sphot

Option 2 — GitHub

pip install git+https://github.com/DHKim327/spHOT.git

Option 3 — conda yml

git clone https://github.com/DHKim327/spHOT.git
cd spHOT
conda env create -f environment/env_spHOT.yml
conda activate env_spHOT
pip install -e .

📥 Inputs

AnnData directory :
Path to .h5ad files, saved per sample :

adatas/
├── sample1/adata.h5ad
└── sample2/adata.h5ad

• .obs key should contain sample phenotype label

Split information :

The splits.csv file defines train/valid/test splits for each sample across multiple folds.

• SID : Sample identifier (e.g., slide or tissue ID)
• 0–4 : Fold indices
• Each cell indicates the dataset role of that sample for a specific fold.

📤 Outputs

After an spHOT run, the output directory structure will be organized as below :

results/
└── {task_name}/                          # Name of run
    ├── de/                               # Domain embedding module result
    │   └── adata.h5ad                    # Merged AnnData with Novae embeddings & initial domain info           
    ├── dt/                               # Domain tree module result
    |   ├── centroid_HC_results.pkl       # Hierarchical domain tree
    |   └── adata.h5ad                    # Merged AnnData with metadomains association info
    └── mil/                              # MIL module result
        ├── D{k}/                         # k-level MIL result
        │   ├── model_encoder_exp{exp}.pt     # Model and outputs for each fold
        │   ├── model_teacher_exp{exp}.pt             
        │   ├── model_student_exp{exp}.pt            
        │   ├── resource_{exp}.csv            # Resource performance log
        │   └── CELL_SCORE_test_{exp}.h5ad    # spHOT cell scores (test) for each fold
        ├── all_test_results.csv          # Sample classification performance of test samples
        ├── all_test_results.csv          # Sample classification performance of validation samples
        └── k_selection_results.csv       # Spatial scores and k-selection result of spHOT run

📘 Tutorials

We provide the code and resources required to reproduce all main figures in the manuscript within the ./tutorial directory. Also, see the ./tutorial directory for step-by-step spHOT usage.

Figure-to-notebook map

Note : Notebooks are numbered by execution order within each figure directory (0. → 3.). Preprocessing notebooks start from public GEO accessions; the simulation dataset is downloaded from Zenodo as the version of record (see Data availability).

😊 Acknowledgements

spHOT is built upon codes from scMILD: Single-cell multiple instance learning for sample classification and associated subpopulation discovery. We thank the authors for publicly releasing their codes.

📚 References

Jeong, K., Choi, J. & Kim, K. scMILD: Single-cell multiple instance learning for sample classification and associated subpopulation discovery. iScience 29(2026).