spatial-graph-algorithms 0.1.0

Unified toolkit for sequencing-based spatial microscopy graph analysis

spatial_graph_algorithms

Python package for analysing proximity graphs from sequencing-based spatial microscopy (Slide-tags, Pixelgen, and similar).

Takes a raw edge list → simulate, denoise, reconstruct coordinates, and score quality in one coherent package.

Documentation · Quickstart · Example notebook

pip install spatial-graph-algorithms
pip install "spatial-graph-algorithms[all]"  # Node2Vec, PyMDE, PaCMAP

---

---

Quick start

from spatial_graph_algorithms.simulate     import generate
from spatial_graph_algorithms.reconstruct  import reconstruct
from spatial_graph_algorithms.metrics      import evaluate
from spatial_graph_algorithms.plot.network import plot_network, plot_comparison

# simulate a 500-node circular tissue graph with 5 % spurious edges
sn = generate(n=500, shape="circle", mode="knn", k=8,
              false_edges_fraction=0.05, seed=42)

# reconstruct coordinates from topology alone
sn = reconstruct(sn, method="mds", dim=2, seed=42)

# score the reconstruction
m = evaluate(sn)
# m["cpd"] ≈ 0.98,  m["knn_preservation"] ≈ 0.77

---

Gallery

Simulated graph (false edges in red)	Reconstruction vs ground truth

Nine graph construction modes ship out of the box:

---

Modules

Module	Status
simulate — point clouds + 9 graph modes + false-edge injection	stable
reconstruct — MDS, STRND; UMAP/Isomap/Node2Vec/PaCMAP/PyMDE optional	stable
metrics — CPD, kNN preservation, distortion, graph summary	stable
plot — network, 3-D, edge-length histogram, reconstruction comparison	stable
denoise — Leiden, Jaccard, betweenness, bipartite filters	in progress
coherence — spatial constant, dimension prediction, promiscuity	in progress

All modules consume and return a SpatialGraph — a thin dataclass holding the adjacency matrix, ground-truth positions, reconstructed positions, and node/edge metadata.

---

Architecture

See ARCHITECTURE.md for the full design doc. Summary:

src/spatial_graph_algorithms/
├── network.py           # SpatialGraph dataclass — shared by every module
├── simulate/            # point cloud generation + 9 graph construction modes
├── reconstruct/         # coordinate recovery (MDS, STRND, …)
├── metrics/             # quality scoring and graph structure summaries
├── plot/                # matplotlib figures
├── verify/              # end-to-end pipeline runner (writes CSV + PNG artefacts)
├── denoise/             # (in progress) edge noise removal
└── coherence/           # (in progress) spatial coherence analysis

Every function takes and returns a SpatialGraph — nothing hides state. Modules only import from modules earlier in the pipeline; simulate never touches reconstruct, metrics never touches plot.

Module	Owns	Does not own
network	SpatialGraph schema and validation	Creating or analysing graphs
simulate	Synthetic graph generation	Real-data I/O
reconstruct	Coordinate recovery algorithms	Graph creation or quality scoring
metrics	Quality metrics and structure summaries	Plotting or file I/O
plot	Figures	Saving results or running algorithms
verify	Pipeline orchestration and artefact writing	Any algorithm logic

---

Contributing

See CONTRIBUTING.md and the full docs. Run pip install -e ".[all]" && pytest to get started — 50 tests, all should pass.

---

MIT license · David Fernandez Bonet