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

docs: finish the MIT relicense and state the input transforms

Browse files

DATA.md still declared cc-by-nc-sa-4.0, contradicting the card and the
repository metadata. Both now say MIT, and both keep the SPIDER-breast
non-commercial constraint explicit, since MIT cannot lift it.

The usage block omitted ToUndirected/NormalizeData/AddVirtualNode, which
the release was trained and evaluated with; without them embed() runs and
silently returns different embeddings. Also name the parameter count and
the hardware behind the timing, and correct the studies/ description: no
code ships here.

Files changed (2) hide show
  1. DATA.md +7 -5
  2. README.md +18 -1
DATA.md CHANGED
@@ -236,9 +236,9 @@ rows, so four split ids have no label row and an inner join silently drops them.
236
 
237
  ## studies/
238
 
239
- Side analyses. Each has its own folder here holding the data, the code that produced it
240
- and its outputs, except the batch-effect study, which reuses `baselines/` and `labels/`
241
- and so ships no folder of its own.
242
 
243
  ### `studies/homophily/`: how homophilic are cell graphs?
244
 
@@ -510,9 +510,11 @@ the source cohort(s) your work touches.
510
 
511
  ## Licence
512
 
513
- Released `cc-by-nc-sa-4.0`. SPIDER-breast is `cc-by-nc-4.0`, research use only, and those
514
- terms travel with the derived graphs:
515
 
 
 
 
516
  `labels/tcga_brca_clinical.tsv` is the open-access GDC clinical export, redistributed under
517
  TCGA's open-access terms. The source cohorts keep their own licences, so cite their papers
518
  alongside GrapHist.
 
236
 
237
  ## studies/
238
 
239
+ Side analyses. Each has its own folder here holding the inputs and, where they are small
240
+ enough to ship, the outputs; the code that produced them is in the GitHub repository. The
241
+ batch-effect study reuses `baselines/` and `labels/` and so ships no folder of its own.
242
 
243
  ### `studies/homophily/`: how homophilic are cell graphs?
244
 
 
510
 
511
  ## Licence
512
 
513
+ Released under the MIT licence, matching the code repository.
 
514
 
515
+ That covers what this repository adds; it cannot relicense the source data, and the upstream
516
+ terms still travel with the derivatives. SPIDER-breast is `cc-by-nc-4.0`, **research use
517
+ only**, so `graphs/spider_breast/` may not be used commercially whatever this licence says.
518
  `labels/tcga_brca_clinical.tsv` is the open-access GDC clinical export, redistributed under
519
  TCGA's open-access terms. The source cohorts keep their own licences, so cite their papers
520
  alongside GrapHist.
README.md CHANGED
@@ -35,7 +35,8 @@ Slide-level MIL, transfer to unseen cohorts (test macro-F1 %, best of three MIL
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.
@@ -114,6 +115,22 @@ 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.
 
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**. The encoder has 10.53 M parameters and embeds a patch in
39
+ 0.093 ms at 0.327 GB peak memory (BACH, batch size 48, H200).
40
 
41
  Without VICReg the encoder collapses (`pca_1` ≈ 0.5, effective dimension ≈ 2 of 512); with it
42
  the same 100-epoch run finishes at 0.17 and 11.9. The term is training-only.
 
115
  h = model.embed(batch.x, batch.edge_index, batch.edge_attr, batch.batch)
116
  ```
117
 
118
+ `batch` is a PyG `Batch` from a `DataLoader`, and it must be built with the same three
119
+ transforms the release was trained and evaluated with, or the embeddings will not match:
120
+
121
+ ```python
122
+ from torch_geometric.transforms import ToUndirected
123
+ # NormalizeData and AddVirtualNode ship in the code repository (src/train/utils.py)
124
+ transforms = [
125
+ ToUndirected(),
126
+ NormalizeData(scale_vals, edge_attr_skip_cols=[0], min_std=0.01, clip=10),
127
+ AddVirtualNode(mean_edge_distance=scale_vals["edge_attr"]["mean"][0]),
128
+ ]
129
+ ```
130
+
131
+ `scale_vals` is the cohort's `normalization.json`, shipped beside its graphs. Skipping these
132
+ raises no error; it just yields different numbers.
133
+
134
  Three arguments decide whether the weights load at all. `encoder_norm` must be `"layer"` and
135
  `edge_distance_in_proj` must be `False` — both defaults are wrong for this checkpoint — and
136
  `concat_hidden` must be `True`, which has no default. Anything else raises a shape or key error.