Ace3Z commited on
Commit
ef50b39
·
verified ·
1 Parent(s): cb57b1d

docs: rewrite the model card in the style of the original

Browse files

Shorter and direct: what the work is, the headline numbers, what is here, requirements, one verified usage block, licence and citation.

The usage block now fetches file by file. snapshot_download with allow_patterns skips LFS files on the pinned huggingface-hub 1.7.1, so the previous snippet returned an empty directory and no checkpoint.

Files changed (1) hide show
  1. README.md +68 -211
README.md CHANGED
@@ -13,22 +13,16 @@ tags:
13
 
14
  # GrapHist++: Edge-Informed Graph Self-Supervised Learning for Histopathology
15
 
16
- GrapHist++ encodes a histopathology tile as a **cell graph** (one node per nucleus, edges
17
- from a Delaunay triangulation pruned at 100 µm) and embeds it with a self-supervised
18
- **ACM-GINEConv** encoder. It extends [GrapHist](https://huggingface.co/ogutsevda/graphist)
19
- ([arXiv:2603.00143](https://arxiv.org/abs/2603.00143)) by making the **edges carry
20
- information**: each edge holds a 75-dimensional descriptor of the tissue between two cells,
21
- and the encoder injects those features into message passing instead of treating edges as mere
22
- connectivity.
23
 
24
- **Trained on 11,149,499 cell graphs from TCGA-BRCA**, 100 epochs, batch 2048, no labels. The
25
- objective is GraphMAE-style masked node-feature reconstruction (mask 50 %, scaled cosine
26
- error, α = 3) plus a **VICReg** variance/covariance term on the pooled graph embedding, which
27
- keeps all embedding dimensions in use (final `pca_1` 0.17, effective dimension 11.9).
28
-
29
- Encoder 7.98 M parameters (9.29 M on the inference path, which also runs the projection;
30
- 10.53 M for the full pre-training model), 512-dim embeddings, 0.093 ms/patch at batch 48 on an
31
- H200.
32
 
33
  ## Results
34
 
@@ -36,73 +30,64 @@ Slide-level MIL, transfer to unseen cohorts (test macro-F1 %, best of three MIL
36
 
37
  | | BRACS | BreakHis | BACH |
38
  |---|:--:|:--:|:--:|
39
- | GrapHist (v1) | 60.30 | 89.37 | **69.16** |
40
  | **GrapHist++** | **69.00** | **95.53** | 68.98 |
41
 
42
- Survival on TCGA-BRCA (Cox PH, C-index): **0.793**, vs 0.763 for v1, 0.724 MAE, 0.632 DINOv2.
43
- [`DATA.md`](DATA.md) maps every artifact here to the result it reproduces. It carries the
44
- artifacts and the evaluation protocol for cell-type identification and patch-level subtyping,
45
- and the AdapterGNN fine-tuning table, which is GrapHist v1; the GrapHist++ macro-F1 for those
46
- two tasks is reported in the paper rather than here.
 
47
 
48
- ## What's in this repo
49
 
50
  ```
51
- graphist_v2.pt the model. 126,597,010 B, md5 81a2e6b91cefff0bbbc13c6fd318ee78
52
- modeling/ code to load and run it, plus the graph-path helper
53
- graphs/ cell graphs: TCGA-BRCA (11.1 M, pre-training), BACH, BRACS,
54
- BreakHis, SPIDER-breast
55
- embeddings/ embeddings from this model: slide-level (4 cohorts), cell-level (22 sets)
56
- baselines/ DINOv2, MAE and GrapHist v1 features for the comparison rows
57
- labels/ TCGA-BRCA clinical table and slide labels
58
- studies/ data for the side analyses: homophily, AdapterGNN, preprocessing runtime
59
- upstream_v1/ mirror of the original GrapHist v1 releases
60
  ```
61
 
62
- To run the model on your own graphs you need only `graphist_v2.pt` and `modeling/`. To
63
- reproduce a published number you also need that dataset's `normalization.json` from
64
- `graphs/<cohort>/`, since the transforms are part of the pipeline. See [`DATA.md`](DATA.md).
65
-
66
- Training, evaluation and analysis code lives in
67
- [github.com/Ace3Z/GrapHist-V2](https://github.com/Ace3Z/GrapHist-V2).
68
 
69
- > ⚠️ **If you use `graphs/`, run `modeling/rebase_graph_paths.py` first.** The label CSVs store
70
- > bare filenames and the loader resolves them against the working directory, so without this
71
- > step every graph is silently dropped. `DATA.md` has the commands and the expected counts.
72
 
73
- ## Usage
74
-
75
- ```python
76
- from huggingface_hub import snapshot_download
77
-
78
- # The whole repository is ~1.05 TB, so fetch only what you need.
79
- path = snapshot_download(repo_id="Ace3Z/graphist-v2",
80
- allow_patterns=["graphist_v2.pt", "modeling/*", "*.md"])
81
  ```
82
 
83
- Sizes, so nothing surprises you: `graphs/tcga_brca` 652 GB, `upstream_v1` 273 GB,
84
- `baselines` 78 GB, `embeddings/slide` 26 GB, everything else under 7 GB each. The tars are
85
- uncompressed, so extracting TCGA-BRCA costs another ~650 GB on top. Following `DATA.md`
86
- end to end needs roughly 1.7 TB of free space; the checkpoint alone is 127 MB.
87
-
88
- Three arguments are **load-critical**. `build_model` reads two of them with defaults that do
89
- not match this checkpoint, and the third has no default at all:
90
 
91
- | Argument | Must be | If wrong |
92
- |---|---|---|
93
- | `edge_distance_in_proj` | `False` | `edge_input_proj` built as (512, **75**); checkpoint has (512, **74**) |
94
- | `encoder_norm` | `"layer"` | `encoder.layer_norms.*` missing from the model |
95
- | `concat_hidden` | `True` | `AttributeError` if omitted; (512, 512) instead of (512, **2560**) if `False` |
96
 
97
  ```python
98
- import sys, torch
 
 
 
 
 
 
 
 
 
 
 
99
  sys.path.insert(0, f"{path}/modeling")
100
  from models import build_model
101
 
102
  class Args:
103
  encoder = decoder = "acm_gineconv"
104
- num_features = 96 # per-cell features
105
- num_edge_features = 75 # per-edge features (projection sees 74; distance excluded)
106
  num_hidden = 512
107
  num_layers = 5
108
  concat_hidden = True # load-critical
@@ -122,166 +107,38 @@ class Args:
122
 
123
  model = build_model(Args())
124
  ckpt = torch.load(f"{path}/graphist_v2.pt", map_location="cpu", weights_only=False)
125
- model.load_state_dict(ckpt["model_state_dict"], strict=True) # note the key name
126
  model.eval()
127
 
128
- # x: [num_nodes, 96] edge_index: [2, num_edges] edge_attr: [num_edges, 75]
129
- # batch: [num_nodes] graph assignment (zeros for a single graph)
130
  with torch.no_grad():
131
- node_emb = model.embed(x, edge_index, edge_attr, batch) # -> [num_nodes, 512]
132
  ```
133
 
134
- Region- and slide-level embeddings are means over node embeddings. To match the published
135
- numbers, apply the transforms used at training time: `NormalizeData` with the dataset's
136
- `normalization.json`, then `AddVirtualNode`. Both are in `modeling/graphist_utils.py`.
137
-
138
- ### Requirements
139
-
140
- Inference needs only `torch`, `torch_geometric`, `numpy` and `pandas`.
141
-
142
- | | Trained with | Also verified on |
143
- |---|---|---|
144
- | Python | 3.10 | 3.10 |
145
- | torch | 2.2.2 (CUDA 11.8) | 2.10.0 (CUDA 12.8) |
146
- | torch_geometric | 2.5.2 | 2.7.0 |
147
- | numpy | 1.26.4 | 2.2.6 |
148
- | pandas | 2.2.2 | 2.3.3 |
149
-
150
- Tested at both ends of that range, and on both numpy 1.x and 2.x. Newer versions also work;
151
- these are floors, not a supported ceiling. CPU-only inference works.
152
-
153
- Using the released data needs a little more: `h5py` (the embedding files are HDF5),
154
- `scikit-learn` 1.5+ for the cell-level probe, and `lifelines` 0.30 for the survival analysis.
155
-
156
- > `modeling/models/acm_gin.py` is required even though this model never uses it:
157
- > `edcoder.py` imports it at module level.
158
-
159
- ## Graph format
160
-
161
- | Tensor | Shape | Meaning |
162
- |---|---|---|
163
- | `x` | `[num_nodes, 96]` | per-cell morphology, texture and colour features |
164
- | `edge_index` | `[2, num_edges]` | Delaunay edges, pruned at 100 µm |
165
- | `edge_attr` | `[num_edges, 75]` | column 0 = centroid distance (µm); 1–74 describe the inter-cellular region |
166
-
167
- The v1 releases use a 1-dimensional `edge_attr` (distance only) and are **not** interchangeable
168
- with this model in either direction.
169
-
170
- ## Verification
171
-
172
- `build_model` + `load_state_dict(strict=True)` returns 0 missing / 0 unexpected keys using only
173
- the files shipped here. All 397 BACH slide embeddings regenerate from this checkpoint at
174
- minimum cosine similarity **0.9999999997** against the published set. As a control, a
175
- different checkpoint scores 0.256 mean cosine on the same comparison, so the test discriminates
176
- and these weights are the ones behind the released embeddings.
177
-
178
- ## Datasets used
179
-
180
- This release is built from seven public cohorts. If you use it, please cite GrapHist **and**
181
- the source cohort(s) your work touches.
182
-
183
- | Cohort | Used for | Source |
184
- |---|---|---|
185
- | **TCGA-BRCA** | pre-training (11.1 M graphs), slide-level evaluation, survival | [GDC Data Portal](https://portal.gdc.cancer.gov/) |
186
- | **BACH** (ICIAR 2018) | slide-level subtyping, homophily | [Grand Challenge](https://iciar2018-challenge.grand-challenge.org/) |
187
- | **BRACS** | slide-level subtyping, homophily | [bracs.icar.cnr.it](https://www.bracs.icar.cnr.it/) |
188
- | **BreakHis** | slide-level subtyping, homophily | [P&D Lab, UFPR](https://web.inf.ufpr.br/vri/databases/breast-cancer-histopathological-database-breakhis/) |
189
- | **NuCLS** | cell-type identification, homophily | [NuCLS](https://sites.google.com/view/nucls/home) |
190
- | **PanNuke** | cell-type identification, homophily | [TIA Centre, Warwick](https://warwick.ac.uk/fac/sci/dcs/research/tia/data/pannuke/) |
191
- | **SPIDER-breast** | patch-level subtyping | [histai/SPIDER-breast](https://huggingface.co/datasets/histai/SPIDER-breast) |
192
-
193
- <details>
194
- <summary>BibTeX for the source cohorts</summary>
195
-
196
- ```bibtex
197
- @article{weinstein2013cancer,
198
- title={The cancer genome atlas pan-cancer analysis project},
199
- author={Weinstein, John N and Collisson, Eric A and Mills, Gordon B and Shaw, Kenna R and
200
- Ozenberger, Brad A and Ellrott, Kyle and Shmulevich, Ilya and Sander, Chris and
201
- Stuart, Joshua M},
202
- journal={Nature Genetics}, volume={45}, number={10}, pages={1113--1120}, year={2013},
203
- publisher={Nature Publishing Group}
204
- }
205
-
206
- @article{aresta2019bach,
207
- title={{BACH}: Grand challenge on breast cancer histology images},
208
- author={Aresta, Guilherme and Ara{\'u}jo, Teresa and Kwok, Scotty and
209
- Chennamsetty, Sai Saketh and Safwan, Mohammed and Alex, Varghese and others},
210
- journal={Medical Image Analysis}, volume={56}, pages={122--139}, year={2019},
211
- publisher={Elsevier}
212
- }
213
-
214
- @article{brancati2022bracs,
215
- title={{BRACS}: A Dataset for BReAst Carcinoma Subtyping in {H\&E} Histology Images},
216
- author={Brancati, Nadia and Anniciello, Anna Maria and Pati, Pushpak and Riccio, Daniel and
217
- Scognamiglio, Giosu{\`e} and Jaume, Guillaume and De Pietro, Giuseppe and
218
- Di Bonito, Maurizio and Foncubierta, Antonio and Botti, Gerardo and others},
219
- journal={Database}, volume={2022}, pages={baac093}, year={2022},
220
- publisher={Oxford University Press UK}
221
- }
222
-
223
- @article{spanhol2015dataset,
224
- title={A dataset for breast cancer histopathological image classification},
225
- author={Spanhol, Fabio A and Oliveira, Luiz S and Petitjean, Caroline and Heutte, Laurent},
226
- journal={IEEE Transactions on Biomedical Engineering}, volume={63}, number={7},
227
- pages={1455--1462}, year={2015}, publisher={IEEE}
228
- }
229
-
230
- @article{amgad2022nucls,
231
- title={{NuCLS}: A scalable crowdsourcing approach and dataset for nucleus classification and
232
- segmentation in breast cancer},
233
- author={Amgad, Mohamed and Atteya, Lamees A and Hussein, Hagar and Mohammed, Kareem Hosny and
234
- Hafiz, Ehab and Elsebaie, Maha AT and Alhusseiny, Ahmed M and
235
- AlMoslemany, Mohamed Atef and Elmatboly, Abdelmagid M and Pappalardo, Philip A and others},
236
- journal={GigaScience}, volume={11}, pages={giac037}, year={2022},
237
- publisher={Oxford University Press}
238
- }
239
-
240
- @article{gamper2020pannuke,
241
- title={{PanNuke} dataset extension, insights and baselines},
242
- author={Gamper, Jevgenij and Koohbanani, Navid Alemi and Benes, Ksenija and Graham, Simon and
243
- Jahanifar, Mostafa and Khurram, Syed Ali and Azam, Ayesha and Hewitt, Katherine and
244
- Rajpoot, Nasir},
245
- journal={arXiv preprint arXiv:2003.10778}, year={2020}
246
- }
247
-
248
- @article{nechaev2025spider,
249
- title={{SPIDER}: A Comprehensive Multi-Organ Supervised Pathology Dataset and Baseline Models},
250
- author={Nechaev, Dmitry and Pchelnikov, Alexey and Ivanova, Ekaterina},
251
- year={2025}, eprint={2503.02876}, archivePrefix={arXiv}, primaryClass={cs.CV}
252
- }
253
- ```
254
- </details>
255
 
256
  ## Licence and citation
257
 
258
  Released under the MIT licence, matching the code repository.
259
 
260
- That covers what this repository adds; it cannot relicense the source data. Everything here
261
- is *derived cell-level features*, not images, and the upstream terms still travel with the
262
  derivatives: SPIDER-breast is `cc-by-nc-4.0`, research use only, and
263
- `labels/tcga_brca_clinical.tsv` is the open-access GDC clinical export, redistributed under
264
- TCGA's open-access terms. The source cohorts keep their own licences.
 
 
 
 
265
 
266
  ```bibtex
267
- @article{ogut2026graphist,
268
- title = {GrapHist: Graph Self-Supervised Learning for Histopathology},
269
- author = {{\"O}{\u{g}}{\"u}t, Sevda and Vincent-Cuaz, C{\'e}dric and
270
- Dubljevic, Natalia and Hurtado, Carlos and Subramanian, Vaishnavi and
271
- Frossard, Pascal and Thanou, Dorina},
272
- year = {2026},
273
- eprint = {2603.00143},
274
- archivePrefix = {arXiv},
275
- primaryClass = {cs.CV}
276
  }
277
  ```
278
-
279
- Built on GraphMAE (Hou et al., 2022), ACM (Luan et al., 2022), GINEConv (Hu et al., 2020) and
280
- VICReg (Bardes et al., 2022).
281
-
282
- This work was done by [**Mahbod Tajdini**](https://mahbodtajdini.com) and [**Tomás Gadea Alcaide**](https://tomasgadea.com/), supervised by members of
283
- [LTS4, EPFL](https://www.epfl.ch/labs/lts4/).
284
-
285
- Training, evaluation and analysis code:
286
- [github.com/Ace3Z/GrapHist-V2](https://github.com/Ace3Z/GrapHist-V2). This repository holds the
287
- model, the code needed to load it, and the data.
 
13
 
14
  # GrapHist++: Edge-Informed Graph Self-Supervised Learning for Histopathology
15
 
16
+ Pre-trained weights, cell graphs and embeddings for the edge-informed extension of
17
+ [GrapHist](https://huggingface.co/papers/2603.00143). GrapHist encodes a slide as a sparse graph
18
+ of cells and pre-trains an ACM-GIN encoder with masked feature reconstruction. GrapHist++ keeps
19
+ that recipe and changes two things: each edge carries a 75-dimensional descriptor of the tissue
20
+ between the two cells, and a VICReg variance/covariance term is added to the objective to stop
21
+ the representation collapsing.
 
22
 
23
+ - **Original paper:** [arXiv:2603.00143](https://arxiv.org/abs/2603.00143) · [model](https://huggingface.co/ogutsevda/graphist)
24
+ - **Code:** [Ace3Z/GrapHist-V2](https://github.com/Ace3Z/GrapHist-V2)
25
+ - **Data manual:** [`DATA.md`](DATA.md) — every artifact here and the result it reproduces
 
 
 
 
 
26
 
27
  ## Results
28
 
 
30
 
31
  | | BRACS | BreakHis | BACH |
32
  |---|:--:|:--:|:--:|
33
+ | GrapHist | 60.30 | 89.37 | **69.16** |
34
  | **GrapHist++** | **69.00** | **95.53** | 68.98 |
35
 
36
+ Survival on TCGA-BRCA (Cox PH, C-index): **0.793**, against 0.763 for GrapHist, 0.724 MAE,
37
+ 0.632 DINOv2. Cell-type identification (macro-F1 %): PanNuke 20× breast **58.57**, 40× breast
38
+ **58.38**, NuCLS 7-class **27.09**. Inference costs 0.093 ms per patch at 0.327 GB peak memory.
39
+
40
+ Without VICReg the encoder collapses (`pca_1` ≈ 0.5, effective dimension ≈ 2 of 512); with it
41
+ the same 100-epoch run finishes at 0.17 and 11.9. The term is training-only.
42
 
43
+ ## What's here
44
 
45
  ```
46
+ graphist_v2.pt the released encoder (127 MB, md5 81a2e6b91cefff0bbbc13c6fd318ee78)
47
+ modeling/ build_model factory and the ACM-GINEConv backbone
48
+ graphs/ cell graphs: TCGA-BRCA, BACH, BRACS, BreakHis, SPIDER-breast
49
+ embeddings/ precomputed slide- and cell-level embeddings
50
+ baselines/ DINOv2, MAE and GrapHist v1 embeddings for comparison
51
+ labels/ slide labels and the TCGA-BRCA clinical export
52
+ studies/ homophily, AdapterGNN and preprocessing-runtime artifacts
53
+ upstream_v1/ the original GrapHist graphs, unchanged
 
54
  ```
55
 
56
+ The repository is ~1.05 TB, so fetch file by file rather than cloning it. `DATA.md` gives the
57
+ per-cohort commands; the model alone is the six files in the snippet below.
 
 
 
 
58
 
59
+ ## Requirements
 
 
60
 
61
+ ```bash
62
+ pip install torch torch-geometric huggingface_hub
 
 
 
 
 
 
63
  ```
64
 
65
+ Graphs are PyTorch Geometric objects with `x` `(n, 96)`, `edge_index` `(2, e)`, `edge_attr`
66
+ `(e, 75)` and `batch`. Column 0 of `edge_attr` is the centroid distance in µm and is used as the
67
+ message weight, not as a feature.
 
 
 
 
68
 
69
+ ## Usage
 
 
 
 
70
 
71
  ```python
72
+ import os, sys, torch
73
+ from huggingface_hub import hf_hub_download
74
+
75
+ # Fetch file by file: on huggingface-hub 1.7.1 snapshot_download(allow_patterns=...)
76
+ # silently skips LFS files, so it returns an empty directory here.
77
+ for f in ["graphist_v2.pt", "modeling/models/__init__.py", "modeling/models/acm_gin.py",
78
+ "modeling/models/acm_gineconv.py", "modeling/models/edcoder.py",
79
+ "modeling/models/utils.py"]:
80
+ hf_hub_download(repo_id="Ace3Z/graphist-v2", filename=f)
81
+
82
+ path = os.path.dirname(hf_hub_download(repo_id="Ace3Z/graphist-v2",
83
+ filename="graphist_v2.pt"))
84
  sys.path.insert(0, f"{path}/modeling")
85
  from models import build_model
86
 
87
  class Args:
88
  encoder = decoder = "acm_gineconv"
89
+ num_features = 96 # per-cell features
90
+ num_edge_features = 75 # projection sees 74; distance excluded
91
  num_hidden = 512
92
  num_layers = 5
93
  concat_hidden = True # load-critical
 
107
 
108
  model = build_model(Args())
109
  ckpt = torch.load(f"{path}/graphist_v2.pt", map_location="cpu", weights_only=False)
110
+ model.load_state_dict(ckpt["model_state_dict"], strict=True)
111
  model.eval()
112
 
 
 
113
  with torch.no_grad():
114
+ h = model.embed(batch.x, batch.edge_index, batch.edge_attr, batch.batch)
115
  ```
116
 
117
+ Three arguments decide whether the weights load at all. `encoder_norm` must be `"layer"` and
118
+ `edge_distance_in_proj` must be `False` — both defaults are wrong for this checkpoint — and
119
+ `concat_hidden` must be `True`, which has no default. Anything else raises a shape or key error.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
120
 
121
  ## Licence and citation
122
 
123
  Released under the MIT licence, matching the code repository.
124
 
125
+ That covers what this repository adds; it cannot relicense the source data. Everything here is
126
+ *derived cell-level features*, not images, and the upstream terms still travel with the
127
  derivatives: SPIDER-breast is `cc-by-nc-4.0`, research use only, and
128
+ `labels/tcga_brca_clinical.tsv` is the open-access GDC clinical export. The source cohorts keep
129
+ their own licences.
130
+
131
+ The architecture adapts [GraphMAE](https://github.com/THUDM/GraphMAE) and
132
+ [ACM-GNN](https://github.com/SitaoLuan/ACM-GNN); the regularizer follows
133
+ [VICReg](https://arxiv.org/abs/2105.04906).
134
 
135
  ```bibtex
136
+ @misc{ogut2026graphist,
137
+ title = {GrapHist: Graph Self-Supervised Learning for Histopathology},
138
+ author = {Sevda {\"O}{\u{g}}{\"u}t and C{\'e}dric Vincent-Cuaz and Natalia Dubljevic and
139
+ Carlos Hurtado and Vaishnavi Subramanian and Pascal Frossard and Dorina Thanou},
140
+ year = {2026},
141
+ eprint = {2603.00143},
142
+ url = {https://arxiv.org/abs/2603.00143},
 
 
143
  }
144
  ```