Metadata-Version: 2.4
Name: spatial_graph_algorithms
Version: 0.1.0
Summary: Unified toolkit for sequencing-based spatial microscopy graph analysis
Author-email: David Fernandez Bonet <davferdz@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/DavidFernandezBonet/spatial-graph-algorithms
Project-URL: Documentation, https://davidfernandezbonet.github.io/spatial-graph-algorithms/
Project-URL: Repository, https://github.com/DavidFernandezBonet/spatial-graph-algorithms
Project-URL: Bug Tracker, https://github.com/DavidFernandezBonet/spatial-graph-algorithms/issues
Keywords: spatial omics,graph analysis,spatial transcriptomics,network reconstruction,slide-tags,pixelgen,proximity graph,node2vec,umap,mds
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: pandas>=1.3
Requires-Dist: networkx>=2.8
Requires-Dist: python-igraph>=0.10
Requires-Dist: scikit-learn>=1.0
Requires-Dist: matplotlib>=3.5
Provides-Extra: strnd
Requires-Dist: umap-learn>=0.5; extra == "strnd"
Requires-Dist: pecanpy>=2.0; extra == "strnd"
Provides-Extra: leiden
Requires-Dist: leidenalg>=0.9; extra == "leiden"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: all
Requires-Dist: umap-learn>=0.5; extra == "all"
Requires-Dist: pecanpy>=2.0; extra == "all"
Requires-Dist: leidenalg>=0.9; extra == "all"
Requires-Dist: torch>=2.0; extra == "all"
Requires-Dist: pymde>=0.1; extra == "all"
Requires-Dist: pacmap>=0.7; extra == "all"

# spatial_graph_algorithms

[![Tests](https://github.com/DavidFernandezBonet/spatial-graph-algorithms/actions/workflows/tests.yml/badge.svg)](https://github.com/DavidFernandezBonet/spatial-graph-algorithms/actions/workflows/tests.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://davidfernandezbonet.github.io/spatial-graph-algorithms/)
[![PyPI](https://img.shields.io/pypi/v/spatial-graph-algorithms)](https://pypi.org/project/spatial-graph-algorithms/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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](https://davidfernandezbonet.github.io/spatial-graph-algorithms/) · [Quickstart](https://davidfernandezbonet.github.io/spatial-graph-algorithms/quickstart/) · [Example notebook](examples/spatial_graph_algorithms_demo.ipynb)**

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

---

<p align="center">
  <img src="docs/images/pipeline_banner.png" width="88%">
</p>

---

## Quick start

```python
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 |
|:---:|:---:|
| ![](docs/images/simulated_network.png) | ![](docs/images/reconstruction_comparison.png) |

Nine graph construction modes ship out of the box:

<p align="center">
  <img src="docs/images/simulation_modes.png" width="75%">
</p>

---

## 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](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](CONTRIBUTING.md) and the [full docs](https://davidfernandezbonet.github.io/spatial-graph-algorithms/). Run `pip install -e ".[all]" && pytest` to get started — 50 tests, all should pass.

---

MIT license · David Fernandez Bonet
