用途
DeepSpot-M 用于从 H&E 组织学图像生成转录组范围的虚拟空间转录组学数据。它将一个 224x224 的 H&E 组织学瓦片映射为 log1p-CPM 尺度的空间基因表达：每个查询基因在每个瓦片上输出一个值，并按瓦片来源的网格排列。该技能适用于为肿瘤切片生成标记基因的空间表达图、在无配对检测的切片队列上做转录组范围预测、为仅形态学的组织学流程添加表达通道，以及构建切片级队列图谱（如 TCGA 所做）。
主要能力
模型核心是多模态基础模型，包含 LoRA 适配的病理基础骨干网络（Midnight）对瓦片进行 token 化，交叉注意力基因解码器使每个基因查询能够关注 patch token，基因路由超网络从冻结的生物学嵌入构建基因特异性投影。生物学嵌入共五种，由 source 参数选择：evo2（基因组序列）、orthrus（RNA）、prott5（蛋白序列）、scgpt（单细胞表达）、apertus（语言模型）。每种提供不同的基因身份视角。发布的模型覆盖约 1.9 万个蛋白编码基因面板，面板以 tokens.csv 随权重发布，并通过 model.gene_names 暴露。基因以可查询嵌入而非固定输出槽进入模型，因此该面板包含训练中未见的基因；面板之外的基因在此版本中无法查询。发布的多样本模型可通过 model.set_source(name) 切换嵌入来源，无需重新加载。应用于 TCGA 时，模型生成了覆盖 32 种癌症类型、28,664 张切片的虚拟空间转录组图谱。
使用方式
安装：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 瓦片与坐标清单。
权重受门控：打开 https://huggingface.co/ratschlab/DeepSpotM 请求访问，获准后对将下载权重的机器进行认证：hf auth login。Hugging Face 下载器使用缓存凭据或 HF_TOKEN；批准与认证是分开的。如选择缓存位置，在导入 Hub 库前设置 HF_HOME。不要把令牌放进代码。已批准的本地模型目录可离线加载。
快速开始示例（受门控的推理示意；加载/查询 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 单位返回，与所传基因列表对齐，因此请将列表与输出放在一起以保持列标签。符号必须位于发布的约 1.9 万基因面板（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)
全切片工作流：预测按瓦片进行，因此切片级运行是分块步骤加批量推理。1）验证切片 MPP，使用 histolab 技能在组织网格上提取 224x224 瓦片，并保留每个瓦片的 level-0 边界框和实测输出 MPP。2）用 torch.stack 处理并堆叠瓦片为批次。3）每批用相同基因列表调用一次 predict_genes。4）按记录的瓦片 ID 顺序拼接批次；按这些 ID 连接坐标，检查唯一性与缺失瓦片，而非假定文件/报告行顺序。5）保持输出标记为模型预测而非实测转录本计数。需在留出切片/患者上用配对检测验证目标组织与处理条件；来自同一张切片的瓦片不是独立的生物学重复。发布的基模型也不同于癌症特异性微调的 TCGA 图谱模型。该矩阵即切片的虚拟空间转录组图谱，可导入 AnnData 用于下游分析。references/whole_slide.md 提供了完整循环、批次大小与 AnnData 组装步骤。
详细参考：references/api.md 涵盖 from_pretrained 与 predict_genes 的完整调用面、五种嵌入来源及选择方式、批处理、设备放置、基因符号处理和 log1p-CPM 输出转换。
适用场景
适用于肿瘤切片标记基因的空间表达图；无配对检测的切片队列转录组范围预测；按符号查询约 1.9 万面板基因（含训练未见基因），远超典型空间检测面板的数百个基因；为仅形态学组织学流程添加表达通道；构建切片级队列图谱。
限制
许可方面：代码为 PolyForm Noncommercial 1.0.0，权重为 CC-BY-NC-SA-4.0。当前模型访问表单额外限制资格为无同期商业隶属的学术/公共非营利研究人员，并排除商业资助/合作使用。请求访问前请阅读实时声明；仅凭非商业意图不足以确立资格。仅限研究用途，不得用于临床或诊断。请保留适用的署名与许可。
验证范围：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、真实切片分块和生物学预测准确性未测试；完整推理示例为示意性质。