Que fait deepspot-m ?
Aperçu
DeepSpot-M est un modèle de fondation multimodal qui transforme une tuile d'histologie H&E de 224×224 pixels en expression génique spatiale en log1p-CPM. La sortie est une transcriptomique spatiale virtuelle : une valeur par gène interrogé et par tuile, disposée sur la grille d'origine des tuiles.
Un backbone de fondation pathologique (Midnight) adapté par LoRA tokenise la tuile. Un décodeur de gènes à attention croisée permet à chaque requête de gène d'interagir avec les jetons de la tuile, et un hyper-réseau de routage de gènes construit des projections spécifiques à chaque gène à partir d'embeddings biologiques figés (Evo 2, Orthrus, ProtT5, scGPT, Apertus). Les gènes entrent dans le modèle sous forme d'embeddings interrogeables plutôt que de créneaux de sortie fixes, de sorte que le modèle publié couvre un panel d'environ 19 000 gènes codant pour des protéines, y compris des gènes jamais vus pendant l'entraînement. Le panel est livré avec les poids sous le nom tokens.csv et est exposé sous model.gene_names ; les gènes en dehors de ce panel ne peuvent pas être interrogés dans cette version.
Appliqué à TCGA, le modèle a produit un atlas de transcriptomique spatiale virtuelle de 28 664 lames couvrant 32 types de cancer.
Licence
Le code est sous licence PolyForm Noncommercial 1.0.0 et les poids sous licence CC-BY-NC-SA-4.0. Utilisez-le pour la recherche non commerciale et vérifiez les deux licences avant de redistribuer les sorties.
Installation
uv pip install deepspotm==1.0.0
La version 1.0.0 cible Python 3.10 à 3.13 et inclut PyTorch. Installez d'abord la version de PyTorch correspondant à votre version de CUDA si vous souhaitez une inférence GPU.
Accès au modèle
Les poids sont sous accès restreint :
- Ouvrez https://huggingface.co/ratschlab/DeepSpotM et demandez l'accès.
- Une fois l'accès accordé, authentifiez la machine qui les téléchargera :
huggingface-cli login
from_pretrained lit ce jeton mis en cache, donc une connexion est nécessaire une fois par machine.
Démarrage rapide
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 est une image PIL de exactement 224×224 pixels. image_processor la convertit en tenseur, unsqueeze(0) ajoute la dimension du lot, et predict_genes prend le lot ainsi qu'une liste de symboles de gènes HGNC. Les valeurs sont renvoyées en log1p-CPM, alignées avec la liste de gènes que vous avez passée, alors conservez cette liste à côté de la sortie pour garder les colonnes étiquetées. Les symboles doivent faire partie du panel d'environ 19 000 gènes publié (model.gene_names) ; un symbole inconnu lève une KeyError nommant les gènes incriminés.
Exigences pour les tuiles
Les tuiles doivent être en RGB 224×224 à environ 20x de grossissement (environ 0,5 micron par pixel). Vérifiez la taille à la limite de votre pipeline plutôt que de passer une culture non vérifiée :
TILE_PX = 224
def require_tile(tile):
"""Retourne une tuile RGB 224×224, ou lève une exception si la culture est de la mauvaise taille."""
if tile.size != (TILE_PX, TILE_PX):
raise ValueError(
f"DeepSpot-M s'attend à une tuile de {TILE_PX}x{TILE_PX} à environ 20x "
f"(~0,5 micron par pixel) ; a reçu {tile.size[0]}x{tile.size[1]}. "
"Re-tuilez au niveau correspondant ou rééchantillonnez la culture."
)
return tile.convert("RGB")
Extrayez les tuiles au niveau de la lame dont la résolution est la plus proche de 0,5 micron par pixel, puis recadrez à 224×224 à ce niveau. Le rééchantillonnage à partir d'un niveau plus grossier modifie la texture que le backbone lit.
Gardez la dépendance optionnelle
deepspotm et ses poids sont une dépendance lourde et sous accès restreint. Importez-la à l'intérieur de la fonction qui en a besoin afin que le projet environnant s'installe, s'importe et se teste sans elle, et transformez une ImportError en un message qui nomme chaque étape :
DEEPSPOTM_HELP = (
"DeepSpot-M est indisponible. Installez-le avec `uv pip install deepspotm==1.0.0`, demandez "
"l'accès aux poids sous accès restreint sur https://huggingface.co/ratschlab/DeepSpotM, puis "
"authentifiez-vous avec `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)
Sources d'embeddings
source sélectionne l'embedding de gène figé à partir duquel le routeur construit les projections. Il peut prendre l'une des cinq valeurs suivantes :
source | Embedding de gène |
|---|---|
evo2 | séquence génomique |
orthrus | ARN |
prott5 | séquence protéique |
scgpt | expression unicellulaire |
apertus | modèle de langage |
Chacune donne une vision différente de l'identité du gène. Choisissez-en une par exécution, et exécutez les mêmes tuiles avec plusieurs sources lorsque ce choix est important pour votre analyse. Consultez references/api.md pour la surface d'appel complète, le groupement par lots et le placement sur périphérique, la gestion des symboles de gènes et les unités de sortie.
Flux de travail pour lame entière
La prédiction se fait par tuile, donc une exécution à l'échelle de la lame est une étape de tuilage suivie d'une inférence par lots :
- Extrayez des tuiles de 224×224 sur une grille avec la compétence
histolab, en conservant les coordonnées de chaque tuile. - Traitez et empilez les tuiles en lots avec
torch.stack. - Appelez
predict_genesune fois par lot avec la même liste de gènes. - Concaténez les lots en une matrice tuiles×gènes et attachez les coordonnées.
Cette matrice est la carte de transcriptomique spatiale virtuelle pour la lame, et elle s'intègre directement dans AnnData pour une analyse spatiale en aval. references/whole_slide.md contient une boucle détaillée, la taille des lots et une étape d'assemblage dans AnnData.
Cas d'utilisation courants
- Cartes d'expression spatiale pour des gènes marqueurs à travers une section tumorale.
- Prédiction à l'échelle du transcriptome sur une cohorte de lames sans essai de dosage correspondant.
- Interrogation de n'importe lequel des ~19 000 gènes du panel par symbole, y compris les gènes jamais vus pendant l'entraînement — bien au-delà des quelques centaines de gènes d'un panel spatial typique.
- Ajout d'un canal d'expression à un pipeline d'histologie basé uniquement sur la morphologie.
- Construction d'un atlas de cohorte au niveau de la lame, comme cela a été fait pour TCGA.
Références détaillées
references/api.md:from_pretrainedetpredict_genesen détail, les cinq sources d'embeddings et comment choisir, le groupement par lots, le placement sur périphérique, la gestion des symboles de gènes et la conversion des sorties log1p-CPM.references/whole_slide.md: tuilage avec histolab, boucle de prédiction à l'échelle de la lame, assemblage et stockage d'une matrice tuiles×gènes, et exécutions à l'échelle de la cohorte.
Sources principales
- Article : https://doi.org/10.64898/2026.06.19.26356060 (medRxiv, publié le 22 juin 2026)
- Code : https://github.com/ratschlab/DeepSpotM
- Poids : https://huggingface.co/ratschlab/DeepSpotM
- PyPI : https://pypi.org/project/deepspotm/