drug-discovery-prompts/upstream/K-Dense-AI-scientific-agent-skills/skills/deepspot-m/references/api.md

title, task, lineage_type, upstream_source, upstream_sha, imported_at, prompt_class, upstream_changes, author, validated

title	task	lineage_type	upstream_source	upstream_sha	imported_at	prompt_class	upstream_changes	author	validated
DeepSpot-M API reference		import	https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/deepspot-m/references/api.md	991bd993	2026-08-08	prompt	accepted	upstream	false

DeepSpot-M API reference

Everything here builds on the two calls in SKILL.md: DeepSpotM.from_pretrained and model.predict_genes.

Loading a model

from deepspotm import DeepSpotM

model, image_processor = DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source="scgpt")

from_pretrained returns two objects:

• model: the PyTorch model that answers gene queries.
• image_processor: the transform that turns one 224x224 PIL tile into the tensor the model reads. Always use the processor that came back with the model rather than a hand-written transform, so normalisation matches the weights.

Arguments:

• The repository id, "ratschlab/DeepSpotM". It is gated, so request access on the model page and run huggingface-cli login before the first call.
• source: which frozen gene embedding the router builds gene-specific projections from. One of evo2, orthrus, prott5, scgpt, apertus.

The first call downloads weights into the Hugging Face cache. Set HF_HOME to place that cache on a volume with room for it, which matters on a shared cluster where the default home directory is small.

Choosing an embedding source

source	Gene embedding
evo2	genomic sequence
orthrus	RNA
prott5	protein sequence
scgpt	single-cell expression
apertus	language model

The gene router turns whichever embedding you pick into per-gene projections, which is what makes genes queryable rather than fixed outputs. Each source describes gene identity from a different modality, so the same gene is represented differently under each one.

Pick one source per run and keep it fixed across every tile in a slide or cohort, so the values stay comparable. When the choice matters to a conclusion, run the same tiles through several sources and report the values side by side:

genes = ["EPCAM", "CD3D", "PTPRC"]

per_source = {}
for source in ("scgpt", "prott5", "evo2"):
    model, image_processor = DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source=source)
    tiles = torch.stack([image_processor(require_tile(t)) for t in pil_tiles])
    per_source[source] = model.predict_genes(tiles, genes)

Reload the model when you change source, and rebuild the tile batch with the processor returned alongside it.

Predicting genes

vals = model.predict_genes(image_processor(pil_tile).unsqueeze(0), ["EPCAM", "CD3D"])

The first argument is a batch tensor of processed tiles. The second is a list of gene symbols. A single tile still needs the batch dimension, which is what unsqueeze(0) adds.

Gene symbols

Pass HGNC gene symbols as uppercase strings, for example EPCAM, CD3D, PTPRC, MKI67. The queryable genes are the ~19k-symbol panel shipped with the weights as tokens.csv, exposed on the loaded model as model.gene_names. A symbol outside that panel raises KeyError naming the offending genes, and predicting genes outside the panel is not part of this release. Check membership up front when a gene list comes from elsewhere:

panel = set(model.gene_names)
missing = [g for g in genes if g not in panel]
if missing:
    raise ValueError(f"Not in the DeepSpot-M panel: {missing}")

Two habits keep a run reproducible:

• Map aliases to current HGNC symbols before querying, so CD45 becomes PTPRC. Reading the list from a file keeps the mapping visible in the run.
• Keep the gene list beside the output. Values come back in the order requested, and the list is the only label the array carries.

genes = [line.strip() for line in open("genes.txt") if line.strip()]
vals = model.predict_genes(tiles, genes)

Ask for every gene you need in one call rather than looping one gene at a time. The tile tokens are computed once per batch and reused across the gene queries.

Batching

image_processor handles one tile, so build a batch by stacking:

import torch

batch = torch.stack([image_processor(require_tile(t)) for t in pil_tiles])
vals = model.predict_genes(batch, genes)

Batch size trades throughput against memory. Start at 32 tiles on a GPU and 8 on CPU, then raise it while memory allows. Memory grows with both the batch and the number of genes in one call, so lower one when the other is large.

Device placement

from_pretrained accepts a device argument and returns the model already in eval mode on that device, and predict_genes runs under no_grad on its own. So device handling is one argument plus putting each batch on the same device:

import torch

device = "cuda" if torch.cuda.is_available() else "cpu"
model, image_processor = DeepSpotM.from_pretrained(
    "ratschlab/DeepSpotM", source="scgpt", device=device
)

vals = model.predict_genes(batch.to(device), genes)

Keeping the model on the device across batches is what makes a slide-scale run practical. Move results back with .cpu() before converting to NumPy.

Output units

Values are log1p-CPM, the same scale as log1p normalised counts per million in a single-cell or spatial expression matrix. It is the scale most downstream tools expect, so feed it straight into clustering, correlation or spatial statistics.

To read values as CPM instead, invert the transform:

import numpy as np

cpm = np.expm1(vals.cpu().numpy())

Compare values across tiles and slides on the log1p-CPM scale, since that is the scale the model produces.

Handling the gated download

from_pretrained fails when the machine has no access token or the access request is still pending. Report the whole path back to a working call rather than the raw error:

DEEPSPOTM_HELP = (
    "DeepSpot-M is unavailable. Install it with `uv pip install deepspotm==1.0.0`, request "
    "access to the gated weights at https://huggingface.co/ratschlab/DeepSpotM, then "
    "authenticate with `huggingface-cli login`."
)

def load_deepspotm(source="scgpt"):
    try:
        from deepspotm import DeepSpotM
    except ImportError as exc:
        raise RuntimeError(DEEPSPOTM_HELP) from exc
    try:
        return DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source=source)
    except Exception as exc:
        raise RuntimeError(DEEPSPOTM_HELP) from exc

On a cluster node with no outbound network, download the weights once on a login node and point HF_HOME at the shared cache.

Primary sources

• Paper: https://doi.org/10.64898/2026.06.19.26356060 (medRxiv, posted 22 June 2026)
• Code: https://github.com/ratschlab/DeepSpotM
• Weights: https://huggingface.co/ratschlab/DeepSpotM
• PyPI: https://pypi.org/project/deepspotm/