Skip to content

Commit 2ff3fe6

Browse files
yousefkotpyousefkotp
committed
docs: add comprehensive README, arXiv TODO markers across repo
- Write full README with quick start, method overview, training, SLURM jobs, results table, acknowledgment, and citation - Add arXiv TODO placeholders in README, MODEL_CARD.md, CITATION.cff - Use absolute URLs for PyPI compatibility - Sync badges with HuggingFace (center-aligned, consistent set)
1 parent 8d94b5d commit 2ff3fe6

3 files changed

Lines changed: 208 additions & 0 deletions

File tree

‎CITATION.cff‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,4 +41,6 @@ preferred-citation:
4141
- family-names: Hosseini
4242
given-names: Mahdi S.
4343
orcid: "https://orcid.org/0000-0002-9147-0731"
44+
# TODO: update arXiv URL and DOI when paper is posted
45+
url: "https://arxiv.org/abs/XXXX.XXXXX"
4446
year: 2026

‎MODEL_CARD.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Model Card: MOOZY
22

3+
<!-- TODO: update arXiv URL when paper is posted -->
4+
**Paper:** [arXiv:XXXX.XXXXX](https://arxiv.org/abs/XXXX.XXXXX)
5+
36
## Model Description
47

58
MOOZY is a patient-first foundation model for computational pathology. It produces 768-dimensional embeddings at the slide and case (patient) level from whole-slide image feature grids.

‎README.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# MOOZY: A Patient-First Foundation Model for Computational Pathology
2+
3+
<!-- TODO: update arXiv URL when paper is posted -->
4+
<p align="center">
5+
<a href="https://atlasanalyticslab.github.io/MOOZY/"><img src="https://img.shields.io/badge/Project-Page-4285F4?logo=googlechrome&logoColor=white" alt="Project Page"></a>
6+
<a href="https://arxiv.org/abs/XXXX.XXXXX"><img src="https://img.shields.io/badge/arXiv-XXXX.XXXXX-B31B1B?logo=arxiv" alt="arXiv"></a>
7+
<a href="https://huggingface.co/AtlasAnalyticsLab/MOOZY"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Model-yellow" alt="HuggingFace"></a>
8+
<a href="https://pypi.org/project/moozy/"><img src="https://img.shields.io/pypi/v/moozy?logo=pypi&logoColor=white&label=PyPI" alt="PyPI"></a>
9+
<a href="https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey" alt="License"></a>
10+
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"></a>
11+
</p>
12+
13+
<p align="center">
14+
<img src="https://raw.githubusercontent.com/AtlasAnalyticsLab/MOOZY/main/assets/overview_0.5.png" alt="MOOZY: a patient-first foundation model for computational pathology, whole-slide image encoding, and case-level representation learning">
15+
</p>
16+
17+
**MOOZY is a foundation model for computational pathology that treats the patient case, not the individual slide, as the fundamental unit of representation.** It encodes one or more whole-slide images (WSIs) into a single 768-dimensional case-level embedding that captures dependencies across all slides from the same patient. Trained entirely on public data with 85.8M parameters (14x smaller than GigaPath), MOOZY outperforms larger models on classification and survival prediction tasks across diverse organs and cancer types.
18+
19+
---
20+
21+
## Table of Contents
22+
23+
- [Quick Start](#quick-start)
24+
- [Environment Setup](#environment-setup)
25+
- [Using the Output](#using-the-output)
26+
- [Method Overview](#method-overview)
27+
- [Training](#training)
28+
- [Scripts](#scripts)
29+
- [SLURM Jobs](#slurm-jobs)
30+
- [Results](#results)
31+
- [Acknowledgment](#acknowledgment)
32+
- [Citation](#citation)
33+
- [License](#license)
34+
35+
## Quick Start
36+
37+
```bash
38+
pip install moozy
39+
```
40+
41+
Model weights download automatically on first use. No access gates, no manual downloads, no HuggingFace approval.
42+
43+
```bash
44+
# Encode a patient case from pre-extracted H5 feature files
45+
moozy encode slide_1.h5 slide_2.h5 --output case_embedding.h5
46+
47+
# Encode directly from raw whole-slide images
48+
moozy encode slide_1.svs slide_2.svs --output case_embedding.h5
49+
```
50+
51+
Or use the Python API:
52+
53+
```python
54+
from moozy.encoding import run_encoding
55+
56+
run_encoding(
57+
slide_paths=["slide_1.h5", "slide_2.h5"],
58+
output_path="case_embedding.h5",
59+
)
60+
```
61+
62+
The output H5 file contains a 768-d case-level embedding ready for downstream tasks: classification, survival prediction, or retrieval.
63+
64+
All encoding arguments (data, runtime, raw WSI options, mixed precision) are documented in [docs/encode.md](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/docs/encode.md).
65+
66+
### Environment Setup
67+
68+
```bash
69+
conda create -n moozy python=3.12 -y
70+
conda activate moozy
71+
pip install moozy
72+
```
73+
74+
<details>
75+
<summary><b>venv</b></summary>
76+
77+
```bash
78+
python -m venv moozy-env
79+
source moozy-env/bin/activate
80+
pip install moozy
81+
```
82+
83+
</details>
84+
85+
<details>
86+
<summary><b>uv</b></summary>
87+
88+
```bash
89+
uv venv moozy-env
90+
source moozy-env/bin/activate
91+
uv pip install moozy
92+
```
93+
94+
</details>
95+
96+
### Using the Output
97+
98+
The output is a standard H5 file. Load it with `h5py`:
99+
100+
```python
101+
import h5py
102+
103+
with h5py.File("case_embedding.h5", "r") as f:
104+
embedding = f["features"][:] # (768,) float32 case-level embedding
105+
106+
# Use the embedding for downstream tasks
107+
# e.g., as input to a linear probe, k-NN, MLP probe, or clustering
108+
```
109+
110+
## Method Overview
111+
112+
MOOZY is a two-stage pipeline that first learns slide-level representations through self-supervised learning, then aligns them with clinical meaning through multi-task supervision.
113+
114+
**Stage 1: Self-supervised slide encoder.** A vision transformer learns context-aware spatial representations from 77,134 unlabeled public histopathology slides (~1.67 billion patches across 23 anatomical sites) using masked self-distillation. No labels are used. The slide encoder captures tissue morphology, spatial context, and inter-region relationships across the whole slide.
115+
116+
**Stage 2: Patient-aware multi-task alignment.** The pretrained slide encoder is fine-tuned end-to-end with a case transformer that models dependencies across all slides from the same patient. A learnable [CASE] token aggregates per-slide embeddings into a single case-level representation. Multi-task supervision across 333 tasks (205 classification, 128 survival) from 56 public datasets provides broad clinical grounding. All task heads are discarded after training, leaving a general-purpose patient encoder.
117+
118+
For detailed model specifications, see the [model card](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/MODEL_CARD.md).
119+
120+
## Training
121+
122+
Both training stages are fully open-source and reproducible using only public data. All training arguments (data, model, optimization, checkpointing, logging, runtime) are documented in the [Stage 1](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/docs/stage_1.md) and [Stage 2](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/docs/stage_2.md) training docs.
123+
124+
### Scripts
125+
126+
For local multi-GPU training, use the launch scripts in [`scripts/`](https://github.com/AtlasAnalyticsLab/MOOZY/tree/main/scripts):
127+
128+
```bash
129+
# Stage 1: Self-supervised pretraining
130+
GPU_IDS=0,1,2,3,4,5,6,7 bash scripts/train_stage1.sh
131+
132+
# Stage 2: Multi-task alignment
133+
GPU_IDS=0,1,2,3,4,5,6,7 bash scripts/train_stage2.sh
134+
```
135+
136+
### SLURM Jobs
137+
138+
SLURM job templates are provided in [`slurm/`](https://github.com/AtlasAnalyticsLab/MOOZY/tree/main/slurm) for cluster environments:
139+
140+
| Script | Description |
141+
|---|---|
142+
| [`slurm/single_gpu.sh`](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/slurm/single_gpu.sh) | Single-GPU training |
143+
| [`slurm/multi_gpu.sh`](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/slurm/multi_gpu.sh) | Multi-GPU training on one node |
144+
| [`slurm/multi_node.sh`](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/slurm/multi_node.sh) | Multi-node distributed training |
145+
| [`slurm/inference.sh`](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/slurm/inference.sh) | Patient encoding |
146+
147+
## Results
148+
149+
Frozen-feature MLP probe comparison against slide encoder baselines on eight held-out tasks. **Bold** indicates the best result per metric.
150+
151+
| Task | Metric | CHIEF | GigaPath | PRISM | Madeleine | TITAN | MOOZY |
152+
|---|---|---|---|---|---|---|---|
153+
| Residual Cancer Burden | F1 | 0.46 | 0.45 | 0.46 | 0.51 | 0.43 | **0.56** |
154+
| | AUC | 0.60 | 0.55 | 0.58 | 0.63 | 0.58 | **0.74** |
155+
| | Bal Acc | 0.44 | 0.40 | 0.43 | 0.48 | 0.38 | **0.51** |
156+
| TP53 Mutation | F1 | 0.82 | 0.76 | 0.85 | 0.84 | **0.87** | **0.87** |
157+
| | AUC | 0.81 | 0.76 | 0.85 | 0.85 | **0.91** | 0.86 |
158+
| | Bal Acc | 0.83 | 0.76 | 0.84 | 0.84 | **0.88** | 0.86 |
159+
| BAP1 Mutation | F1 | 0.86 | 0.84 | 0.80 | 0.85 | 0.84 | **0.89** |
160+
| | AUC | 0.75 | 0.63 | 0.71 | 0.78 | **0.82** | 0.79 |
161+
| | Bal Acc | 0.75 | 0.66 | 0.66 | 0.75 | 0.75 | **0.78** |
162+
| ACVR2A Mutation | F1 | 0.89 | 0.80 | 0.85 | 0.89 | 0.87 | **0.91** |
163+
| | AUC | 0.80 | 0.74 | 0.83 | 0.76 | 0.79 | **0.91** |
164+
| | Bal Acc | 0.80 | 0.65 | 0.81 | 0.81 | 0.76 | **0.90** |
165+
| Histologic Grade | F1 | 0.71 | 0.77 | 0.73 | 0.75 | 0.73 | **0.78** |
166+
| | AUC | 0.71 | **0.77** | 0.67 | 0.74 | 0.71 | 0.75 |
167+
| | Bal Acc | 0.73 | **0.77** | 0.73 | 0.74 | 0.73 | **0.77** |
168+
| KRAS Mutation | F1 | 0.77 | 0.77 | 0.72 | 0.81 | 0.80 | **0.85** |
169+
| | AUC | 0.76 | 0.72 | 0.61 | 0.70 | **0.80** | **0.80** |
170+
| | Bal Acc | 0.74 | 0.76 | 0.63 | 0.77 | **0.81** | 0.79 |
171+
| IDH Status | F1 | 0.92 | 0.94 | 0.91 | 0.92 | 0.94 | **0.97** |
172+
| | AUC | 0.96 | 0.97 | 0.95 | 0.96 | 0.97 | **0.99** |
173+
| | Bal Acc | 0.92 | 0.94 | 0.91 | 0.91 | 0.94 | **0.97** |
174+
| Treatment Response | F1 | 0.53 | 0.51 | 0.57 | 0.49 | 0.49 | **0.58** |
175+
| | AUC | **0.70** | 0.68 | 0.69 | 0.59 | 0.60 | 0.68 |
176+
| | Bal Acc | 0.48 | 0.40 | **0.51** | 0.35 | 0.37 | 0.48 |
177+
178+
<!-- TODO: update arXiv link when paper is posted -->
179+
<p align="center"><sub>Mean values from five-fold frozen-feature evaluation. Full results with confidence intervals are in the <a href="https://arxiv.org/abs/XXXX.XXXXX">paper</a>.</sub></p>
180+
181+
Across all eight tasks, MOOZY improves macro averages over TITAN by +7.4% weighted F1, +5.5% AUC, and +7.8% balanced accuracy, and over PRISM by +8.8% F1, +10.7% AUC, and +9.8% balanced accuracy, with 14x fewer parameters than GigaPath.
182+
183+
## Acknowledgment
184+
185+
This work was supported by NSERC-DG RGPIN-2022-05378 [M.S.H], Amazon Research Award [M.S.H], and Gina Cody RIF [M.S.H], FRQNT scholarship [Y.K]. Computational resources were provided in part by [Calcul Qu&eacute;bec](https://www.calculquebec.ca) and the [Digital Research Alliance of Canada](https://www.alliancecan.ca).
186+
187+
## Citation
188+
189+
If you find MOOZY useful, please cite:
190+
191+
<!-- TODO: update arXiv ID when paper is posted -->
192+
```bibtex
193+
@article{kotp2026moozy,
194+
title = {MOOZY: A Patient-First Foundation Model for Computational Pathology},
195+
author = {Kotp, Yousef and Trinh, Vincent Quoc-Huy and Pal, Christopher and Hosseini, Mahdi S.},
196+
journal = {arXiv preprint arXiv:XXXX.XXXXX},
197+
year = {2026}
198+
}
199+
```
200+
201+
## License
202+
203+
This project is licensed under [CC BY-NC-SA 4.0](https://github.com/AtlasAnalyticsLab/MOOZY/blob/main/LICENSE).

0 commit comments

Comments
 (0)