deepspot-m

DeepSpot-M

概要

DeepSpot-M は、224x224 の H&E 組織画像タイルを log1p-CPM の空間遺伝子発現にマッピングするマルチモーダル基盤モデルです。出力は仮想空間トランスクリプトミクスであり、タイルごと・クエリした遺伝子ごとに 1 つの値が、タイルの由来するグリッド上に配置されます。

LoRA で適応させた病理基盤バックボーン (Midnight) がタイルをトークン化します。クロスアテンション型の遺伝子デコーダーにより、各遺伝子クエリがパッチトークンにアテンションを向けることができ、遺伝子ルーターハイパーネットワークが凍結された生物学的埋め込み (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 を設定してください。トークンをコードに書かないでください。承認されたローカルのモデルディレクトリはオフラインで読み込めます。

クイックスタート

説明用のゲート付き推論です。読み込み/クエリ 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 は、ルーターが射影を構築する際に使用する凍結された遺伝子埋め込みを選択します。これは 5 つの値のうちの 1 つです:

source	遺伝子埋め込み
evo2	ゲノム配列
orthrus	RNA
prott5	タンパク質配列
scgpt	単一細胞発現
apertus	言語モデル

それぞれが遺伝子アイデンティティの異なるビューを提供します。1 回の実行につき 1 つを選び、 その選択が解析にとって重要な場合は、同じタイルを複数のソースで実行してください。公開されている マルチソースモデルは model.set_source(name) を使用して切り替えることができ、再読み込みは 不要です。推論呼び出しのサーフェス、バッチ処理とデバイス配置、遺伝子シンボルの 扱い、出力単位については references/api.md を参照してください。

ホールスライドワークフロー

予測はタイル単位であるため、スライド規模の実行はタイル化ステップに続くバッチ 推論となります:

1. スライドの MPP を確認し、histolab スキルで組織グリッド上に 224x224 のタイルを抽出し、 各タイルのレベル 0 のバウンディングボックスと測定された出力 MPP を保持します。
2. torch.stack でタイルを処理してバッチにスタックします。
3. 同じ遺伝子リストでバッチごとに predict_genes を 1 回呼び出します。
4. 記録されたタイル ID の順序でバッチを連結し、それらの ID で座標を結合します。 ファイルやレポートの行順を前提とせず、一意性と欠落タイルを確認してください。

出力は、測定されたトランスクリプトカウントではなく、モデル予測としてラベル付けしてください。 対象となる組織と処理条件について、ペア測定を伴うホールドアウトスライド/患者で検証してください。 1 つのスライドのタイルは独立した生物学的リプリケートではありません。公開されている ベースモデルは、がん特異的にファインチューニングされた TCGA アトラスモデルとも異なります。

この行列がスライドの仮想空間トランスクリプトミクスマップであり、下流解析のために AnnData にそのまま投入できます。ホールスライドワークフロー には、実践的なループ、バッチサイズ、および AnnData の組み立てステップがあります。

検証範囲

2026-09-30 に、現在の PyPI 1.0.0 ホイールと一致するアップストリームモデルソースをレビューしました。 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 の全体、5 つの埋め込み ソースとその選び方、バッチ処理、デバイス配置、遺伝子シンボルの扱い、および log1p-CPM 出力の変換。
• references/whole_slide.md: histolab によるタイル化、スライド規模の予測ループ、 タイル×遺伝子行列の組み立てと保存、およびコホート規模の実行。

一次ソース

• 論文: 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/