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

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.

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