spsheaf 0.2.0__tar.gz

spsheaf-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Eduardo Paluzo-Hidalgo, Yusuke Imoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spsheaf-0.2.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE README.md pyproject.toml
+recursive-include src/spsheaf *.py
+recursive-include examples quickstart.py tutorial.ipynb
+prune experiments
+prune benchmarks
+prune figures
+prune reported
+prune tests
+prune tools
+prune docs
+prune data
+prune _staging
+prune _to_delete
+global-exclude __pycache__ *.py[cod] .DS_Store

spsheaf-0.2.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: spsheaf
+Version: 0.2.0
+Summary: spSheaf: sheaf-theoretic boundary detection for segmentation-free spatial domain inference
+Author: Eduardo Paluzo-Hidalgo, Yusuke Imoto
+License: MIT
+Project-URL: Repository, https://github.com/EduPH/spSheaf
+Keywords: spatial transcriptomics,sheaf theory,domain inference,computational topology,MERFISH
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.7
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: matplotlib>=3.4
+Requires-Dist: pyarrow>=10
+Requires-Dist: anndata>=0.9
+Requires-Dist: h5py>=3.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: flake8>=5.0; extra == "dev"
+Provides-Extra: figures
+Requires-Dist: pypdf>=3.9; extra == "figures"
+Requires-Dist: pdfminer.six>=20221105; extra == "figures"
+Requires-Dist: pillow>=9.0; extra == "figures"
+Requires-Dist: pytest>=7.0; extra == "figures"
+Provides-Extra: benchmark
+Requires-Dist: ssam>=1.0; extra == "benchmark"
+Requires-Dist: points2regions>=0.1; extra == "benchmark"
+Dynamic: license-file
+
+# spSheaf
+
+Sheaf-theoretic spatial domain inference from raw molecules, without cell
+segmentation. spSheaf places kernel-smoothed expression fibers on a grid,
+gives each vertex a local principal-subspace stalk, scores every edge by its
+*sheaf disagreement* — the residual mismatch of neighbouring local coordinates
+after the stalks are aligned — and attenuates those transitions during
+clustering. Paluzo-Hidalgo, Maehara & Imoto (2026), manuscript in preparation for publication.
+
+![The spSheaf construction on a 530 × 400 µm window of a MERFISH hypothalamus section](docs/assets/spsheaf_method.gif)
+
+*The construction on real data (MERFISH slice 0.19 of Moffitt et al. 2018, a
+530 × 400 µm window; every quantity computed by spSheaf at the paper's
+settings). Molecules and the 15 µm grid; the Gaussian-kernel fiber of one grid
+point and one of its components as a smoothed field; the kNN graph; the stalks
+standing over the vertices; one edge across an interface, its two stalks
+aligned by the SVD of their overlap and the disagreement D(e) between the
+transported coordinates; every edge scored; the smoothed boundary field over
+the tissue; the domains.*
+
+## Install
+
+```bash
+pip install spsheaf                  # Python >= 3.9; numpy, scipy, scikit-learn, pandas
+pip install -e .                     # from a clone, for the experiments and figures
+pip install -r requirements-lock.txt # exact versions the results were produced on
+```
+
+## Quickstart
+
+`examples/quickstart.py` downloads one public section — the SpaceTx BaristaSeq mouse visual cortex,
+0.32 million molecules, 81 genes — runs the eight steps at the paper's
+settings for it, and draws the domains next to the authors' layer
+annotation. One minute on a laptop, no other data needed:
+
+```bash
+pip install spsheaf matplotlib
+python examples/quickstart.py        # writes examples/quickstart_domains.png; ARI 0.77 against the six layers
+```
+
+![quickstart](examples/quickstart_domains.png)
+
+`examples/tutorial.ipynb` is the same section step by step, with every
+intermediate drawn (fibers, stalks, the disagreement field), what each
+parameter does, the comparison with the annotation per layer, and how to
+choose the number of domains with the silhouette when there is no
+annotation. It runs in under a minute; the executed outputs are kept in the
+notebook.
+
+The whole method is eight function calls on a molecule table with columns
+`x`, `y`, `gene` (any units; the parameters are in those units):
+
+```python
+from spsheaf import fibers, graph, sheaf, clustering
+
+grid, raw, genes = fibers.build_kernel_fibers(mol, grid_spacing=15, bandwidth=25, x_col="x", y_col="y")
+fib    = fibers.normalize_fibers(raw)                               # 1  fibers on a grid
+edges  = graph.build_spatial_graph(grid, k=6)                       # 2  spatial graph
+stalks = sheaf.compute_stalks(fib, grid, uniform_dim=6, k_nbrs=50)  # 3  stalks: local principal subspaces
+rs     = sheaf.compute_restriction_maps(stalks, edges, 6)           # 4  restriction maps by SVD alignment
+b_raw, b_smooth = sheaf.compute_boundary_scores(fib, grid, stalks, edges, rs, smooth_radius=60)  # 5-6
+labels = clustering.boundary_aware_clustering(fib, grid, b_smooth, edges, n_clusters=8)          # 7
+labels, _ = clustering.spatial_cleanup(labels, edges, grid_coords=grid)                          # 8
+```
+
+`spsheaf.pipeline.run_single_slice` wraps the eight steps and the evaluation
+against an annotation. Parameters: grid spacing `δ`, kernel bandwidth `h`,
+stalk dimension `d`, smoothing radius `σ_s`, boundary weight `α_b`, spatial
+weight `α_s`, and the coordinate reference of the stalk sections
+(`SPSHEAF_REFERENCE=tissue|local`, default `tissue`: coordinates referenced
+to the section mean; `local` references them to the neighbourhood mean, and
+is what the tuning grid selects on the MERFISH benchmark). The number of
+domains `k` is an input; `experiments/merfish/k_selection.py` computes the
+silhouette over a range of `k`, and the paper recommends selecting within the
+range where it lies within 0.002 of its maximum. `docs/package_api.md` lists
+the modules.
+
+## Reproduce the paper
+
+Everything below this line is the paper's reproduction material; `pip install spsheaf` ships only `src/spsheaf/`.
+
+Point the code at the data (`data/README.md` lists every input and where it
+comes from):
+
+```bash
+export SPSHEAF_DATA=/path/to/data      # or copy paths.example.toml to paths.toml
+```
+
+Rebuild the figures from the stored tables (minutes, no raw data needed
+except for the panel dumps under `data/results`):
+
+```bash
+make figures && make figures-verify   # 17 PDFs into figures/out/, checked against the 180 mm / 6-8 pt spec
+```
+
+Check a number without running anything: every spSheaf table in the paper is
+under `reported/` (`reported/README.md` names the claim and the command behind
+each file; `reported/tissue/` holds the runs repeated at the tissue reference);
+the competitors' tables and per-cell labels are under
+`benchmarks/segfree/results/` (`results_union/` for the selection over both
+references). `make reported-check` and `make reported-tissue-check` fail if
+either has drifted from its results tree.
+
+Re-run the experiments (hours; raw inputs required):
+
+```bash
+SPSHEAF_REFERENCE=local make merfish merfish-seeds merfish-loo-cv   # Table 1, Fig 2b: five slices, 20 seeds, the 27-configuration grid
+make merfish merfish-seeds merfish-loo-cv   # the same at the default (tissue) reference; the two grids together are the 54-row union
+make revision                               # ablation, boundary evaluation, k sweep (Fig 2c/d)
+make osmfish-all osmfish-insample osmfish-insample-tissue   # Fig 3, the 2 x 108 grid
+make spacetx-all spacetx-ablation           # both SpaceTx sections, 162-configuration grids, ED 3, Supplementary Fig 3
+make matched-selection-union benchmark-table   # one selection rule for all four methods (Table 1)
+make k-selection merfish-k-selection merfish-k-split   # choosing k: synthetic calibration, the five slices, the divisions at k = 9 (ED 4, Fig 4)
+make help                                   # everything else
+```
+
+The grids are resumable: interrupt and re-run, only missing configurations
+are computed. The competitor sweeps (SSAM, Points2Regions, FICTURE) are
+reproducible from the tracked metric tables; re-running them needs the
+competitors' inputs, which `python -m benchmarks.segfree.inputs` names.
+
+## Main results
+
+ARI against the published annotation, every method tuned on its own grid on
+the section it is scored on (Table 1 of the paper); the coordinate reference
+is part of spSheaf's grid. MERFISH: one configuration per method over the
+five slices.
+
+| | MERFISH (5 slices) | osmFISH | Allen prototype MERFISH | BaristaSeq |
+|---|---|---|---|---|
+| **spSheaf** (selected reference) | **0.571** (local) | 0.673 (tissue) | **0.754** (tissue) | **0.757** (tissue) |
+| spSheaf at the default, tissue | 0.548 | 0.673 | 0.754 | 0.757 |
+| Points2Regions | 0.457 | 0.432 | 0.684 | 0.733 |
+| SSAM | 0.401 | **0.729** | 0.410 | 0.738 |
+| FICTURE | 0.342 | 0.465 | 0.475 | 0.631 |
+
+On MERFISH the ranking holds under all three selection rules the five slices
+allow — per-slice argmax 0.584 vs 0.510, one configuration 0.571 vs 0.457,
+leave-one-slice-out 0.552 vs 0.388 — and spSheaf ranks first of twelve on
+NMI against the SDMBench baselines. On osmFISH two of eleven layers are
+recovered at no configuration; see `experiments/osmfish/`. On the MERFISH
+benchmark at the local reference, ten ablation arms attribute +0.102 ARI to
+the sheaf term over no weighting and +0.046 over a kernel baseline; at the
+tissue reference the gain over the kernel baseline is 0.006, and on the two
+SpaceTx sections no edge score separates from it (`reported/tissue/`).
+
+## Layout
+
+```
+src/spsheaf/         the method (fibers, graph, sheaf, clustering, evaluation, pipeline); what `pip install spsheaf` ships
+examples/            quickstart.py and tutorial.ipynb: one public section from molecules to domains
+experiments/         one folder per dataset (synthetic/ for the k calibration); each README gives commands, inputs and outputs
+benchmarks/segfree/  SSAM, Points2Regions and FICTURE under a matched protocol; results/, results_union/, results_tissue/ tracked
+figures/             figure pipeline; out/ is generated, assets/ holds the few placed rasters
+reported/            spSheaf's own result tables, one row per configuration (tracked); tissue/ for the runs at the default reference
+tests/  tools/       unit tests; provenance and requirements scripts
+docs/                package API; dev-notes/ are working notes
+data/                untracked; data/README.md
+```
+
+## Licence
+
+MIT.

spsheaf-0.2.0/README.md

@@ -0,0 +1,163 @@
+# spSheaf
+
+Sheaf-theoretic spatial domain inference from raw molecules, without cell
+segmentation. spSheaf places kernel-smoothed expression fibers on a grid,
+gives each vertex a local principal-subspace stalk, scores every edge by its
+*sheaf disagreement* — the residual mismatch of neighbouring local coordinates
+after the stalks are aligned — and attenuates those transitions during
+clustering. Paluzo-Hidalgo, Maehara & Imoto (2026), manuscript in preparation for publication.
+
+![The spSheaf construction on a 530 × 400 µm window of a MERFISH hypothalamus section](docs/assets/spsheaf_method.gif)
+
+*The construction on real data (MERFISH slice 0.19 of Moffitt et al. 2018, a
+530 × 400 µm window; every quantity computed by spSheaf at the paper's
+settings). Molecules and the 15 µm grid; the Gaussian-kernel fiber of one grid
+point and one of its components as a smoothed field; the kNN graph; the stalks
+standing over the vertices; one edge across an interface, its two stalks
+aligned by the SVD of their overlap and the disagreement D(e) between the
+transported coordinates; every edge scored; the smoothed boundary field over
+the tissue; the domains.*
+
+## Install
+
+```bash
+pip install spsheaf                  # Python >= 3.9; numpy, scipy, scikit-learn, pandas
+pip install -e .                     # from a clone, for the experiments and figures
+pip install -r requirements-lock.txt # exact versions the results were produced on
+```
+
+## Quickstart
+
+`examples/quickstart.py` downloads one public section — the SpaceTx BaristaSeq mouse visual cortex,
+0.32 million molecules, 81 genes — runs the eight steps at the paper's
+settings for it, and draws the domains next to the authors' layer
+annotation. One minute on a laptop, no other data needed:
+
+```bash
+pip install spsheaf matplotlib
+python examples/quickstart.py        # writes examples/quickstart_domains.png; ARI 0.77 against the six layers
+```
+
+![quickstart](examples/quickstart_domains.png)
+
+`examples/tutorial.ipynb` is the same section step by step, with every
+intermediate drawn (fibers, stalks, the disagreement field), what each
+parameter does, the comparison with the annotation per layer, and how to
+choose the number of domains with the silhouette when there is no
+annotation. It runs in under a minute; the executed outputs are kept in the
+notebook.
+
+The whole method is eight function calls on a molecule table with columns
+`x`, `y`, `gene` (any units; the parameters are in those units):
+
+```python
+from spsheaf import fibers, graph, sheaf, clustering
+
+grid, raw, genes = fibers.build_kernel_fibers(mol, grid_spacing=15, bandwidth=25, x_col="x", y_col="y")
+fib    = fibers.normalize_fibers(raw)                               # 1  fibers on a grid
+edges  = graph.build_spatial_graph(grid, k=6)                       # 2  spatial graph
+stalks = sheaf.compute_stalks(fib, grid, uniform_dim=6, k_nbrs=50)  # 3  stalks: local principal subspaces
+rs     = sheaf.compute_restriction_maps(stalks, edges, 6)           # 4  restriction maps by SVD alignment
+b_raw, b_smooth = sheaf.compute_boundary_scores(fib, grid, stalks, edges, rs, smooth_radius=60)  # 5-6
+labels = clustering.boundary_aware_clustering(fib, grid, b_smooth, edges, n_clusters=8)          # 7
+labels, _ = clustering.spatial_cleanup(labels, edges, grid_coords=grid)                          # 8
+```
+
+`spsheaf.pipeline.run_single_slice` wraps the eight steps and the evaluation
+against an annotation. Parameters: grid spacing `δ`, kernel bandwidth `h`,
+stalk dimension `d`, smoothing radius `σ_s`, boundary weight `α_b`, spatial
+weight `α_s`, and the coordinate reference of the stalk sections
+(`SPSHEAF_REFERENCE=tissue|local`, default `tissue`: coordinates referenced
+to the section mean; `local` references them to the neighbourhood mean, and
+is what the tuning grid selects on the MERFISH benchmark). The number of
+domains `k` is an input; `experiments/merfish/k_selection.py` computes the
+silhouette over a range of `k`, and the paper recommends selecting within the
+range where it lies within 0.002 of its maximum. `docs/package_api.md` lists
+the modules.
+
+## Reproduce the paper
+
+Everything below this line is the paper's reproduction material; `pip install spsheaf` ships only `src/spsheaf/`.
+
+Point the code at the data (`data/README.md` lists every input and where it
+comes from):
+
+```bash
+export SPSHEAF_DATA=/path/to/data      # or copy paths.example.toml to paths.toml
+```
+
+Rebuild the figures from the stored tables (minutes, no raw data needed
+except for the panel dumps under `data/results`):
+
+```bash
+make figures && make figures-verify   # 17 PDFs into figures/out/, checked against the 180 mm / 6-8 pt spec
+```
+
+Check a number without running anything: every spSheaf table in the paper is
+under `reported/` (`reported/README.md` names the claim and the command behind
+each file; `reported/tissue/` holds the runs repeated at the tissue reference);
+the competitors' tables and per-cell labels are under
+`benchmarks/segfree/results/` (`results_union/` for the selection over both
+references). `make reported-check` and `make reported-tissue-check` fail if
+either has drifted from its results tree.
+
+Re-run the experiments (hours; raw inputs required):
+
+```bash
+SPSHEAF_REFERENCE=local make merfish merfish-seeds merfish-loo-cv   # Table 1, Fig 2b: five slices, 20 seeds, the 27-configuration grid
+make merfish merfish-seeds merfish-loo-cv   # the same at the default (tissue) reference; the two grids together are the 54-row union
+make revision                               # ablation, boundary evaluation, k sweep (Fig 2c/d)
+make osmfish-all osmfish-insample osmfish-insample-tissue   # Fig 3, the 2 x 108 grid
+make spacetx-all spacetx-ablation           # both SpaceTx sections, 162-configuration grids, ED 3, Supplementary Fig 3
+make matched-selection-union benchmark-table   # one selection rule for all four methods (Table 1)
+make k-selection merfish-k-selection merfish-k-split   # choosing k: synthetic calibration, the five slices, the divisions at k = 9 (ED 4, Fig 4)
+make help                                   # everything else
+```
+
+The grids are resumable: interrupt and re-run, only missing configurations
+are computed. The competitor sweeps (SSAM, Points2Regions, FICTURE) are
+reproducible from the tracked metric tables; re-running them needs the
+competitors' inputs, which `python -m benchmarks.segfree.inputs` names.
+
+## Main results
+
+ARI against the published annotation, every method tuned on its own grid on
+the section it is scored on (Table 1 of the paper); the coordinate reference
+is part of spSheaf's grid. MERFISH: one configuration per method over the
+five slices.
+
+| | MERFISH (5 slices) | osmFISH | Allen prototype MERFISH | BaristaSeq |
+|---|---|---|---|---|
+| **spSheaf** (selected reference) | **0.571** (local) | 0.673 (tissue) | **0.754** (tissue) | **0.757** (tissue) |
+| spSheaf at the default, tissue | 0.548 | 0.673 | 0.754 | 0.757 |
+| Points2Regions | 0.457 | 0.432 | 0.684 | 0.733 |
+| SSAM | 0.401 | **0.729** | 0.410 | 0.738 |
+| FICTURE | 0.342 | 0.465 | 0.475 | 0.631 |
+
+On MERFISH the ranking holds under all three selection rules the five slices
+allow — per-slice argmax 0.584 vs 0.510, one configuration 0.571 vs 0.457,
+leave-one-slice-out 0.552 vs 0.388 — and spSheaf ranks first of twelve on
+NMI against the SDMBench baselines. On osmFISH two of eleven layers are
+recovered at no configuration; see `experiments/osmfish/`. On the MERFISH
+benchmark at the local reference, ten ablation arms attribute +0.102 ARI to
+the sheaf term over no weighting and +0.046 over a kernel baseline; at the
+tissue reference the gain over the kernel baseline is 0.006, and on the two
+SpaceTx sections no edge score separates from it (`reported/tissue/`).
+
+## Layout
+
+```
+src/spsheaf/         the method (fibers, graph, sheaf, clustering, evaluation, pipeline); what `pip install spsheaf` ships
+examples/            quickstart.py and tutorial.ipynb: one public section from molecules to domains
+experiments/         one folder per dataset (synthetic/ for the k calibration); each README gives commands, inputs and outputs
+benchmarks/segfree/  SSAM, Points2Regions and FICTURE under a matched protocol; results/, results_union/, results_tissue/ tracked
+figures/             figure pipeline; out/ is generated, assets/ holds the few placed rasters
+reported/            spSheaf's own result tables, one row per configuration (tracked); tissue/ for the runs at the default reference
+tests/  tools/       unit tests; provenance and requirements scripts
+docs/                package API; dev-notes/ are working notes
+data/                untracked; data/README.md
+```
+
+## Licence
+
+MIT.

spsheaf-0.2.0/examples/quickstart.py

@@ -0,0 +1,91 @@
+"""spSheaf quickstart: from a molecule table to spatial domains in one script.
+
+Downloads one public section (the SpaceTx BaristaSeq mouse visual cortex
+section, 0.32 million molecules, 81 genes, ~25 MB), runs the eight steps of
+spSheaf at the settings used for it in the paper, draws the domains next to
+the authors' layer annotation and prints the ARI. About one minute on a
+laptop; no other data needed.
+
+    pip install spsheaf matplotlib
+    python examples/quickstart.py            # writes quickstart_domains.png
+
+Every step is a plain function call so each intermediate (fibers, graph,
+stalks, boundary field) can be inspected or replaced. Units are those of the
+input coordinates (micrometres here).
+"""
+from pathlib import Path
+from urllib.request import urlretrieve
+
+import numpy as np
+import pandas as pd
+
+from spsheaf import clustering, evaluation, fibers, graph, sheaf
+
+# ---------------------------------------------------------------- 1. data
+BASE = "https://s3.amazonaws.com/starfish.data.spacetx/spacetx-website/data/BARISTASeq"
+HERE = Path(__file__).resolve().parent
+DATA = HERE / "data_quickstart"
+DATA.mkdir(exist_ok=True)
+for name in ("s3_spot_table.csv", "s3_mapped_cell_table.csv"):
+    if not (DATA / name).exists():
+        print(f"downloading {name} ...")
+        urlretrieve(f"{BASE}/{name}", DATA / name)
+
+spots = pd.read_csv(DATA / "s3_spot_table.csv", usecols=["xc", "yc", "gene"])
+mol = pd.DataFrame({"x": spots.xc.values, "y": spots.yc.values, "gene": spots.gene.astype(str).values})
+print(f"{len(mol):,} molecules, {mol.gene.nunique()} genes")
+
+# ---------------------------------------------------------------- 2. parameters
+# the configuration selected for this section in the paper (Supplementary Table 3)
+GRID_SPACING = 10.0     # um between fiber centres
+BANDWIDTH = 40.0        # um, Gaussian kernel of the fibers
+STALK_DIM = 9           # dimension of every local principal subspace
+SMOOTH_RADIUS = 180.0   # um, smoothing of the disagreement field
+SPATIAL_WEIGHT = 0.5    # alpha_s: weight of the coordinates in the clustering feature
+BOUNDARY_ALPHA = 0.5    # alpha_b: strength of the attenuation at transitions
+K = 6                   # number of domains (six annotated layers here)
+
+# ---------------------------------------------------------------- 3. the eight steps
+grid, raw, genes = fibers.build_kernel_fibers(mol, grid_spacing=GRID_SPACING, bandwidth=BANDWIDTH,
+                                              x_col="x", y_col="y")            # (1) fibers on a grid
+fib = fibers.normalize_fibers(raw)
+edges = graph.build_spatial_graph(grid, k=6)                                     # (2) spatial graph
+stalks = sheaf.compute_stalks(fib, grid, uniform_dim=STALK_DIM, k_nbrs=50)      # (3) stalks: local PCA bases
+rs = sheaf.compute_restriction_maps(stalks, edges, STALK_DIM)                    # (4) restriction maps by SVD
+b_raw, b_smooth = sheaf.compute_boundary_scores(fib, grid, stalks, edges, rs,
+                                                smooth_radius=SMOOTH_RADIUS)     # (5-6) disagreement, field
+labels = clustering.boundary_aware_clustering(fib, grid, b_smooth, edges, n_clusters=K,
+                                              spatial_weight=SPATIAL_WEIGHT,
+                                              boundary_alpha=BOUNDARY_ALPHA)    # (7) attenuated clustering
+labels, _ = clustering.spatial_cleanup(labels, edges, grid_coords=grid)         # (8) remove fragments
+
+# ---------------------------------------------------------------- 4. against the authors' annotation
+cells = pd.read_csv(DATA / "s3_mapped_cell_table.csv")
+cxy = cells[["rotated_x", "rotated_y"]].values
+cxy = cxy - cxy.min(0) + grid.min(0)      # cell frame onto the grid frame by their lower-left corners
+from scipy.spatial import cKDTree
+_, idx = cKDTree(grid).query(cxy, k=1)
+pred = labels[idx]
+names = sorted(cells.layer.dropna().unique())
+gti = np.array([names.index(l) if isinstance(l, str) else -1 for l in cells.layer])
+valid = gti >= 0
+ari = evaluation.compute_ari(pred, gti, valid)
+print(f"ARI against the layer annotation: {ari:.3f}  (the paper reports 0.757 at this configuration "
+      "with a label-free registration of the cell frame; a corner alignment is used here)")
+
+# ---------------------------------------------------------------- 5. picture
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+fig, axes = plt.subplots(1, 3, figsize=(12, 4.2))
+axes[0].scatter(cxy[valid, 0], cxy[valid, 1], c=gti[valid], cmap="tab10", s=2, linewidths=0)
+axes[0].set_title("annotation (cells)")
+axes[1].scatter(grid[:, 0], grid[:, 1], c=b_smooth, cmap="magma", s=5, marker="s", linewidths=0)
+axes[1].set_title("sheaf disagreement field")
+axes[2].scatter(grid[:, 0], grid[:, 1], c=labels, cmap="tab10", s=5, marker="s", linewidths=0)
+axes[2].set_title(f"spSheaf domains, k = {K}")
+for ax in axes:
+    ax.set_aspect("equal"); ax.set_axis_off()
+fig.tight_layout()
+fig.savefig(HERE / "quickstart_domains.png", dpi=150)
+print(f"wrote {HERE / 'quickstart_domains.png'}")