lazyslide_models.feature_prediction.STPath

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: FeaturePredictionModel

stpath 🤗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 through needs_coords and whole_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_spots bounds the whole slide, not a chunk of it. Past it predict raises 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=512 for 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.pth to load instead of downloading.

gene_voc_pathstr, optional

Local symbol2ensembl.json to 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.