GHIST+

GHIST+ is a framework for tissue-wide reconstruction of single-cell molecular states from H&E histology

Repository Layout

• train.py: main training entry point.
• tools/inference.py: checkpoint inference and prediction export.
• tutorial.ipynb: single-slide, multi-slide, and PanCancer walkthrough.
• configs/: publication training configs.
• dataio/: image, nuclei, patch, and expression data loaders.
• model/: GHIST+ model components.
• utils/: config, device, image, and helper utilities.

Installation

Use a CUDA-enabled Linux machine with a compatible PyTorch install. The code was tested on Ubuntu 24.04.1 LTS, Python 3.10.16, NVIDIA RTX A6000 GPUs, driver 550.120, and PyTorch 2.6.0 with CUDA 12.4.

conda create --name model_env python=3.10
conda activate model_env

pip install torch torchvision
pip install numpy pandas scipy scikit-learn matplotlib tqdm natsort h5py
pip install tifffile imageio opencv-python pillow timm huggingface_hub torchstain
pip install git+https://github.com/sebastianffx/stainlib.git

Tested package versions include torch==2.6.0, torchvision==0.21.0, numpy==1.26.4, pandas==2.3.2, scipy==1.15.3, scikit-learn==1.7.1, matplotlib==3.8.2, timm==0.9.12, huggingface_hub==0.33.2, and torchstain==1.4.1.

Installation usually takes 10-30 minutes on a CUDA Linux workstation, excluding large downloads. The first run downloads the UNI2-h checkpoint through the Hugging Face cache.

Distribution-aware reconstruction

The hurdle output predicts expression presence separately from positive magnitude. Validation and inference use the same deterministic prevalence gate.

Data Configuration

Configs use environment-variable placeholders for local data and run paths. Set those paths before training or edit the config directly.

Each slide entry should point to:

• aligned H&E image
• nuclei segmentation mask
• matched nuclei metadata
• expression matrix and cell-type labels for training/evaluation slides

For prediction-only inference, target expression labels are not required.

Tutorial

Open tutorial.ipynb from the repository root. Select single, multi, or pancancer, set the data root, and run the cells from top to bottom.

Training

Run from the repository root:

python train.py \
  --config_file configs/config_all_cancers.json \
  --fold_id 1 \
  --gpu_id 0

Training outputs include the copied config, genes.txt, stain standardisation file, checkpoints, metrics, and imputed cache files.

Inference

Run inference from a completed training run:

python tools/inference.py \
  --experiment_path results/fold1_YYYY_MM_DD_HH_MM_SS \
  --config_file configs/config_all_cancers.json \
  --impute_dir /path/to/cache_root/imputed_<hash> \
  --slide_id 14 \
  --gpu_id 0 \
  --output_dir /path/to/inference_output

Use --checkpoint_path /path/to/epoch_N_model.pth to select a specific checkpoint. Use --skip_metrics for prediction-only runs without target labels.

Main outputs:

• *_pred_expr_scaled.csv
• *_pred_expr_scaled.npz
• *_pred_celltype.csv
• *_pred_celltype_probs.csv
• *_meta.json

Validation

Install pytest, then run:

python -m pytest -q

Notes

• Large generated files are ignored by .gitignore.
• Keep the config, checkpoint, genes.txt, stain standardisation file, and matching cache together when moving a trained run.
• To reproduce manuscript-scale experiments, use the provided config format with the corresponding datasets, checkpoints, and run paths.