{"id":"deepspot-m","name":"deepspot-m","summary":"DeepSpot-Mを用いてH&E組織学からトランスクリプトーム全体の仮想空間トランスクリプトミクスを生成します。","body":"# DeepSpot-M\n\n## Overview\n\nDeepSpot-M is a multimodal foundation model that maps a 224x224 H&E histology tile to\nspatial gene expression in log1p-CPM. The output is virtual spatial transcriptomics: one\nvalue per queried gene per tile, laid out on the grid the tiles came from.\n\nA LoRA-adapted pathology foundation backbone (Midnight) tokenises the tile. A\ncross-attention gene decoder lets each gene query attend to the patch tokens, and a gene\nrouter hypernetwork builds gene-specific projections from frozen biological embeddings\n(Evo 2, Orthrus, ProtT5, scGPT, Apertus). Genes enter the model as queryable embeddings\nrather than fixed output slots, so the released model covers a ~19k protein-coding gene\npanel including genes unseen in training. The panel ships with the weights as\n`tokens.csv` and is exposed as `model.gene_names`; genes outside it cannot be queried in\nthis release.\n\nApplied to TCGA, the model produced a virtual spatial transcriptomics atlas of 28,664\nslides across 32 cancer types.\n\n## Licensing\n\nThe code is PolyForm Noncommercial 1.0.0 and the weights are CC-BY-NC-SA-4.0. Use it for\nnoncommercial research and check both licences before redistributing outputs.\n\n## Installation\n\n```bash\nuv pip install deepspotm==1.0.0\n```\n\nVersion 1.0.0 targets Python 3.10 to 3.13 and pulls in PyTorch. Install the PyTorch build\nthat matches your CUDA version first if you want GPU inference.\n\n## Model access\n\nThe weights are gated:\n\n1. Open <https://huggingface.co/ratschlab/DeepSpotM> and request access.\n2. Once access is granted, authenticate the machine that will download them:\n\n```bash\nhuggingface-cli login\n```\n\n`from_pretrained` reads that cached token, so a login is needed once per machine.\n\n## Quick start\n\n```python\nfrom deepspotm import DeepSpotM\n\nmodel, image_processor = DeepSpotM.from_pretrained(\"ratschlab/DeepSpotM\", source=\"scgpt\")\n\nvals = model.predict_genes(image_processor(pil_tile).unsqueeze(0), [\"EPCAM\", \"CD3D\"])\n```\n\n`pil_tile` is a PIL image of exactly 224x224 pixels. `image_processor` turns it into a\ntensor, `unsqueeze(0)` adds the batch dimension, and `predict_genes` takes the batch plus a\nlist of HGNC gene symbols. Values come back in log1p-CPM, aligned with the gene list you\npassed, so keep that list beside the output to keep the columns labelled. Symbols must be\nin the released ~19k-gene panel (`model.gene_names`); an unknown symbol raises `KeyError`\nnaming the offending genes.\n\n## Tile requirements\n\nTiles must be 224x224 RGB at roughly 20x magnification (about 0.5 microns per pixel). Check\nthe size at the boundary of your pipeline rather than passing an unchecked crop through:\n\n```python\nTILE_PX = 224\n\ndef require_tile(tile):\n    \"\"\"Return an RGB 224x224 tile, or raise if the crop is the wrong size.\"\"\"\n    if tile.size != (TILE_PX, TILE_PX):\n        raise ValueError(\n            f\"DeepSpot-M expects a {TILE_PX}x{TILE_PX} tile at about 20x \"\n            f\"(~0.5 microns per pixel); got {tile.size[0]}x{tile.size[1]}. \"\n            \"Re-tile at the matching level or resample the crop.\"\n        )\n    return tile.convert(\"RGB\")\n```\n\nExtract tiles at the slide level whose resolution is nearest 0.5 microns per pixel, then\ncrop to 224x224 there. Resampling from a coarser level changes the texture the backbone\nreads.\n\n## Keep the dependency optional\n\n`deepspotm` and its weights are a heavy, gated dependency. Import it inside the function\nthat needs it so the surrounding project installs, imports and tests without it, and turn\nan `ImportError` into a message that names every step:\n\n```python\nDEEPSPOTM_HELP = (\n    \"DeepSpot-M is unavailable. Install it with `uv pip install deepspotm==1.0.0`, request \"\n    \"access to the gated weights at https://huggingface.co/ratschlab/DeepSpotM, then \"\n    \"authenticate with `huggingface-cli login`.\"\n)\n\ndef load_deepspotm(source=\"scgpt\"):\n    try:\n        from deepspotm import DeepSpotM\n    except ImportError as exc:\n        raise RuntimeError(DEEPSPOTM_HELP) from exc\n    return DeepSpotM.from_pretrained(\"ratschlab/DeepSpotM\", source=source)\n```\n\n## Embedding sources\n\n`source` selects which frozen gene embedding the router builds projections from. It is one\nof five values:\n\n| `source`  | Gene embedding                    |\n| --------- | --------------------------------- |\n| `evo2`    | genomic sequence                  |\n| `orthrus` | RNA                               |\n| `prott5`  | protein sequence                  |\n| `scgpt`   | single-cell expression            |\n| `apertus` | language model                    |\n\nEach gives a different view of gene identity. Pick one per run, and run the same tiles\nthrough more than one source when the choice matters to your analysis. See\n`references/api.md` for the full call surface, batching and device placement, gene symbol\nhandling and output units.\n\n## Whole slide workflow\n\nPrediction is per tile, so a slide-scale run is a tiling step followed by batched\ninference:\n\n1. Extract 224x224 tiles on a grid with the `histolab` skill, keeping each tile's\n   coordinates.\n2. Process and stack tiles into batches with `torch.stack`.\n3. Call `predict_genes` once per batch with the same gene list.\n4. Concatenate the batches into a tiles-by-genes matrix and attach the coordinates.\n\nThat matrix is the virtual spatial transcriptomics map for the slide, and it drops\nstraight into `AnnData` for downstream spatial analysis. `references/whole_slide.md` has a\nworked loop, batch sizing and an `AnnData` assembly step.\n\n## Common use cases\n\n- Spatial expression maps for marker genes across a tumour section.\n- Transcriptome-wide prediction over a slide cohort with no matching assay run.\n- Querying any of the ~19k panel genes by symbol, including genes unseen in training —\n  far beyond the few hundred genes of a typical spatial assay panel.\n- Adding an expression channel to a morphology-only histology pipeline.\n- Building a slide-level cohort atlas, as done for TCGA.\n\n## Detailed references\n\n- `references/api.md`: `from_pretrained` and `predict_genes` in full, the five embedding\n  sources and how to choose, batching, device placement, gene symbol handling, and\n  converting log1p-CPM output.\n- `references/whole_slide.md`: tiling with histolab, a slide-scale prediction loop,\n  assembling and storing a tiles-by-genes matrix, and cohort-scale runs.\n\n## Primary sources\n\n- Paper: <https://doi.org/10.64898/2026.06.19.26356060> (medRxiv, posted 22 June 2026)\n- Code: <https://github.com/ratschlab/DeepSpotM>\n- Weights: <https://huggingface.co/ratschlab/DeepSpotM>\n- PyPI: <https://pypi.org/project/deepspotm/>","author":"@K-Dense-AI","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/deepspot-m","license":"MIT","category":"document","lang":"en","tokens":1651,"stars":0,"calls30d":0,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/api.md","size":6741,"sha256":"388a6c19861fe34338133e270fb3fdd7987d089a76495641e813776b667b941e"},{"path":"references/whole_slide.md","size":5476,"sha256":"b6ff0c36a3ea623bcd454d6a726304222db42dad90f9bcf9efb99f29cf75939c"}],"requires":{"mcp":[],"tools":["Read Write Edit Bash"]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["doi.org","huggingface.co"]}}