deepspot-m

DeepSpot-M

概述

DeepSpot-M 是一个多模态基础模型，可将 224x224 的 H&E 组织学图块映射为 log1p-CPM 空间基因表达。输出为虚拟空间转录组学：每个图块中每个被查询基因对应一个值，并按照图块来源的网格进行排列。

一个经 LoRA 适配的病理学基础骨干模型（Midnight）对图块进行 tokenise。交叉注意力基因解码器让每个基因查询关注 patch token，基因路由器超网络则从冻结的生物学嵌入（Evo 2、Orthrus、ProtT5、scGPT、Apertus）构建基因特异性投影。基因以可查询嵌入而非固定输出槽位的形式进入模型，因此发布的模型覆盖约 19k 个蛋白质编码基因面板，包括训练中未见的基因。该面板随权重以 tokens.csv 形式提供，并通过 model.gene_names 暴露；此版本中无法查询该面板之外的基因。

应用于 TCGA 时，该模型生成了覆盖 32 种癌症类型、28,664 张切片的虚拟空间转录组学图谱。

许可

代码采用 PolyForm Noncommercial 1.0.0，权重采用 CC-BY-NC-SA-4.0。当前模型访问表单还额外将资格限制为无同期商业隶属关系的学术/公共非营利研究人员，并排除商业资助/合作用途。申请访问前请阅读实时声明；仅有非商业意图并不构成资格。仅供研究使用，不得用于临床或诊断用途。请保留适用的署名和许可证。

安装

uv pip install deepspotm==1.0.0

PyPI 1.0.0 声明 Python >=3.10 且无上限；这并不能证明其与未来每个依赖版本都兼容。请使用隔离环境。如果使用 GPU，请安装与你的 CUDA 运行时匹配的 PyTorch 构建。可选的 histolab 0.7.0 切片器要求 Python <3.12 以及较旧的科学计算栈：请单独运行切片，并交换 PNG 图块及坐标清单。

模型访问

权重受门控：

1. 打开 https://huggingface.co/ratschlab/DeepSpotM 并申请访问。
2. 访问获批后，对将要下载权重的机器进行身份验证：

hf auth login

Hugging Face 下载器使用缓存的凭据或 HF_TOKEN；审批与身份验证是分开的。如果选择缓存位置，请在导入 Hub 库之前设置 HF_HOME。不要将 token 放入代码中。已获批的本地模型目录可以离线加载。

快速开始

说明性门控推理；加载/查询 API 和本地预处理已在未下载权重的情况下检查：

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 将 PIL 图像转换为张量；unsqueeze(0) 添加批次维度，predict_genes 接受该批次以及一个 HGNC 基因符号列表。返回值以 log1p-CPM 表示，并与你传入的基因列表对齐，因此请将该列表与输出并列保存，以保持列标签明确。符号必须位于发布的约 19k 基因面板（model.gene_names）中；未知符号会引发 KeyError，并指出有问题的基因。

图块要求

图块必须为 224x224 RGB，放大倍率约为 20x（约每像素 0.5 微米）。请在你的流水线边界检查尺寸，而不要将未经检查的裁剪直接传入：

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

仅凭像素尺寸无法验证放大倍率。请读取两个 MPP 轴以及实际层级下采样因子；只有当某个原生层级的物理分辨率足够接近所选目标时，才使用该层级。否则，请从足够精细的源像素显式重采样并记录该变换。切勿根据层级编号推断 20x。返回的处理器会调整/裁剪图像，但无法确定其物理 MPP。

保持依赖可选

deepspotm 及其权重是沉重且受门控的依赖。请在需要它的函数内部导入，以便周边项目在缺少它时仍可安装、导入和测试，并将 ImportError 转换为说明每个步骤的消息：

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 `hf auth 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)

嵌入来源

source 用于选择路由构建投影时所基于的冻结基因嵌入。它是以下五个值之一：

source	基因嵌入
evo2	基因组序列
orthrus	RNA
prott5	蛋白质序列
scgpt	单细胞表达
apertus	大模型

每一种都给出对基因身份的不同视角。每次运行选择一种，当这一选择对你的分析重要时，可将同样的切片通过多个来源运行。已发布的多来源模型可使用 model.set_source(name) 切换；无需重新加载。 有关推理调用接口、批处理与设备放置、基因符号处理以及输出单位，请参见 references/api.md。

全切片工作流

预测是以每个切片为单位进行的，因此切片规模的运行是一个切块步骤，随后是批量推理：

1. 验证切片 MPP，使用 histolab 技能在组织网格上提取 224x224 的切片，并保留每个切片在 0 级的边界框以及实测输出 MPP。
2. 通过 torch.stack 将切片处理并堆叠为批次。
3. 每个批次使用相同的基因列表调用一次 predict_genes。
4. 按记录的切片 ID 顺序拼接批次；通过这些 ID 连接坐标，检查唯一性和缺失切片，而不是假设文件/报告的行顺序。

将输出标记为模型预测，而非实测转录本计数。在与预期组织和处理条件配对的检测中，在留出的切片/患者上进行验证；来自同一切片的切片不是独立的生物学重复。已发布的基础模型也不同于癌症特异性的微调 TCGA 图谱模型。

该矩阵就是该切片的虚拟空间转录组图谱，可直接放入 AnnData 用于下游分析。全切片工作流 包含一个完整的循环、批次大小以及 AnnData 组装步骤。

验证范围

于 2026-09-30 审查了当前的 PyPI 1.0.0 wheel 及匹配的上游模型源代码。CPU 检查使用 Python 3.12.10、Torch 2.7.1、Torchvision 0.22.1、 Transformers 5.18.0、PEFT 0.21.1、Lightning 2.6.6 和 Hugging Face Hub 1.33.0。 合成检查覆盖加载/查询契约、归一化、分辨率拒绝、坐标连接以及 H5AD 往返。受门控的权重、CUDA、真实切片切块以及生物学预测准确性未测试；完整推理示例仅作说明之用。

常见用例

• 肿瘤切片上标记基因的空间表达图谱。
• 在没有匹配检测运行的情况下，对切片队列进行转录组范围的预测。
• 通过符号查询约 19k 面板基因中的任意一个，包括训练中未见的基因 —— 远超典型空间检测面板的数百个基因。
• 为仅形态学的组织学流水线添加一个表达通道。
• 构建切片级队列图谱，如为 TCGA 所做的那样。

详细参考

• references/api.md：完整的 from_pretrained 和 predict_genes、五种嵌入来源及如何选择、批处理、设备放置、基因符号处理，以及转换 log1p-CPM 输出。
• references/whole_slide.md：使用 histolab 切块、切片规模的预测循环、组装并存储 tiles-by-genes 矩阵，以及队列规模的运行。

主要来源

• 论文：https://doi.org/10.64898/2026.06.19.26356060（medRxiv，2026）
• 代码：https://github.com/ratschlab/DeepSpotM
• 权重：https://huggingface.co/ratschlab/DeepSpotM
• PyPI：https://pypi.org/project/deepspotm/