lazyslide_models.feature_prediction.STPath#
- class STPath(organ_type=None, tech_type=None, genes=None, model_path=None, gene_voc_path=None, token=None, max_spots=8000)#
Bases:
FeaturePredictionModelstpath 🤗Hugging Face GitHub Paper Params: 49.2M Unlicensed [Huang et al., 2025] Predict spatial gene expression from GigaPath tile features with a spatially aware transformer. STPath spatial transcriptomics predictor.
Consumes 1536-dimensional GigaPath tile features together with tile coordinates and predicts log1p-transformed expression for 38,982 genes, keyed by Ensembl gene ID.
Unlike
Path2Space, predictions are not independent per tile: a spatial transformer attends over every spot at once, so the model must see the whole slide in one call. The runner handles that throughneeds_coordsandwhole_slide.>>> import lazyslide as zs >>> zs.tl.feature_extraction(wsi, "gigapath") >>> zs.tl.feature_prediction( ... wsi, STPath(organ_type="Kidney", tech_type="Visium", ... genes=["GATA3", "UBE2C"]) ... )
Note
Attention cost is quadratic in the number of spots, and every tile is seen in one call — there is no batching, so
max_spotsbounds the whole slide, not a chunk of it. Past itpredictraises rather than thrashing, before producing any output.Measured peak memory is roughly 1 GB at 1,000 spots, 4.7 GB at 4,000 and 9.6 GB at 6,000. STPath is a spot-level model — a Visium section is a few thousand spots at 100 µm pitch — so a whole slide at that resolution does not fit: a typical slide tiled at 128 µm is around 12,000 tiles. Use it on a region of interest, or keep 256 px tiles at mpp 0.5 (GigaPath’s input scale) and coarsen only their spacing, e.g.
stride_px=512for a 256 µm pitch, accepting that this is sparser than the spots the model was trained on.Note
In-context conditioning on observed expression, which upstream exposes through
context_gene_exps, is not wired up here; every spot is predicted from image features alone.- Parameters:
- organ_typestr, optional
Organ the section comes from, e.g.
"Kidney". Aliases from STPath’s organ vocabulary are accepted. When omitted the organ token is padded, matching the reference implementation.- tech_typestr, optional
Spatial technology, one of
"Spatial Transcriptomics","Visium","Xenium","Visium HD". Padded when omitted.- genessequence of str, optional
Restrict the output to these gene symbols. Strongly recommended: the full panel is 38,982 columns, which is slow to assemble and wide to store. When omitted every gene is returned, keyed by Ensembl ID.
- model_pathstr, optional
Local
stfm.pthto load instead of downloading.- gene_voc_pathstr, optional
Local
symbol2ensembl.jsonto load instead of downloading.- tokenstr, optional
Hugging Face access token.
- max_spotsint, default: 8000
Refuse to run above this many tiles. See the note on memory.
- predict(features, coords=None)#
Predict log1p expression for every tile of one slide.
- Parameters:
- featuresarray-like, shape (n_tiles, 1536)
GigaPath tile features for the whole slide.
- coordsarray-like, shape (n_tiles, 2)
Tile origins in slide coordinates. Required.