Handling Hierarchical Region Data

[willGraham01]

The API needs to be able to handle hierarchical information about the regions of a dataset. Not all of these are at the most granular level (the nodes), but may instead be groupings of several nodes in the dataset.

Broadly speaking, there are multiple parts to this, that we may want to split out into sub-issues:

• Connections objects should be able to read in Brainglobe hierarchical data concerning the regions of a given dataset, making this information accessible in some way through the API.
  • Initially this information should be read in through an additional, optional file. But it will be placed inside the existing node_info attribute of the relevant objects.
  • There will need to be some convenience wrapper functionality around selecting nodes by a level in the hierarchy.
• We need to be able to "collapse" nodes that belong to a single region into a single node.
  • Ask Larry or Joel for the exact procedure that needs to be implemented.
  • This would likely be a method on the Connections class, like collapse_to(*regions) that takes a variable number of positional arguments and returns a version of the network where the given regions are collapsed to a single node?
• We need to think about how we implement methods like "shortest path from node X to region A", where region A is at a higher level in the hierarchy.
  • If node X is inside region A, this is interpreted as distance to all other nodes in region A, for example.
  • If node X is outside region A, this is shortest paths to region A (which requires node collapses).
  • TLDR we need to derive some kind of standard interface / convention for when passing a region causes a "collapse" and when it simply constitutes a "selection" of nodes.