VOICE-25M

Predict single-cell gene expression from H&E images using an image encoder, a spatial decoder, and a reference bank of cells with measured expression.

Resources

• Code: GitHub
• Paper: arXiv:2608.08366

Installation

Use Python 3.10 or later and install a PyTorch build suitable for your hardware.

git clone https://github.com/zchxhcz1/VOICE-25M.git
cd VOICE-25M
pip install -r requirements.txt

For SVS, NDPI, or MRXS images, install the OpenSlide system library and openslide-python. PNG, JPEG, and TIFF images are also supported. Large slide images should use an OpenSlide-readable format to avoid loading the entire image into memory.

Download the model

Download the checkpoints, fusion weights, gene information, and reference bank from Hugging Face. UNI2-h requires separate access through MahmoodLab/UNI2-h.

After receiving UNI2-h access, authenticate with your own Hugging Face account:

hf auth login
python - <<'PYTHON'
from huggingface_hub import snapshot_download, hf_hub_download

model_dir = "models/voice25m"
snapshot_download("zchx/VOICE-25M", local_dir=model_dir)
hf_hub_download("MahmoodLab/UNI2-h", "pytorch_model.bin", local_dir=f"{model_dir}/uni2h")
PYTHON

See model files for the directory structure.

Prediction

Run prediction from a single H&E image:

python predict/predict.py \
  --image /path/to/slide.svs \
  --release models/voice25m \
  --out results/prediction.h5ad

The command segments nuclei, extracts cell-centered image crops, predicts expression, retrieves reference expression, and combines both predictions. It also saves the segmentation beside the output. The first segmentation run downloads the Cellpose model; use --segment-model to provide local segmentation weights.

If the image does not contain physical resolution metadata, supply its actual microns per pixel:

python predict/predict.py --image /path/to/image.png --mpp 0.25 \
  --release models/voice25m --out results/prediction.h5ad

0.25 is an example. Use the resolution of your image. Prediction requires no measured expression or precomputed image features for the target slide.

Option	Purpose
--cells cells.npz	Use existing cell boundaries instead of automatic segmentation
--prepared /path/to/slide	Read prepared cell crops and boundaries instead of --image
--tissue xenium_lung	Select tissue-specific fusion weights; omitted or unknown tissue uses global weights
--genes all	Predict all 18,580 model genes; this is the default
--genes genes.txt	Predict an ordered list of gene symbols, one per line
--direct-only	Predict with the image model without reference retrieval
--save-embeddings	Save image and spatial features
--enc-chunk 32 --query-batch 64	Reduce transient GPU memory use
--sample-id SAMPLE --exclude RELATED_SAMPLE	Exclude the target and related references when they occur in the bank

CUDA is the default device. CPU inference is available with --device cpu --amp fp32. Prediction matrices are written to disk in batches; output size scales with the number of cells and requested genes. Automatic segmentation produces nuclei; use supplied cell boundaries when available.

Output

import anndata as ad
prediction = ad.read_h5ad("results/prediction.h5ad")

Field	Contents
X	Combined gene-expression scores
layers['A']	Direct predictions in log1p(mu) scale
layers['R']	Reference expression scores; NaN where reference coverage is unavailable
var['beta']	Applied fusion weight for each gene
var['covered']	Reference coverage for each gene
obsm['spatial']	Cell centroids as x,y coordinates in source-image pixels

The combined score is beta * A + (1 - beta) * R. Genes without reference coverage or fitted weights use the direct prediction. Combined scores describe variation across cells within each gene; they are not molecule counts. In direct-only mode, X contains the direct prediction.

Training

Training instructions cover RNA embedding preparation, image–RNA alignment, expression training, reference-bank construction, and fitting fusion weights. Training requires paired H&E images and measured spatial expression.

Input formats describe image geometry, prepared-slide files, reference-bank inputs, and output coordinates.