# Deepspot M

> Genera transcriptómica espacial virtual de todo el transcriptoma a partir de histología H&E con DeepSpot-M: expresión génica en log1p-CPM por tile de 224x224 a ~20x, consultando genes por símbolo.

Fuente: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/deepspot-m
Markdown: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/deepspot-m.md

Repositorio: https://github.com/K-Dense-AI/scientific-agent-skills
Autor: K-Dense-AI
Licencia: PolyForm-Noncommercial-1.0.0
Actualizado: hace 21 días
Coste de contexto: 82 tok instalada, 1.8k tok al activarse, 4.9k tok con todos los archivos del bundle
Bundle: 3 archivos, 19 KB
Permisos que pide: read write edit bash

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add K-Dense-AI/scientific-agent-skills --skill deepspot-m --agent claude-code
# Cursor
npx -y skills add K-Dense-AI/scientific-agent-skills --skill deepspot-m --agent cursor
# Codex
npx -y skills add K-Dense-AI/scientific-agent-skills --skill deepspot-m --agent codex
# Gemini CLI
npx -y skills add K-Dense-AI/scientific-agent-skills --skill deepspot-m --agent gemini
# Windsurf
npx -y skills add K-Dense-AI/scientific-agent-skills --skill deepspot-m --agent windsurf
# Cline
npx -y skills add K-Dense-AI/scientific-agent-skills --skill deepspot-m --agent cline
```

## Qué hace

- Predice expresión génica espacial (log1p-CPM) por tile de histología H&E de 224x224 a ~20x con el modelo DeepSpot-M
- Permite consultar genes por símbolo HGNC en un panel de ~19k genes codificantes, incluidos genes no vistos en entrenamiento
- Ofrece cinco fuentes de embedding génico (evo2, orthrus, prott5, scgpt, apertus) para construir las proyecciones del gen
- Encadena tiling con histolab e inferencia por lotes para generar un mapa transcriptómico virtual de un slide completo
- Descarga los pesos gated de Hugging Face (ratschlab/DeepSpotM) tras solicitar acceso y autenticar con huggingface-cli

## Cuándo usarla

- Se necesita expresión génica espacial para tiles de 224x224 a ~20x (~0.5 micras por pixel)
- Se quiere consultar genes por símbolo en vez de un panel fijo de un ensayo espacial
- Se quiere ejecutar predicción sobre un slide completo tras hacer tiling con histolab
- Se está construyendo un atlas transcriptómico virtual a nivel de cohorte de slides

## Cuándo no

- No usarlo para fines comerciales sin revisar antes las licencias (código PolyForm Noncommercial, pesos CC-BY-NC-SA)

## Qué la activa

- "Predice la expresión espacial de EPCAM y CD3D en este tile de histología"
- "Genera un mapa transcriptómico virtual de este slide completo con DeepSpot-M"
- "Consulta genes por símbolo en vez de usar un panel espacial fijo"

## Antes de instalar

- Necesita el paquete deepspotm 1.0.0 (PyPI, Python 3.10-3.13) con PyTorch, y acceso a los pesos gated de ratschlab/DeepSpotM en Hugging Face vía huggingface-cli login; se recomienda GPU CUDA.
- makes network requests

## Archivos

- SKILL.md — 7 KB
- references/api.md — 7 KB
- references/whole_slide.md — 5 KB

## SKILL.md

Reproducido tal cual desde K-Dense-AI/scientific-agent-skills bajo PolyForm-Noncommercial-1.0.0. Esta sección es el documento original y está en inglés.

# DeepSpot-M

## Overview

DeepSpot-M is a multimodal foundation model that maps a 224x224 H&E histology tile to
spatial gene expression in log1p-CPM. The output is virtual spatial transcriptomics: one
value per queried gene per tile, laid out on the grid the tiles came from.

A LoRA-adapted pathology foundation backbone (Midnight) tokenises the tile. A
cross-attention gene decoder lets each gene query attend to the patch tokens, and a gene
router hypernetwork builds gene-specific projections from frozen biological embeddings
(Evo 2, Orthrus, ProtT5, scGPT, Apertus). Genes enter the model as queryable embeddings
rather than fixed output slots, so the released model covers a ~19k protein-coding gene
panel including genes unseen in training. The panel ships with the weights as
`tokens.csv` and is exposed as `model.gene_names`; genes outside it cannot be queried in
this release.

Applied to TCGA, the model produced a virtual spatial transcriptomics atlas of 28,664
slides across 32 cancer types.

## Licensing

The code is PolyForm Noncommercial 1.0.0 and the weights are CC-BY-NC-SA-4.0. Use it for
noncommercial research and check both licences before redistributing outputs.

## Installation

```bash
uv pip install deepspotm==1.0.0
```

Version 1.0.0 targets Python 3.10 to 3.13 and pulls in PyTorch. Install the PyTorch build
that matches your CUDA version first if you want GPU inference.

## Model access

The weights are gated:

1. Open <https://huggingface.co/ratschlab/DeepSpotM> and request access.
2. Once access is granted, authenticate the machine that will download them:

```bash
huggingface-cli login
```

`from_pretrained` reads that cached token, so a login is needed once per machine.

## Quick start

```python
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` is a PIL image of exactly 224x224 pixels. `image_processor` turns it into a
tensor, `unsqueeze(0)` adds the batch dimension, and `predict_genes` takes the batch plus a
list of HGNC gene symbols. Values come back in log1p-CPM, aligned with the gene list you
passed, so keep that list beside the output to keep the columns labelled. Symbols must be
in the released ~19k-gene panel (`model.gene_names`); an unknown symbol raises `KeyError`
naming the offending genes.

## Tile requirements

Tiles must be 224x224 RGB at roughly 20x magnification (about 0.5 microns per pixel). Check
the size at the boundary of your pipeline rather than passing an unchecked crop through:

```python
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")
```

Extract tiles at the slide level whose resolution is nearest 0.5 microns per pixel, then
crop to 224x224 there. Resampling from a coarser level changes the texture the backbone
reads.

## Keep the dependency optional

`deepspotm` and its weights are a heavy, gated dependency. Import it inside the function
that needs it so the surrounding project installs, imports and tests without it, and turn
an `ImportError` into a message that names every step:

```python
DEEPSPOTM_HELP = (
    "DeepSpot-M is unavailable. Install it with `uv pip install deepspotm==1.0.0`, request "
    "access to the gated weights at https://huggingface.co/ratschlab/DeepSpotM, then "
    "authenticate with `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 sources

`source` selects which frozen gene embedding the router builds projections from. It is one
of five values:

| `source`  | Gene embedding                    |
| --------- | --------------------------------- |
| `evo2`    | genomic sequence                  |
| `orthrus` | RNA                               |
| `prott5`  | protein sequence                  |
| `scgpt`   | single-cell expression            |
| `apertus` | language model                    |

Each gives a different view of gene identity. Pick one per run, and run the same tiles
through more than one source when the choice matters to your analysis. See
`references/api.md` for the full call surface, batching and device placement, gene symbol
handling and output units.

## Whole slide workflow

Prediction is per tile, so a slide-scale run is a tiling step followed by batched
inference:

1. Extract 224x224 tiles on a grid with the `histolab` skill, keeping each tile's
   coordinates.
2. Process and stack tiles into batches with `torch.stack`.
3. Call `predict_genes` once per batch with the same gene list.
4. Concatenate the batches into a tiles-by-genes matrix and attach the coordinates.

That matrix is the virtual spatial transcriptomics map for the slide, and it drops
straight into `AnnData` for downstream spatial analysis. `references/whole_slide.md` has a
worked loop, batch sizing and an `AnnData` assembly step.

## Common use cases

- Spatial expression maps for marker genes across a tumour section.
- Transcriptome-wide prediction over a slide cohort with no matching assay run.
- Querying any of the ~19k panel genes by symbol, including genes unseen in training —
  far beyond the few hundred genes of a typical spatial assay panel.
- Adding an expression channel to a morphology-only histology pipeline.
- Building a slide-level cohort atlas, as done for TCGA.

## Detailed references

- `references/api.md`: `from_pretrained` and `predict_genes` in full, the five embedding
  sources and how to choose, batching, device placement, gene symbol handling, and
  converting log1p-CPM output.
- `references/whole_slide.md`: tiling with histolab, a slide-scale prediction loop,
  assembling and storing a tiles-by-genes matrix, and cohort-scale runs.

## Primary sources

- Paper: <https://doi.org/10.64898/2026.06.19.26356060> (medRxiv, posted 22 June 2026)
- Code: <https://github.com/ratschlab/DeepSpotM>
- Weights: <https://huggingface.co/ratschlab/DeepSpotM>
- PyPI: <https://pypi.org/project/deepspotm/>

## Dónde encaja

- Categoría: [Investigación](https://skillsagentes.com/categorias/investigacion.md) — Investigación estructurada, búsqueda de fuentes y síntesis.
- Creador: [K-Dense-AI](https://skillsagentes.com/creators/k-dense-ai.md) — 163 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Citation Management](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/citation-management.md): Gestión integral de citas académicas: busca en OpenAlex, PubMed y Google Scholar, extrae metadatos precisos, valida citas y genera entradas BibTeX correctamente formateadas.
- [Scientific Slides](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/scientific-slides.md): Crea decks de diapositivas y presentaciones para charlas de investigación: PowerPoint, presentaciones de conferencia, seminarios, defensas de tesis. Da estructura, plantillas, guía de tiempos y validación visual.
- [Literature Review](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/literature-review.md): Realiza revisiones bibliográficas sistemáticas y completas usando varias bases académicas (PubMed, arXiv, bioRxiv, Semantic Scholar). Genera markdown y PDF con citas verificadas en varios estilos (APA, Nature, Vancouver).
- [Infographics](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/infographics.md): Crea infografías profesionales con Nano Banana Pro AI y refinamiento iterativo inteligente. Usa Gemini 3.6 Flash para revisar la calidad e integra investigación con Perplexity Sonar. Soporta 10 tipos, 8 estilos y paletas para daltonismo.
- [Latex Posters](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/latex-posters.md): Crea pósteres de investigación profesionales en LaTeX con beamerposter, tikzposter o baposter, para conferencias y comunicación científica: layout, colores, columnas múltiples e integración de figuras.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)