Skip to content

Module: coherence

File: src/spatial_graph_algorithms/coherence/__init__.py Status: Compatibility alias for spatial_graph_algorithms.spatial_coherence.

Purpose

coherence is kept for older imports. New code should use:

from spatial_graph_algorithms.spatial_coherence import score

Calling spatial_graph_algorithms.coherence.score forwards to the same implementation.

Planned Scope

Assess how spatially coherent a graph is — i.e., how consistent its topology is with an underlying low-dimensional spatial embedding.

A spatially coherent graph follows a scaling law: the mean shortest path S grows as

S ~ n^(1/d)

where n is the subgraph size and d is the effective spatial dimension. A graph derived from a 2-D tissue section should give a slope of ~0.5 in log-log space.

Current API

from spatial_graph_algorithms.spatial_coherence import score

result = score(sg)
# returns Gram-matrix spectral coherence metrics

Planned Functionality

Feature Description
Spatial constant estimation Slope of log(S) vs log(n) over BFS subgraph growth
Effective dimension prediction 1 / slope — expected ~2 for 2-D tissue, ~3 for 3-D
Promiscuity / viewpoint analysis Identify nodes with anomalous shortest-path behaviour
R² goodness of fit How well the scaling law holds — low R² → incoherent graph

The NSC reference implementation is in: /home/david/PycharmProjects/Spatial_Constant_Analysis/src/network_spatial_coherence/spatial_constant_analysis.py and promiscuity_measures.py.

Follow-Up Implementation Notes

When adding the planned scaling-law features, implement them in spatial_coherence, not in this compatibility package:

  1. The core computation is a BFS subgraph growth experiment:
  2. Sample k random seed nodes.
  3. For each seed, grow a BFS subgraph to sizes [10, 20, 50, ..., n].
  4. Compute mean shortest path within each subgraph.

  5. Fit log(S) ~ slope × log(n) with scipy.stats.linregress.

  6. Use scipy.sparse.csgraph.shortest_path for all path computations — do not use NetworkX shortest paths for large graphs (much slower).

  7. The result should be a plain dict (not a SpatialGraph) since this is analysis output, not a transformed graph.

  8. Optional: return a pd.DataFrame of the raw (n, S) values alongside the summary dict so callers can plot the scaling curve themselves.

  9. No new mandatory dependencies are needed — scipy and numpy are sufficient.

Compatibility File Structure

coherence/
└── __init__.py       — forwards score() to spatial_coherence.score