feat: Stack regions and Layer partitions

[drodarie]

Describe the work done

Stack will now use its children's stack_index attribute to order them in the stack before repositioning them.
In practice, a Layer of a Stack can "decide" of its position within it.

List which issues this resolves:

Closes #867

Tasks

• Added tests

---

📚 Documentation preview 📚: https://bsb--868.org.readthedocs.build/en/868/

[Helveg]

I gave notes to change the UX of the Stack with more feature parity to what stacks were in BSB3, and what I think is a more rich and intuitive user experience.

[Helveg]

just noticed that anchor refs any partition/region

[Helveg]

Atm the ref can be any partition/region, even non-children. This can either be:

• allowed and your intention: this would allow "out of stack anchors", but then we need to drop the backref="region" (backref would set the target's region to this region, effectively transferring/stealing it from its parent)
• not your intention: swap to a new ref function to strictly one of the children (not sure if a ref to a ref works, probably untested)

[drodarie]

Never thought of making a ref to a ref 😮 but I managed to make it work with just a ref. The function _resolve_anchor_offset should check if the ref belongs to the children. I can also add a test for that.

[drodarie]

@Helveg what is the purpose of volume_scale in the Layer class. It does not seem to be used at the moment?

[Helveg]

It was a feature to scale the dimensions of one layer according to the volume of another layer, so that you could have e.g. 20^mm3 of IO per 200^mm3 of cerebellar cortex, see #191

We can remove it until it is reimplemented :)

[drodarie]

I am not sure how you wanted to implement it. At the moment, volume_scale is a list of 2 floats?
If I understand your feature correctly, I would need to provide the ref Partition and the volume ratio. so I guess one of the float serves as a way to fetch the ref partition?

[Helveg]

I would not advise you to implement volume_scale at this point, I think we can just remove it. The floats were originally ratios of the dimensions. Let's say you volume scale to another ref with the floats to [1, 1, 1] then you'd create a cube scaled to the ref, when you'd [1, 2, 1], the second dimension would be twice as large as the other 2 dimensions. So they'd essentially determine the shape of the scaled volume.

If there were only 2 floats, perhaps the third value was always ommited andassumed to be the axial dimension, and was always 1 as a reference point? I don't know, but that's what I remember of the feature.

I think this feature was used by @AliceGem to scale the IO layer. I'm not sure who works on cereb-IO models now, and whether they require this feature? If anyone working on that model wants to move to BSB4, and requires this feature, we can reimplement it from the git history.

[drodarie]

Needs dbbs-lab/bsb-arbor#3 to be merged.

[codecov]

Codecov Report

Attention: Patch coverage is 98.27586% with 1 line in your changes missing coverage. Please review.

Project coverage is 88.85%. Comparing base (f1d26b2) to head (938274c).
Report is 21 commits behind head on main.

Files	Patch %	Lines
bsb/topology/partition.py	90.90%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #868      +/-   ##
==========================================
+ Coverage   87.89%   88.85%   +0.95%     
==========================================
  Files         103      110       +7     
  Lines       13771    15088    +1317     
==========================================
+ Hits        12104    13406    +1302     
- Misses       1667     1682      +15     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.