DeepSpot-M

Visão Geral

DeepSpot-M é um modelo fundamental multimodal que mapeia um bloco de histologia H&E de 224x224 para a expressão gênica espacial em log1p-CPM. A saída é transcriptômica espacial virtual: um valor por gene consultado por bloco, organizado na grade de onde os blocos vieram.

Um backbone de fundação de patologia adaptado por LoRA (Midnight) tokeniza o bloco. Um decodificador de gene por atenção cruzada permite que cada consulta de gene atenda aos tokens do patch, e um hypernetwork de roteamento de genes constrói projeções específicas de genes a partir de embeddings biológicos congelados (Evo 2, Orthrus, ProtT5, scGPT, Apertus). Os genes entram no modelo como embeddings consultáveis em vez de slots de saída fixos, então o modelo liberado cobre um painel de ~19k genes codificadores de proteínas, incluindo genes não vistos no treinamento. O painel é enviado com os pesos como tokens.csv e é exposto como model.gene_names; genes fora dele não podem ser consultados nesta versão.

Aplicado ao TCGA, o modelo produziu um atlas de transcriptômica espacial virtual de 28.664 slides em 32 tipos de câncer.

Licenciamento

O código é PolyForm Noncommercial 1.0.0 e os pesos são CC-BY-NC-SA-4.0. O formulário de acesso ao modelo atual restringe ainda mais a elegibilidade a pesquisadores acadêmicos/públicos sem fins lucrativos sem afiliações comerciais concorrentes e exclui o uso comercialmente financiado/colaborativo. Leia as declarações ao vivo antes de solicitar acesso; uma intenção não comercial por si só não estabelece elegibilidade. Apenas para uso em pesquisa, não para uso clínico ou diagnóstico. Preserve a atribuição e as licenças aplicáveis.

Instalação

uv pip install deepspotm==1.0.0

PyPI 1.0.0 declara Python >=3.10 sem limite superior; isso não é prova de compatibilidade com todas as futuras versões de dependência. Use um ambiente isolado. Instale a versão do PyTorch que corresponde ao seu runtime CUDA se estiver usando uma GPU. O tiler opcional histolab 0.7.0 requer Python <3.12 e uma pilha científica mais antiga: execute a tiler separadamente e troque blocos PNG mais um manifesto de coordenadas.

Acesso ao Modelo

Os pesos são restritos:

1. Abra https://huggingface.co/ratschlab/DeepSpotM e solicite acesso.
2. Assim que o acesso for concedido, autentique a máquina que os baixará:

hf auth login

O downloader do Hugging Face usa credenciais em cache ou HF_TOKEN; aprovação e autenticação são separadas. Defina HF_HOME antes de importar bibliotecas do Hub se escolher um local de cache. Não coloque tokens no código. Um diretório de modelo local aprovado pode ser carregado offline.

Início Rápido

Inferência restrita ilustrativa; a API de carregamento/consulta e o pré-processamento local foram verificados sem baixar os pesos:

import torch
from PIL import Image
from deepspotm import DeepSpotM

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

with Image.open("tile.png") as image:
    if image.size != (224, 224):
        raise ValueError("Expected a pre-tiled 224x224 image at verified ~0.5 um/px")
    batch = image_processor(image.convert("RGB")).unsqueeze(0).to(device)
genes = ["EPCAM", "CD3D"]
vals = model.predict_genes(batch, genes).cpu()  # shape (1, 2)

image_processor transforma uma imagem PIL em um tensor; unsqueeze(0) adiciona a dimensão do lote e predict_genes recebe o lote mais uma lista de símbolos de genes HGNC. Os valores retornam em log1p-CPM, alinhados com a lista de genes que você passou, então mantenha essa lista ao lado da saída para manter as colunas rotuladas. Os símbolos devem estar no painel de ~19k genes liberado (model.gene_names); um símbolo desconhecido gera KeyError nomeando os genes ofensivos.

Requisitos de Bloco

Os blocos devem ser RGB de 224x224 com aproximadamente 20x de magnificação (cerca de 0,5 mícrons por pixel). Verifique o tamanho na borda do seu pipeline em vez de passar um corte não verificado:

TILE_PX = 224

def require_tile(tile):
    """Return an RGB 224x224 tile, or raise if the crop is the wrong size."""
    if tile.size != (TILE_PX, TILE_PX):
        raise ValueError(
            f"DeepSpot-M expects a {TILE_PX}x{TILE_PX} tile at about 20x "
            f"(~0.5 microns per pixel); got {tile.size[0]}x{tile.size[1]}. "
            "Re-tile at the matching level or resample the crop."
        )
    return tile.convert("RGB")

O tamanho do pixel por si só não verifica a magnificação. Leia ambos os eixos MPP e o real

…