Interpretation of segmentGroup element constructs

[halfflat]

Hello!

I'm in the process of providing support for reading NeuroML2 morphologies in the Arbor simulator (https://github.com/arbor-sim/arbor), and have some questions concerning the semantics of path and subTree elements within segmentGroup. I've been using https://neuroml.org/NeuroML2CoreTypes/Cells.html as a reference for the element semantics, and https://github.com/NeuroML/NeuroML2/blob/master/Schemas/NeuroML2/NeuroML_v2.0.xsd for the schema.

1. The schema has minOccurs="0" for both from and to elements within a path element. While a missing from element could be interpreted as meaning the path should be taken from the root segment (inclusive), what is the interpretation for a missing to element?

2. The subTree element can be expressed with a to element instead of a from element; is this intended to describe the subset of the morphology which is strictly proximal to the segment identified in to?

3. If I am interpreting the schema correctly, a subTree might have neither a to nor a from element. Does this denote the entire morphology? Or perhaps an empty subset?

[pgleeson]

Hi Sam,
Thanks for your interest in libNeuroML, and great that Arbor is adding more NeuroML support.

First off, the path and subTree elements are not widely used, and I can't recall seeing a working example with them. They can of course be useful though for more efficient definition of segment groups. If they need to be better specified that's certainly possible.

One way to make them easier to use and to ensure correct behaviour & test across different cells is to have a helper method in libNeuroML to actually do the calculation of which segments are meant in different scenarios (so that Python applications at least don't have to interpret/reimplement the meaning themselves). There is a method cell.get_all_segments_in_group() which already does this, but does not yet support path or subTree.

I've just added a notebook which demonstrates this and other helper methods for cells: https://github.com/NeuralEnsemble/libNeuroML/blob/development/notebooks/CellMorphology.ipynb.

Once the issues you mention are clarified I can add more exampels of usage there. Regarding your questions:

1. A missing to could certainly be confusing if there is a branch more distal to the from point. I guess it could be useful if you just want to give a from point on a distal unbranched dendrite and say "everything out to the tip" without explicitly naming the tip...
2. Yes, no from should mean: from the root. A to would mean "everything more proximal from this point".
3. Probably if both are missing then it should be interpreted as the whole tree.

Looking at this I think the best solution is to remove the path element and clarify the meaning of from (all segments more distal to this point; if missing, use root) and to (all segments more proximal from this segment without going "backwards", i.e. no going back up a different branch; if missing, assume it means all tips). In this way, a subTree contaning a to and from is just the same as a path: it will be the simple unbranched line between these points => no need for the path element...

@scrook Any thoughts, does this sound ok?

[halfflat]

Thanks for the explanation! A helper method in libNeuroML would certainly have helped clarify the semantics.

[halfflat]

One difference between the semantics as currently described, is that subTree refers to subsets of the morphology which exclude the named segment, while path is inclusive.

If the SegmentEndPoint type had an additional fractionAlong attribute, it could be used to specify exactly where these regions start and stop, and would make it more straightforward, I think, to describe them with a single construct.

[pgleeson]

Where is it suggested that the from segment is excluded from the subTree (or was that want you meant)? I think the from segment should be included.

On your second point, I can see the use case for defining the concept of "a subset of the morphology" with exact points defined by fractionAlong, but this is a bit different. It's a subelement of segmentGroup, and so explicitly defines a set of segments, no subdivisions. The other concept could potentially be added (I thought for a moment that that was what it referred to when you asked about fractional sections), but it's not there yet. Do you have a specific use case for that?

[halfflat]

Very good point about a fractional segment making it not a segment group: I didn't think this through! I don't have a specific use case, though we are mapping these elements to a description language that can make these sorts of distinctions. While a subregion of interest, in principle, needn't align with the sampling process used to define the morphology, it's certainly not something we need NeuroML to represent.

I presumed from was excluded because of the wording 'include all segments distal to that specified by from', and read that as being segments which were strictly distal and thus didn't intersect with the 'from' segment. It's fine if it is meant to be inclusive, but the text should probably be amended to make that clear (e.g. 'all segments distal to the proximal end of from').

[halfflat]

I realize I have been treating path incorrectly as well: as it is describing a segmentGroup it's not a path in the topology of the morphology as such, because the segments collected may not constitute an unbranched region of the morphology.

When reasoning about what is and isn't included in segmentGroup path and subTree specifications, is it the parent–child relationship that is important, or the morphological topology as defined by parent and fractionAlong relationships?

As an example:

<neuroml xmlns="http://www.neuroml.org/schema/neuroml2" id="hello">
<morphology id="example1">
    <segment id="0">
        <proximal x="0" y="0" z="0" diameter="1"/>
        <distal x="2" y="0" z="0" diameter="1"/>
    </segment>
    <segment id="1">
        <parent segment="0" fractionAlong="0.5"/>
        <distal x="1" y="1" z="0" diameter="1"/>
    </segment>
    <segmentGroup id="path01">
        <path>
            <from segment="0"/>
            <to segment="1"/>
        </path>
    </segmentGroup>
</morphology>
<morphology id="example2">
    <segment id="0">
        <proximal x="0" y="0" z="0" diameter="1"/>
        <distal x="1" y="0" z="0" diameter="1"/>
    </segment>
    <segment id="1">
        <parent segment="0"/>
        <proximal x="1" y="0" z="0" diameter="1"/>
        <distal x="2" y="0" z="0" diameter="1"/>
    </segment>
    <segment id="2">
        <parent segment="1" fractionAlong="0"/>
        <proximal x="1" y="0" z="0" diameter="1"/>
        <distal x="1" y="1" z="0" diameter="1"/>
    </segment>
    <segmentGroup id="to2">
        <subTree>
            <to segment="2"/>
        </subTree>
    </segmentGroup>
    <segmentGroup id="from1">
        <subTree>
            <from segment="1"/>
        </subTree>
    </segmentGroup>
</morphology>
</neuroml>

Here, is it correct to say that path01 in example1 contains the two segments 0 and 1, and thus is the whole of the (branched) morphology?

In example2, segment 1 is not proximal to segment 2 — they are sibling branches in the morphology — but segment 1 is segment 2's parent. Should segmentGroup to2 comprise all three segments 0, 1 and 2, or just 0 and 2? Similarly, does segmentGroup from1 comprise segments 1 and 2, or just segment 1?

[pgleeson]

Good points... Though my first inclination is to use definitions independent of the fraction along, just use the parentage, i.e. follow paths just using the child parent relationship. In your example it would be tricky with seg 2 connected to the proximal of seg 1, but the reconstructor/modeller has still chosen seg1 as the parent, so that's the relation to be used. Taking fractions into account would be a bit strange when you specify from/to in terms of just segment ids and return a set of whole segments.

Next step would be to implement the helper method for these and add examples to the notebook to test/clarify these ideas. That would be a week or two for me. I hope this isn't holding you up for NeuroML support implementation...

[halfflat]

Thanks for the response! This does clarify the correct and consistent interpretation. With any luck, I'll have our NeuroML morphology support in Arbor next Monday :)

Ultimately it will be helpful for this to be made explicit in the existing documentation, but the helper method will be very useful for verification.

[pgleeson]

Thanks. Happy to try out Arbor when the NML support is stable. Please let me know when there's a new release.

Yes, docs should be updated too. Thankfully there is a pipeline for generating the documentation from the comments in Lems here, but it just has to be tested and written...