deepspot-m 是做什么的？
概述
DeepSpot-M 是一个多模态基础模型，能够将 224x224 大小的 H&E 组织学切片映射为 log1p-CPM 格式的空间基因表达。输出结果为虚拟空间转录组：每个查询基因在每个切片中有一个对应值，并按切片来源网格排列。
该模型使用 LoRA 适配的病理基础骨干网络 (Midnight) 对切片进行标记化。交叉注意力基因解码器让每个基因查询关注切片标记，而基因路由器超网络从冻结的生物学嵌入 (Evo 2, Orthrus, ProtT5, scGPT, Apertus) 构建基因特异性投影。基因以可查询嵌入而非固定输出槽的形式输入模型，因此发布版本覆盖约 19,000 个蛋白编码基因面板，包括训练中未见过的基因。该面板随权重一起作为 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
1.0.0 版本支持 Python 3.10 至 3.13，并依赖 PyTorch。如果你希望使用 GPU 推理，请先安装与 CUDA 版本匹配的 PyTorch 构建版本。
模型访问
权重需要申请访问：
- 打开 https://huggingface.co/ratschlab/DeepSpotM 并请求访问权限。
- 获得访问权限后，在需要下载权重的机器上进行身份验证：
huggingface-cli login
from_pretrained 会读取缓存的令牌，因此每台机器只需登录一次。
快速开始
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 是一个尺寸严格为 224x224 像素的 PIL 图像。image_processor 将其转换为张量，unsqueeze(0) 添加批次维度，predict_genes 接收批次和 HGNC 基因符号列表。返回值以 log1p-CPM 格式呈现，与传入的基因列表对齐，因此请保留该列表以便于标记输出列。符号必须在发布的约 19,000 个基因面板内 (model.gene_names)；未知符号会抛出 KeyError 并指明违规基因。
切片要求
切片必须为 224x224 的 RGB 图像，放大倍数约为 20 倍（约 0.5 微米每像素）。请在管线的边界检查尺寸，而不是直接传入未检查的裁剪结果：
TILE_PX = 224
def require_tile(tile):
"""返回 RGB 224x224 切片，如果裁剪尺寸错误则抛出异常。"""
if tile.size != (TILE_PX, TILE_PX):
raise ValueError(
f"DeepSpot-M 期望 {TILE_PX}x{TILE_PX} 的切片（约 20 倍放大，"
f"~0.5 微米每像素）；实际收到 {tile.size[0]}x{tile.size[1]}。"
"请在与 0.5 微米每像素最接近的层级进行重新分块，或对裁剪结果进行重采样。"
)
return tile.convert("RGB")
在切片级别中提取分辨率最接近 0.5 微米每像素的切片，然后裁剪至 224x224。从较粗层级进行重采样会改变骨干网络读取的纹理。
将依赖项保持为可选
deepspotm 及其权重是较重且受控的依赖项。将其导入放在需要使用它的函数内部，这样周围的项目可以在没有它的情况下安装、导入和测试，并将 ImportError 转换为说明所有步骤的消息：
DEEPSPOTM_HELP = (
"DeepSpot-M 不可用。请使用 `uv pip install deepspotm==1.0.0` 安装，"
"在 https://huggingface.co/ratschlab/DeepSpotM 请求访问受控权重，"
"然后使用 `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)
嵌入来源
source 参数选择路由器用于构建投影的冻结基因嵌入。共有五个可选值：
source | 基因嵌入 |
|---|---|
evo2 | 基因组序列 |
orthrus | RNA |
prott5 | 蛋白质序列 |
scgpt | 单细胞表达 |
apertus | 语言模型 |
每种来源提供不同的基因身份视角。每次运行选择一个来源，当选择对你的分析至关重要时，可使用多个来源对相同切片运行。请参阅 references/api.md 获取完整的调用接口、批处理和设备放置、基因符号处理以及输出单位。
全切片工作流程
预测是基于切片的，因此全切片运行需要先进行分块，然后进行批量推理：
- 使用
histolab技能在网格上提取 224x224 切片，并保留每个切片的坐标。 - 使用
torch.stack处理和堆叠切片成批次。 - 每批次调用一次
predict_genes，传入相同的基因列表。 - 将所有批次拼接成一个切片 × 基因的矩阵，并附加坐标。
该矩阵即为切片的虚拟空间转录组图谱，可直接导入 AnnData 进行下游空间分析。references/whole_slide.md 提供了详细的工作循环、批大小设置以及 AnnData 组装步骤。
常见用例
- 肿瘤切片中标记基因的空间表达图谱。
- 在没有匹配实验数据的情况下，对整个切片队列进行全转录组预测。
- 按符号查询约 19,000 个面板基因中的任意一个，包括训练中未见过的基因——远超典型空间实验面板的几百个基因。
- 为仅包含形态学的组织学管线添加表达通道。
- 构建切片级别的队列图谱，如针对 TCGA 所做的研究。
详细参考
references/api.md：from_pretrained和predict_genes的完整说明、五种嵌入来源及选择方法、批处理、设备放置、基因符号处理以及 log1p-CPM 输出转换。references/whole_slide.md：使用 histolab 分块、全切片预测循环、切片 × 基因矩阵的组装和存储，以及队列级别运行。
主要来源
- 论文：https://doi.org/10.64898/2026.06.19.26356060 (medRxiv，2026 年 6 月 22 日发布)
- 代码：https://github.com/ratschlab/DeepSpotM
- 权重：https://huggingface.co/ratschlab/DeepSpotM
- PyPI：https://pypi.org/project/deepspotm/