[francois-drielsma]

Description

Add graph.group_by to restrict GrapPA message-passing edges to nodes sharing a named cluster-label field. For example, graph: {provider: complete, group_by: ancestor} keeps the input nodes and removes edges between different ancestor groups. group_by: group restricts edges to particle groups.

Group IDs are derived from the majority voxel label within each node. Explicit node-aligned groups override the configured field. Full-chain graph preparation derives the IDs from clust_label, including during cache materialization. Existing cached or explicitly supplied edges are used as-is and must already carry the desired restriction.

Motivation and Context

Enable PID training with ancestor- or particle-group graph context through configuration, mimicking an upstream grouping stage without merging the input nodes or requiring a custom model caller.

Type of Change

• New feature (non-breaking change which adds functionality)
• Documentation update

How Has This Been Tested?

• GrapPA and full-chain model tests: 183 passed in the local spine:latest Docker image (Python 3.10, PyTorch 2.5.1).
• Regression coverage for group restrictions, explicit overrides, invalid settings, missing labels, cached edges, and full-chain group preparation.
• Black formatting, Python compilation, and git diff --check.

Reproduce the model tests with:

python -m pytest test/test_model/test_grappa/test_model.py test/test_model/test_full_chain/test_model.py -q

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• I have added tests that prove my feature works
• New and existing targeted unit tests pass

Additional Notes

The restriction applies during both training and evaluation, after graph generation and length cuts. Sparse graphs are filtered rather than rebuilt separately within each group. Matching negative IDs retain the existing same-group behavior; both this and cache regeneration requirements are documented.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.99%. Comparing base (6a1be8c) to head (8aa17b3).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #181   +/-   ##
=======================================
  Coverage   99.99%   99.99%           
=======================================
  Files         440      440           
  Lines       39282    39297   +15     
=======================================
+ Hits        39280    39295   +15     
  Misses          2        2           

Flag	Coverage Δ
unittests	99.99% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/spine/model/full_chain/ops.py	100.00% <100.00%> (ø)
src/spine/model/grappa/model.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.