GRASS-MIL 1.0: preprint method, nested CV, niche discovery, statistics

.github/workflows/test.yml

@@ -57,7 +57,7 @@ jobs:
             -f "https://data.pyg.org/whl/torch-${TORCH_VERSION}+cpu.html"
 
       - name: Install the package
-        run: pip install ".[interpretability,io]" pytest
+        run: pip install ".[interpretability,io,stats,plots]" pytest
 
       - name: Show key package versions
         run: |
@@ -113,7 +113,7 @@ jobs:
 
       - name: Run tests and collect coverage
         run: |
-          pip install ".[interpretability,io]" pytest "pytest-cov[toml]"
+          pip install ".[interpretability,io,stats,plots]" pytest "pytest-cov[toml]"
           pytest --cov grass_mil
 
       - name: Upload coverage to Codecov

.gitignore

@@ -145,6 +145,8 @@ dmypy.json
 
 # Lightning-Hydra-Template
 configs/local/default.yaml
+src/grass_mil/configs/local/*.yaml
+!src/grass_mil/configs/local/.gitkeep
 /data/
 /logs/
 .env
@@ -154,3 +156,6 @@ configs/local/default.yaml
 
 # Vignette scratch space (downloaded data, graphs, runs)
 vignettes/vignette_work/
+
+# vignette datasets are downloaded at runtime (squidpy.datasets.mibitof)
+vignettes/data/

CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 1.0.0 (2026-10)
+
+Public release accompanying the preprint
+[GRASS-MIL: graph-based representation and discovery of phenotype-associated spatial structures with multiple instance learning](https://www.biorxiv.org/content/10.64898/2026.10.08.757722v1).
+
+### Method (defaults match the preprint; every setting stays configurable)
+
+- Delaunay cell graph with the bounded log edge length `clip((ln d - 2)/3, 0, 1)` as the edge feature (`log_distance`).
+- GINE ego-graph encoder (4 x 256, learnable epsilon, layer norm, max pooling, xavier-initialised cell-type embedding) as `model=grass_mil`.
+- Projected gated attention with one channel per class (32 / 8, kaiming) and logit-space pooling, so every bag logit is an exact sum of per-cell contributions.
+- One region = one bag: all sampled ego-graphs of a region in one batch, one attention softmax, one loss; region-level validation metrics and selection.
+- Training regimes as presets (`regime=mil|mil_frozen|linear_probehead|linear_ftall|linear_ftall_reg`) with per-component learning-rate scales, head pre-fit by a logistic probe, class weights from the training split, per-step cosine schedule, gradient accumulation over regions, AMP-safe scheduler stepping, elementwise feature drop with an unassigned token.
+- BGRL "A3" pretraining preset (`regime=pretrain_a3`): roots drawn from the union of all regions, momentum 0.99 -> 1.0, DropImportance + feature noise, checkpoint every 5000 steps.
+- Import of legacy SPACE-GM style BGRL checkpoints (`model.encoder_init_map=spacegm_bgrl`).
+
+### Analyses
+
+- `grass-mil-probe`, `grass-mil-nested-cv`: nested patient-grouped cross-validation with explicit fold files, inner-fold epoch selection, refit and out-of-fold predictions (region and patient level).
+- `grass-mil-extract`: per-cell cache (embeddings, instance logits, attention) of trained models over every cell.
+- `grass-mil-niches`: niche discovery on a model's cells (cosine HDBSCAN by default, any registry backend), attention-weighted margins, per-niche tables, co-localisation, figures.
+- `grass-mil-metaclusters`: cross-fold niche replication (constrained matching on composition), whole-dataset transfer, shared label-free basis.
+- `grass-mil-scores`: bootstrap AUROC intervals, DeLong tests, within-fold standardisation, operating points (sensitivity, specificity, PPV, NPV, likelihood ratios).
+- `grass-mil-spatial-stats`: neighbourhood enrichment, cellular neighbourhoods, contact fractions and cross-K per region with patient-level group tests.
+- Patient-level aggregation in `grass-mil-predict` (mean of region probabilities or one merged bag).
+
+### Housekeeping
+
+- Removed stale component configs, the dummy dataset, the embeddings shim and internal audit notes; added `CITATION.cff`; `hydra-core` 1.3.5+.

CITATION.cff

@@ -0,0 +1,33 @@
+cff-version: 1.2.0
+message: "If you use GRASS-MIL, please cite the preprint."
+title: "GRASS-MIL: graph-based representation and discovery of phenotype-associated spatial structures with multiple instance learning"
+type: software
+version: 1.0.0
+date-released: 2026-10-13
+license: MIT
+repository-code: https://github.com/BoevaLab/grass-mil
+authors:
+  - family-names: Rabuzin
+    given-names: Lovro
+  - family-names: Yates
+    given-names: Josephine
+  - family-names: Xu
+    given-names: Mina
+  - family-names: Boeva
+    given-names: Valentina
+preferred-citation:
+  type: article
+  title: "GRASS-MIL: graph-based representation and discovery of phenotype-associated spatial structures with multiple instance learning"
+  authors:
+    - family-names: Rabuzin
+      given-names: Lovro
+    - family-names: Yates
+      given-names: Josephine
+    - family-names: Xu
+      given-names: Mina
+    - family-names: Boeva
+      given-names: Valentina
+  journal: bioRxiv
+  year: 2026
+  doi: 10.64898/2026.10.08.757722
+  url: https://www.biorxiv.org/content/10.64898/2026.10.08.757722v1

Makefile

@@ -1,27 +1,19 @@
-
 help:  ## Show help
 	@grep -E '^[.a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
-clean: ## Clean autogenerated files
+clean: ## Remove caches and build artefacts
 	rm -rf dist
 	find . -type f -name "*.DS_Store" -ls -delete
 	find . | grep -E "(__pycache__|\.pyc|\.pyo)" | xargs rm -rf
 	find . | grep -E ".pytest_cache" | xargs rm -rf
 	find . | grep -E ".ipynb_checkpoints" | xargs rm -rf
 	rm -f .coverage
 
-clean-logs: ## Clean logs
+clean-logs: ## Remove run outputs under logs/
 	rm -rf logs/**
 
-format: ## Run pre-commit hooks
+format: ## Run pre-commit hooks (ruff lint + format)
 	pre-commit run -a
 
-sync: ## Merge changes from main branch to your current branch
-	git pull
-	git pull origin main
-
 test: ## Run the test suite
 	pytest
-
-train: ## Train the model
-	grass-mil-train