deepspot-m

Was macht deepspot-m?

Übersicht

DeepSpot-M ist ein multimodales Foundation-Modell, das eine 224×224 große H&E-Histologiekachel in räumliche Genexpression in log1p-CPM abbildet. Die Ausgabe ist eine virtuelle räumliche Transkriptomik: ein Wert pro abgefragtem Gen pro Kachel, angeordnet auf dem Raster, aus dem die Kacheln stammen.

Ein LoRA-angepasster Pathologie-Foundation-Backbone (Midnight) tokenisiert die Kachel. Ein Cross-Attention-Gen-Decoder ermöglicht es jedem Gen-Query, auf die Patch-Token zu achten, und ein Gen-Router-Hypernetzwerk erstellt genspezifische Projektionen aus eingefrorenen biologischen Embeddings (Evo 2, Orthrus, ProtT5, scGPT, Apertus). Gene werden als abfragbare Embeddings in das Modell eingegeben, nicht als feste Ausgabeschlitze, sodass das veröffentlichte Modell ein Panel von etwa 19k Proteinkodierungsgenen abdeckt, einschließlich Genen, die im Training nicht gesehen wurden. Das Panel wird mit den Gewichten als tokens.csv ausgeliefert und ist als model.gene_names verfügbar; Gene außerhalb können in dieser Version nicht abgefragt werden.

Angewandt auf TCGA erzeugte das Modell einen virtuellen räumlichen Transkriptom-Atlas von 28.664 Objektträgern über 32 Krebsarten hinweg.

Lizenzierung

Der Code steht unter der PolyForm Noncommercial 1.0.0-Lizenz und die Gewichte unter CC-BY-NC-SA-4.0. Verwende es für nichtkommerzielle Forschung und überprüfe beide Lizenzen, bevor du Ergebnisse weiterverteilst.

Installation

uv pip install deepspotm==1.0.0

Version 1.0.0 zielt auf Python 3.10 bis 3.13 ab und bezieht PyTorch mit ein. Installiere zuerst den PyTorch-Build, der zu deiner CUDA-Version passt, wenn du GPU-Inferenz verwenden möchtest.

Modellzugriff

Die Gewichte sind zugangsbeschränkt:

1. Öffne https://huggingface.co/ratschlab/DeepSpotM und beantrage Zugriff.
2. Sobald der Zugriff gewährt wurde, authentifiziere den Rechner, der die Gewichte herunterladen wird:

huggingface-cli login

from_pretrained liest dieses zwischengespeicherte Token, daher ist ein Login einmal pro Rechner erforderlich.

Schnellstart

from deepspotm import DeepSpotM

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

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

pil_tile ist ein PIL-Bild mit exakt 224×224 Pixeln. image_processor wandelt es in einen Tensor um, unsqueeze(0) fügt die Batch-Dimension hinzu, und predict_genes nimmt den Batch sowie eine Liste von HGNC-Gensymbolen entgegen. Die Werte werden in log1p-CPM zurückgegeben, ausgerichtet an der übergebenen Genliste, also behalte diese Liste neben der Ausgabe, um die Spalten beschriftet zu halten. Symbole müssen im veröffentlichten Panel von etwa 19k Genen (model.gene_names) enthalten sein; ein unbekanntes Symbol löst einen KeyError mit Nennung der fehlerhaften Gene aus.

Kachelanforderungen

Kacheln müssen 224×224 RGB bei etwa 20-facher Vergrößerung (etwa 0,5 Mikrometer pro Pixel) sein. Überprüfe die Größe an der Grenze deiner Pipeline, anstatt einen ungeprüften Ausschnitt durchzureichen:

TILE_PX = 224

def require_tile(tile):
    """Gib eine RGB 224×224-Kachel zurück oder löse einen Fehler aus, wenn der Ausschnitt die falsche Größe hat."""
    if tile.size != (TILE_PX, TILE_PX):
        raise ValueError(
            f"DeepSpot-M erwartet eine {TILE_PX}x{TILE_PX}-Kachel bei etwa 20x "
            f"(~0,5 Mikrometer pro Pixel); erhalten: {tile.size[0]}x{tile.size[1]}. "
            "Neu kacheln auf der passenden Ebene oder den Ausschnitt neu abtasten."
        )
    return tile.convert("RGB")

Extrahiere Kacheln auf der Objektträgerebene, deren Auflösung am nächsten bei 0,5 Mikrometern pro Pixel liegt, und schneide sie dort auf 224×224 zu. Eine Neuabtastung von einer gröberen Ebene verändert die Textur, die der Backbone liest.

Abhängigkeit optional halten

deepspotm und seine Gewichte sind eine schwere, zugangsbeschränkte Abhängigkeit. Importiere es innerhalb der Funktion, die es benötigt, damit das umgebende Projekt ohne es installiert, importiert und getestet werden kann, und verwandle einen ImportError in eine Nachricht, die jeden Schritt benennt:

DEEPSPOTM_HELP = (
    "DeepSpot-M ist nicht verfügbar. Installiere es mit `uv pip install deepspotm==1.0.0`, beantrage "
    "Zugriff auf die zugangsbeschränkten Gewichte unter https://huggingface.co/ratschlab/DeepSpotM, und "
    "authentifiziere dich mit `huggingface-cli login`."
)

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

Embedding-Quellen

source wählt aus, aus welchem eingefrorenen Gen-Embedding der Router Projektionen erstellt. Es ist einer von fünf Werten:

source	Gen-Embedding
evo2	Genomische Sequenz
orthrus	RNA
prott5	Proteinsequenz
scgpt	Einzelzell-Expression
apertus	Sprachmodell

Jede bietet eine andere Sicht auf die Genidentität. Wähle eine pro Durchlauf und führe dieselben Kacheln durch mehr als eine Quelle, wenn die Wahl für deine Analyse wichtig ist. Siehe references/api.md für die vollständige Aufruffläche, Batch-Verarbeitung und Geräteplatzierung, Behandlung von Gensymbolen und Ausgabeeinheiten.

Arbeitsablauf für ganze Objektträger

Die Vorhersage erfolgt pro Kachel, daher ist ein objektträgerweiter Durchlauf ein Kachelschritt gefolgt von batchweiser Inferenz:

1. Extrahiere 224×224-Kacheln auf einem Raster mit dem histolab-Skill und behalte die Koordinaten jeder Kachel.
2. Verarbeite und staple Kacheln mit torch.stack in Batches.
3. Rufe predict_genes einmal pro Batch mit derselben Genliste auf.
4. Verkette die Batches zu einer Kacheln-mal-Gene-Matrix und füge die Koordinaten hinzu.

Diese Matrix ist die virtuelle räumliche Transkriptom-Karte für den Objektträger und kann direkt in AnnData für nachgelagerte räumliche Analysen eingefügt werden. references/whole_slide.md enthält eine ausgearbeitete Schleife, Batch-Größenbestimmung und einen AnnData-Assemblierungsschritt.

Häufige Anwendungsfälle

• Räumliche Expressionskarten für Markergene über einen Tumorschnitt hinweg.
• Transkriptomweite Vorhersage über eine Objektträgerkohorte ohne passenden Assay-Durchlauf.
• Abfrage eines der etwa 19k Panel-Gene per Symbol, einschließlich in Training ungesehener Gene – weit über die wenigen hundert Gene eines typischen räumlichen Assay-Panels hinaus.
• Hinzufügen eines Expressionskanals zu einer rein morphologischen Histologie-Pipeline.
• Erstellung eines objektträgerweiten Kohorten-Atlasses, wie für TCGA durchgeführt.

Detaillierte Referenzen

• references/api.md: from_pretrained und predict_genes im Detail, die fünf Embedding-Quellen und wie man sie auswählt, Batch-Verarbeitung, Geräteplatzierung, Behandlung von Gensymbolen und Umrechnung der log1p-CPM-Ausgabe.
• references/whole_slide.md: Kacheln mit histolab, eine objektträgerweite Vorhersageschleife, Zusammenstellung und Speicherung einer Kacheln-mal-Gene-Matrix sowie kohortenweite Durchläufe.

Primärquellen

• Paper: https://doi.org/10.64898/2026.06.19.26356060 (medRxiv, veröffentlicht am 22. Juni 2026)
• Code: https://github.com/ratschlab/DeepSpotM
• Gewichte: https://huggingface.co/ratschlab/DeepSpotM
• PyPI: https://pypi.org/project/deepspotm/