🆕 Add DeepSpot-M model (H&E → virtual spatial transcriptomics)

[KalinNonchev]

What

Adds DeepSpot-M (Nonchev et al., medRxiv 2026) as a ModelABC in
tiatoolbox.models.architecture.deepspotm. DeepSpot-M maps a 224×224 H&E tile to
transcriptome-wide spatial gene expression via a LoRA-adapted Midnight backbone and
a cross-attention gene decoder, so one model predicts a ~19k-gene panel (and
zero-shot genes) from histology.

It runs through the existing DeepFeatureExtractor engine — each output "feature"
column is a predicted gene, so a whole-slide image yields an (n_tiles, n_genes)
expression matrix with matching tile coordinates:

from tiatoolbox.models.architecture.deepspotm import DeepSpotM
from tiatoolbox.models.engine.deep_feature_extractor import DeepFeatureExtractor

# A marker panel keeps the output lean; omit `genes` for the full ~19k-gene panel.
model = DeepSpotM(source="scgpt", genes=["EPCAM", "CD3D", "PTPRC"])
extractor = DeepFeatureExtractor(model=model, batch_size=32)
output = extractor.run(
    ["slide.svs"],
    patch_mode=False,
    patch_input_shape=(224, 224),
    input_resolutions=[{"units": "mpp", "resolution": 0.5}],
    save_dir="deepspotm_output",
)

Why DeepFeatureExtractor

DeepSpot-M is image-in and produces a per-tile vector, so it fits the
feature-extractor contract: forward returns the expression tensor and
infer_batch applies DeepSpot-M's own image transform to the NHWC patches and
returns [features]. A genes=[...] subset computes only those gene queries
(faster, and far fewer columns to store). This mirrors how the foundation tile
encoders (UNI / Virchow / H-optimus via TimmBackbone) are wired as models passed
to the engine.

Licensing / access

• Weights live in the gated ratschlab/DeepSpotM Hugging Face repo (accept the
  terms and authenticate) — consistent with the existing gated encoders (UNI,
  Virchow, …).
• License: PolyForm-Noncommercial-1.0.0 (code) + CC-BY-NC-SA-4.0 (weights) —
  research use only.
• deepspotm is an optional dependency, imported lazily with a clear install
  hint (pip install git+https://github.com/ratschlab/DeepSpotM.git). It is not yet
  on PyPI; happy to add an extras entry once it is.

Testing

• tests/models/test_arch_deepspotm.py injects a fake deepspotm module, so the
  wrapper (gene subsetting, tile preprocessing, infer_batch shape/contract, and the
  ImportError path) is exercised in CI without gated weights or the optional
  dependency.
• ruff check and ruff format are clean against the repo config.

Follow-ups (happy to add)

• An example notebook / docs entry.
• A dedicated ModelTask.spatial_transcriptomics if the maintainers prefer it over
  the feature-extractor path.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.88%. Comparing base (9a27bbb) to head (b97ca85).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1103   +/-   ##
========================================
  Coverage    99.88%   99.88%           
========================================
  Files           86       87    +1     
  Lines        11670    11710   +40     
  Branches      1533     1537    +4     
========================================
+ Hits         11657    11697   +40     
  Misses           7        7           
  Partials         6        6           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[shaneahmed]

Thanks @KalinNonchev Please can you also add a Jupyter Notebook? You can use one of the existing inference pipelines (https://github.com/TissueImageAnalytics/tiatoolbox/tree/develop/examples/inference-pipelines) Jupyter Notebooks as a template.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[KalinNonchev]

Thanks @shaneahmed, added in 3ba95fb.

examples/inference-pipelines/deepspotm.ipynb, using idars.ipynb as the template: Colab badge, remove-cell setup and environment cells, device selection, tmp/ cleanup, and the same TCGA sample slide the other inference-pipeline notebooks download.

It builds a DeepSpotM restricted to three marker genes, runs it over the WSI through DeepFeatureExtractor with an IOPatchPredictorConfig at 224x224 and 0.5 mpp, reads the (n_tiles, n_genes) matrix back out of the zarr output, and overlays the predicted expression on the slide thumbnail. EPCAM, PTPRC and COL1A1 each report on a different compartment (epithelium, immune infiltrate, stroma), so the overlay reads as a sanity check rather than three similar-looking maps. It closes with the genes=None full-panel form plus the citation and licence terms.

The committed outputs are from a real run rather than a cleared notebook: 6,467 tissue tiles scored on one GPU, roughly 16 minutes end to end including the slide download and the gated-weight load.

I also added the entry to the Inference Pipelines section of examples/README.md with a thumbnail at docs/images/deepspotm.png, matching the format of the other two.

ruff check, ruff format and the notebook-markdown-format pre-commit hook are all clean against the repo config.

Two notes in case they matter for review:

• The Colab bootstrap cell installs deepspotm from git, since it is not on PyPI yet. I have a PR open on our side to fix the packaging and add a release workflow, so once it is published I am happy to switch that cell to pip install deepspotm and add the extras entry I mentioned in the PR description.
• Running the notebook needs access to the gated ratschlab/DeepSpotM weights, so it cannot execute unattended in CI. That matches the other gated encoders, but flagging it explicitly since this notebook downloads weights rather than using a TIAToolbox-hosted checkpoint.

[KalinNonchev]

@Jiaqi-Lv just approved your HF request. Please let me know if you need anything else.

[Jiaqi-Lv]

Looks great. I'm reviewing this PR.

@Jiaqi-Lv just approved your HF request. Please let me know if you need anything else.

Thank you! I'll review this soon.

[Jiaqi-Lv]

I've made some minor changes:

• Switch the demo slide from the large WSI to wsi4_12k_12k.svs.
• Reorder setup so Hugging Face auth comes before sample download, and note that auth can be skipped when using local weights.
• Replace scatter-point overlays with a tile-grid heatmap.

[Jiaqi-Lv]

Looks good, works well for me.

[KalinNonchev]

Merge? @Jiaqi-Lv