¿Qué hace deepspot-m?
Resumen
DeepSpot-M es un modelo fundacional multimodal que mapea un tile de histología H&E de 224x224 píxeles a expresión génica espacial en log1p-CPM. La salida es transcriptómica espacial virtual: un valor por gen consultado por tile, dispuesto en la cuadrícula de la que provienen los tiles.
Una espina dorsal de patología de base adaptada con LoRA (Midnight) tokeniza el tile. Un decodificador de genes con atención cruzada permite que cada consulta de gen atienda a los tokens del parche, y una hiperred de enrutamiento de genes construye proyecciones específicas para cada gen a partir de incrustaciones biológicas congeladas (Evo 2, Orthrus, ProtT5, scGPT, Apertus). Los genes ingresan al modelo como incrustaciones consultables en lugar de ranuras de salida fijas, por lo que el modelo lanzado cubre un panel de ~19,000 genes codificantes de proteínas, incluidos genes no vistos en el entrenamiento. El panel se distribuye con los pesos como tokens.csv y se expone como model.gene_names; los genes fuera de este panel no se pueden consultar en esta versión.
Aplicado a TCGA, el modelo produjo un atlas de transcriptómica espacial virtual de 28,664 portaobjetos en 32 tipos de cáncer.
Licencia
El código tiene licencia PolyForm Noncommercial 1.0.0 y los pesos tienen licencia CC-BY-NC-SA-4.0. Úsalo para investigación no comercial y verifica ambas licencias antes de redistribuir resultados.
Instalación
uv pip install deepspotm==1.0.0
La versión 1.0.0 está dirigida a Python 3.10 a 3.13 e incluye PyTorch. Instala primero la compilación de PyTorch que coincida con tu versión de CUDA si deseas inferencia en GPU.
Acceso al modelo
Los pesos están restringidos:
- Abre https://huggingface.co/ratschlab/DeepSpotM y solicita acceso.
- Una vez que se conceda el acceso, autentica la máquina que los descargará:
huggingface-cli login
from_pretrained lee ese token en caché, por lo que se necesita un inicio de sesión una vez por máquina.
Inicio 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 es una imagen PIL de exactamente 224x224 píxeles. image_processor la convierte en un tensor, unsqueeze(0) agrega la dimensión del lote, y predict_genes toma el lote más una lista de símbolos de genes HGNC. Los valores se devuelven en log1p-CPM, alineados con la lista de genes que proporcionaste, así que mantén esa lista junto con la salida para mantener las columnas etiquetadas. Los símbolos deben estar en el panel de ~19,000 genes publicado (model.gene_names); un símbolo desconocido lanza KeyError nombrando los genes infractores.
Requisitos de los tiles
Los tiles deben ser RGB de 224x224 a aproximadamente 20x de aumento (alrededor de 0.5 micras por píxel). Verifica el tamaño en el límite de tu pipeline en lugar de pasar un recorte sin verificar:
TILE_PX = 224
def require_tile(tile):
"""Devuelve un tile RGB de 224x224, o lanza una excepción si el recorte es del tamaño incorrecto."""
if tile.size != (TILE_PX, TILE_PX):
raise ValueError(
f"DeepSpot-M espera un tile de {TILE_PX}x{TILE_PX} a aproximadamente 20x "
f"(~0.5 micras por píxel); se obtuvo {tile.size[0]}x{tile.size[1]}. "
"Vuelve a hacer tileado en el nivel coincidente o remuestrea el recorte."
)
return tile.convert("RGB")
Extrae tiles en el nivel del portaobjetos cuya resolución sea la más cercana a 0.5 micras por píxel, luego recorta a 224x224 en ese nivel. Remuestrear desde un nivel más grueso cambia la textura que lee la espina dorsal.
Mantén la dependencia opcional
deepspotm y sus pesos son una dependencia pesada y restringida. Impórtala dentro de la función que la necesite para que el proyecto circundante se instale, importe y pruebe sin ella, y convierte un ImportError en un mensaje que nombre cada paso:
DEEPSPOTM_HELP = (
"DeepSpot-M no está disponible. Instálalo con `uv pip install deepspotm==1.0.0`, solicita "
"acceso a los pesos restringidos en https://huggingface.co/ratschlab/DeepSpotM, luego "
"autentícate con `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)
Fuentes de incrustación
source selecciona qué incrustación de genes congelada utiliza el enrutador para construir proyecciones. Es uno de cinco valores:
source | Incrustación de genes |
|---|---|
evo2 | secuencia genómica |
orthrus | ARN |
prott5 | secuencia de proteínas |
scgpt | expresión unicelular |
apertus | modelo de lenguaje |
Cada una proporciona una vista diferente de la identidad del gen. Elige una por ejecución y ejecuta los mismos tiles a través de más de una fuente cuando la elección sea relevante para tu análisis. Consulta references/api.md para conocer la superficie de llamadas completa, el agrupamiento en lotes y la colocación en dispositivos, el manejo de símbolos de genes y las unidades de salida.
Flujo de trabajo para portaobjetos completos
La predicción se realiza por tile, por lo que una ejecución a nivel de portaobjetos es un paso de tileado seguido de inferencia por lotes:
- Extrae tiles de 224x224 en una cuadrícula con la skill
histolab, manteniendo las coordenadas de cada tile. - Procesa y apila los tiles en lotes con
torch.stack. - Llama a
predict_genesuna vez por lote con la misma lista de genes. - Concatena los lotes en una matriz de tiles por genes y adjunta las coordenadas.
Esa matriz es el mapa de transcriptómica espacial virtual para el portaobjetos, y se integra directamente en AnnData para análisis espacial posteriores. references/whole_slide.md tiene un bucle de trabajo, tamaño de lote y un paso de ensamblaje de AnnData.
Casos de uso comunes
- Mapas de expresión espacial para genes marcadores en una sección tumoral.
- Predicción en todo el transcriptoma sobre una cohorte de portaobjetos sin un ensayo de ensayo coincidente.
- Consulta de cualquiera de los ~19,000 genes del panel por símbolo, incluidos genes no vistos en el entrenamiento, mucho más allá de los pocos cientos de genes de un panel de ensayo espacial típico.
- Agregar un canal de expresión a un pipeline de histología basado solo en morfología.
- Construir un atlas de cohorte a nivel de portaobjetos, como se hizo para TCGA.
Referencias detalladas
references/api.md:from_pretrainedypredict_genesen detalle, las cinco fuentes de incrustación y cómo elegir, agrupamiento por lotes, colocación en dispositivos, manejo de símbolos de genes y conversión de salida log1p-CPM.references/whole_slide.md: tileado con histolab, un bucle de predicción a escala de portaobjetos, ensamblaje y almacenamiento de una matriz de tiles por genes, y ejecuciones a escala de cohorte.
Fuentes primarias
- Artículo: https://doi.org/10.64898/2026.06.19.26356060 (medRxiv, publicado el 22 de junio de 2026)
- Código: https://github.com/ratschlab/DeepSpotM
- Pesos: https://huggingface.co/ratschlab/DeepSpotM
- PyPI: https://pypi.org/project/deepspotm/