feat: add distance_from_node_set

[elhb]

Description

Add distance_from_node_set so segmentation can compute hop distances from seed nodes.

Multi-source BFS on a PNAGraph. Seeds get distance 0. Other nodes get the shortest unweighted path to the nearest seed, up to max_iter (default 40). Unreached nodes stay missing (None). The result is written as node attribute distance_from_seed, replacing that attribute if it already exists. The same graph instance is updated in place and returned. Missing seeds raise ValueError (seed nodes must be present), matching R.

Fixes: PNA-3550

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

Python unit tests only (no R gold files). Tests use a synthetic bipartite line plus a disconnected edge and check exact hops, multiple seeds, max_iter, attribute replacement, and the missing-seed error.

pytest tests/pna/analysis/test_distance_from_node_set.py

PR checklist:

• This comment contains a description of changes (with reason).
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have checked my code and documentation and corrected any misspellings
• I have documented any significant changes to the code in CHANGELOG.md

---

Note

Low Risk
Additive analysis helper that mutates graph node attributes in place; no pipeline or auth changes, with broad unit test coverage.

Overview
Adds distance_from_node_set for PNA segmentation: multi-source BFS on a PNAGraph annotates each node with integer hop distance to the nearest seed (or missing if unreachable or beyond max_iter, default 40). Results are written in place on the distance_from_seed node attribute; the same graph is returned.

The function lives under pixelator.pna.analysis.segmentation and is re-exported from pixelator.pna.analysis. Inputs are validated ( PNAGraph, non-empty seeds present in the graph, max_iter type/range). Optional verbose logs per-iteration reach counts.

CHANGELOG and docs/api/overview.rst document the new API. Unit tests cover single/multiple seeds, max_iter, attribute replacement, errors, and the public export.

^{Reviewed by Cursor Bugbot for commit f35750a. Bugbot is set up for automated code reviews on this repo. Configure here.}