deepspot-m

O que deepspot-m faz?

Visão Geral

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

Um backbone de fundação patológica adaptado com LoRA (Midnight) tokeniza o tile. Um decodificador de genes com atenção cruzada permite que cada consulta de gene atenda aos tokens do patch, e uma hiper-rede roteadora de genes constrói projeções específicas para cada gene 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 lançado cobre um painel de ~19 mil genes codificadores de proteínas, incluindo genes não vistos no treinamento. O painel acompanha 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 lâminas 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. Use-o para pesquisa não comercial e verifique ambas as licenças antes de redistribuir saídas.

Instalação

uv pip install deepspotm==1.0.0

A versão 1.0.0 é direcionada ao Python 3.10 até 3.13 e inclui PyTorch. Instale a compilação do PyTorch que corresponda à sua versão CUDA primeiro se quiser inferência em GPU.

Acesso ao modelo

Os pesos são controlados:

1. Abra https://huggingface.co/ratschlab/DeepSpotM e solicite acesso.
2. Uma vez que o acesso seja concedido, autentique a máquina que irá baixá-los:

huggingface-cli login

from_pretrained lê esse token em cache, então um login é necessário uma vez por máquina.

Início Rápido

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 é uma imagem PIL de exatamente 224x224 pixels. image_processor a transforma em um tensor, unsqueeze(0) adiciona a dimensão do lote, e predict_genes recebe o lote mais uma lista de símbolos genéticos HGNC. Os valores retornam em log1p-CPM, alinhados com a lista de genes que você passou, então mantenha essa lista junto com a saída para manter as colunas rotuladas. Os símbolos devem estar no painel de ~19 mil genes lançado (model.gene_names); um símbolo desconhecido levanta KeyError nomeando os genes ofensores.

Requisitos dos tiles

Os tiles devem ser RGB 224x224 em aproximadamente 20x de ampliação (cerca de 0,5 micrômetros por pixel). Verifique o tamanho no limite do seu pipeline em vez de passar um crop não verificado:

TILE_PX = 224

def require_tile(tile):
    """Retorna um tile RGB 224x224, ou levanta se o crop tiver o tamanho errado."""
    if tile.size != (TILE_PX, TILE_PX):
        raise ValueError(
            f"DeepSpot-M espera um tile de {TILE_PX}x{TILE_PX} a aproximadamente 20x "
            f"(~0.5 micrômetros por pixel); obteve {tile.size[0]}x{tile.size[1]}. "
            "Re-tile no nível correspondente ou reamostre o crop."
        )
    return tile.convert("RGB")

Extraia tiles no nível da lâmina cuja resolução seja mais próxima de 0,5 micrômetros por pixel, então recorte para 224x224 nesse nível. Reamostrar de um nível mais grosseiro altera a textura que o backbone lê.

Mantenha a dependência opcional

deepspotm e seus pesos são uma dependência pesada e controlada. Importe-a dentro da função que precisa dela para que o projeto circundante instale, importe e teste sem ela, e transforme um ImportError em uma mensagem que nomeie cada passo:

DEEPSPOTM_HELP = (
    "DeepSpot-M não está disponível. Instale-o com `uv pip install deepspotm==1.0.0`, solicite "
    "acesso aos pesos controlados em https://huggingface.co/ratschlab/DeepSpotM, então "
    "autentique-se com `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)

Fontes de embeddings

source seleciona de qual embedding gênico congelado o roteador constrói projeções. É um de cinco valores:

source	Embedding gênico
evo2	sequência genômica
orthrus	RNA
prott5	sequência proteica
scgpt	expressão de célula única
apertus	modelo de linguagem

Cada uma oferece uma visão diferente da identidade do gene. Escolha uma por execução e execute os mesmos tiles através de mais de uma fonte quando a escolha for importante para sua análise. Veja references/api.md para a superfície completa de chamada, agrupamento em lote e posicionamento do dispositivo, manipulação de símbolos genéticos e unidades de saída.

Fluxo de trabalho para lâmina inteira

A predição é por tile, então uma execução em escala de lâmina é uma etapa de tileamento seguida por inferência em lote:

1. Extraia tiles 224x224 em uma grade com a habilidade histolab, mantendo as coordenadas de cada tile.
2. Processe e empilhe os tiles em lotes com torch.stack.
3. Chame predict_genes uma vez por lote com a mesma lista de genes.
4. Concatene os lotes em uma matriz tiles-por-genes e anexe as coordenadas.

Essa matriz é o mapa de transcriptômica espacial virtual para a lâmina, e ela se encaixa diretamente em AnnData para análise espacial downstream. references/whole_slide.md tem um loop funcional, dimensionamento de lote e uma etapa de montagem de AnnData.

Casos de uso comuns

• Mapas de expressão espacial para genes marcadores em uma seção tumoral.
• Predição em todo o transcriptoma sobre uma coorte de lâminas sem ensaio correspondente.
• Consultar qualquer um dos ~19 mil genes do painel por símbolo, incluindo genes não vistos no treinamento — muito além das poucas centenas de genes de um painel de ensaio espacial típico.
• Adicionar um canal de expressão a um pipeline de histologia baseado apenas em morfologia.
• Construir um atlas de coorte em nível de lâmina, como feito para o TCGA.

Referências detalhadas

• references/api.md: from_pretrained e predict_genes na íntegra, as cinco fontes de embedding e como escolher, agrupamento em lote, posicionamento do dispositivo, manipulação de símbolos genéticos e conversão da saída log1p-CPM.
• references/whole_slide.md: tileamento com histolab, um loop de predição em escala de lâmina, montagem e armazenamento de uma matriz tiles-por-genes, e execuções em escala de coorte.

Fontes primárias

• Artigo: https://doi.org/10.64898/2026.06.19.26356060 (medRxiv, postado em 22 de junho de 2026)
• Código: https://github.com/ratschlab/DeepSpotM
• Pesos: https://huggingface.co/ratschlab/DeepSpotM
• PyPI: https://pypi.org/project/deepspotm/