README.md

---
license: cc-by-nc-4.0
tags:
  - biology
  - histopathology
  - cell-type-annotation
  - spatial-transcriptomics
  - visium
  - xenium
  - codex
  - LUAD
  - GBM
  - kidney
  - atherosclerosis
  - H&E
library_name: pytorch
---

# MeowCat-Models

Trained model weights for [**MeowCat**](https://github.com/liranmao/MeowCat)
(Multi-resolution Omics-informed Whole-slide Cell Annotation Tool), a deep
learning framework that predicts cell-type distributions on H&E whole-slide
images using spatially-registered transcriptomics / multiplexed protein
imaging as supervision.

Source code: https://github.com/liranmao/MeowCat

MeowCat also ships AI-assistant utilities — Claude Code skills
(`/meowcat-setup`, `/meowcat-check`) and reusable prompts for Codex / Cursor
— that automate configuration, input validation, and pipeline execution. See
[AI tools](https://github.com/liranmao/MeowCat#ai-tools).

## Repo layout

```
MeowCat-Models/
├── README.md
├── luad_general_celltype/states/   # LUAD coarse 8-class
├── luad_refined_celltype/states/   # LUAD fine 17-class
├── gbm_codex_celltype/states/      # GBM 14-class (CODEX-supervised)
├── kidney_celltype/states/         # Kidney
└── athero_celltype/states/         # Atherosclerosis 8-class
```

Each `states/` folder contains the ensemble replicas (`00/`, `01/`, ...).
Each replica contains `model.ckpt` and the per-phase subfolders
(`recon_phase`, `visium_phase`, `xenium_phase`) produced by MeowCat's
multi-phase training.

## Models

### `luad_general_celltype` — LUAD coarse 8-class

```
B, Plasma, Myeloid, Stromal, NonTumor_Epi, Tumor_Epi, T, NK
```

Recommended when downstream analyses only need broad lineage categories.

### `luad_refined_celltype` — LUAD fine 17-class

```
B, CD_cDC, Endo, Fibroblast, iCAF, Macro_alveolar, Macro_TAM, Mast,
Mural, myCAF, Neutrophil, NK, NonTumor_Epi, Plasma, T_CD4, T_CD4_Treg,
T_CD8, Tumor_Epi
```

Recommended for TME-resolved analyses (CAF subtypes, T-cell subsets,
macrophage polarization, etc.).

### `gbm_codex_celltype` — GBM CODEX 14-class

```
AC, MES, MES-Hyp, NPC, OPC, Chromatin-Reg,
Mac, Inflammatory-Mac, T-cell, B-cell,
Neuron, Oligo, Reactive-Ast, Vasc
```

### `kidney_celltype` — Kidney

Trained with the same MeowCat pipeline on kidney H&E + spatial data. See
the MeowCat repo for the cell-type vocabulary and dataset details.

### `athero_celltype` — Atherosclerosis 8-class

```
Endothelial, Inflammatory, Macrophage, Mast, Neutrophil, Plasma, T, VSMC
```

Trained on human atherosclerotic plaque (paired healthy / diseased regions),
Xenium-only supervision.

## Training data

- **LUAD** — 21 Visium sections (238,488 spots, RCTD soft labels) + 4 Xenium
  sections (2,047,381 cells, hard labels). Held out: S1, P24.
  Source: [Cancer Cell 2025](https://www.cell.com/cancer-cell/fulltext/S1535-6108(25)00445-3).
- **GBM (CODEX)** — 12 IDH-wildtype GBM sections, CODEX → H&E via Warpy.
  CLS-only (no transcriptomics). Held out: ZH1007_INF, C_1.
  Source: [Cell 2024](https://www.cell.com/cell/fulltext/S0092-8674(24)00320-9).
- **Kidney** — see the MeowCat repo for details.
  Source: [Nature 2026](https://www.nature.com/articles/s41586-026-10363-4).
- **Atherosclerosis** — 8 Xenium sections (21,237 cells, hard labels) across
  4 patients with paired healthy/diseased plaque regions. 8 additional Xenium
  sections held out for prediction-only evaluation. Unpublished.

## Architecture

Please see the [MeowCat repo](https://github.com/liranmao/MeowCat) for details.

## Usage

### Download

```python
from huggingface_hub import snapshot_download

local = snapshot_download(
    repo_id="liranmao/MeowCat-Models",
    repo_type="model",
    token=True,  # required while the repo is private
)
# weights, e.g.:
#   f"{local}/luad_general_celltype/states/00/model.ckpt"
#   f"{local}/gbm_codex_celltype/states/00/model.ckpt"
```

To grab only one sub-model:

```python
local = snapshot_download(
    repo_id="liranmao/MeowCat-Models",
    repo_type="model",
    allow_patterns=["gbm_codex_celltype/*", "README.md"],
    token=True,
)
```

### Predict on a new H&E slide

Place the downloaded `states/` folder under your MeowCat run's
`output/batches/states`, then run:

```bash
meowcat predict --config config.yaml
meowcat visualize --config config.yaml
```

See `examples/06_predict_new_sample/` in the MeowCat repo for an end-to-end
prediction-only workflow.

## License

CC BY-NC 4.0 — research / non-commercial use only. Source-data restrictions
from the underlying studies may apply; please consult the original
publications before redistributing predictions.

## Citation

If you use these weights, please cite both MeowCat and the source datasets:

```bibtex
@software{meowcat,
  title  = {MeowCat: Multi-resolution Omics-informed Whole-slide Cell Annotation Tool},
  author = {Mao, Liran and contributors},
  year   = {2026},
  url    = {https://github.com/liranmao/MeowCat}
}
```

- LUAD: [Cancer Cell 2025 — S1535-6108(25)00445-3](https://www.cell.com/cancer-cell/fulltext/S1535-6108(25)00445-3)
- GBM: [Cell 2024 — S0092-8674(24)00320-9](https://www.cell.com/cell/fulltext/S0092-8674(24)00320-9)
- Kidney: [Nature 2026 — s41586-026-10363-4](https://www.nature.com/articles/s41586-026-10363-4)
- Atherosclerosis: unpublished