deepspot-m は何をしますか？
概要
DeepSpot-M は、224x224 の H&E 病理画像タイルを空間的遺伝子発現（log1p-CPM）にマッピングするマルチモーダル基盤モデルです。出力は仮想空間トランスクリプトミクスです。すなわち、タイルごとにクエリされた遺伝子ごとに1つの値が、タイルが切り出されたグリッド上に配置されます。
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 を発生させます。
タイル要件
タイルは、約20倍（約0.5ミクロン/ピクセル）の224x224 RGB でなければなりません。未確認の切り抜きをそのまま渡すのではなく、パイプラインの境界でサイズを確認してください。
TILE_PX = 224
def require_tile(tile):
"""RGB 224x224 タイルを返すか、切り抜きのサイズが間違っている場合はエラーを発生させる"""
if tile.size != (TILE_PX, TILE_PX):
raise ValueError(
f"DeepSpot-M は約20倍（~0.5ミクロン/ピクセル）の {TILE_PX}x{TILE_PX} タイルを想定しています。"
f"取得されたサイズは {tile.size[0]}x{tile.size[1]} です。"
"一致するレベルのスライドで再タイル化するか、切り抜きをリサンプリングしてください。"
)
return tile.convert("RGB")
解像度が0.5ミクロン/ピクセルに最も近いスライドレベルでタイルを抽出し、そこで224x224に切り抜いてください。粗いレベルからのリサンプリングは、バックボーンが読み取るテクスチャを変化させます。
依存関係をオプショナルに保つ
deepspotm とその重みは、重くゲート付きの依存関係です。それを必要とする関数の内部でのみインポートすることで、プロジェクト全体が 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 は、ルータープロジェクションが構築する凍結遺伝子埋め込みを選択します。以下の5つの値のいずれかです。
source | 遺伝子埋め込み |
|---|---|
evo2 | ゲノム配列 |
orthrus | RNA |
prott5 | タンパク質配列 |
scgpt | 単一細胞発現 |
apertus | 言語モデル |
それぞれが遺伝子同一性の異なる視点を提供します。実行ごとに1つを選択し、その選択が分析にとって重要な場合には、同じタイルを複数のソースで実行してください。完全な呼び出しインターフェース、バッチ処理、デバイス配置、遺伝子シンボル処理、出力単位については、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の完全な説明、5つの埋め込みソースとその選択方法、バッチ処理、デバイス配置、遺伝子シンボル処理、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/