This one can get surprisingly deceiving! Formally, it’s the latter: using the -stop option will stop tracking the moment a track has at least hit all -include regions. So the last-include region that track happens to hit, will definitely not be traversed. All the other ones probably will.
Where this may still catch you off guard, is when combined with bidirectional tracking (which also happens to be the default, so it’s not unlikely someone may run into this): since bidirectional tracking just tracks in one direction first, and only thereafter in the other direction, the former direction’s tracking process has no idea of which -include regions the other tracking direction may hit; so unless it already hits all -include regions, it’ll happily continue tracking (until other tracking constraints are violated) before the other direction is allowed to start. So actually, the -stop option only really makes sense (most of the time) when combined with the -unidirectional option.
Trying to forget this information and reading the -stop option help text again, I can indeed see how it may suggest all regions have to be “traversed”… since, well, it’s using that actual verb in the text. But I guess it comes down to your specific interpretation of “traverse”. Maybe “visit” is a better verb to describe the behaviour. What do you reckon, @jdtournier, @rsmith, @Dave?
Apart from the help text, I remember us discussing the behaviour when tracking bidirectionally in the past as well. A naive suggestion that has come up, was to have both directions track “at the same time” and “at the same speed” (so as to not bias the outcome to the first chosen direction). But when you think about it, this is just as arbitrary, and will in no way generate a more desirable outcome. Thinking about it now, I can see an alternative suggestion: we could track in one initial direction as before, and then in the other, but when it hits the final region in the other direction (and the -stop option cuts it short), we could truncate the existing other end up to (just before) the point where it would otherwise lose an -include region. If -include regions exist in both directions, that’d mean the track nicely stops at both ends’ “last” -include region. Would that better match the behaviour most people would expect from -stop combined with bidirectional tracking, without them having to understand how bidirectional tracking is implemented?
Not sure if it’s worth looking into (we’re all super busy at the moment); maybe something for the longer term feature/brainstorm list?
So wait… wut ?! I did specify the -stop option, right? So why ain’t it stopping at either end then? Well, it is. In about 50% of the cases it’s stopping at the cyan region’s boundary, and in the other half at the magenta region’s boundary. Here’s what you may discover when lowering the tracks’ opacity (and changing their colour, for optimal visibility):
The sudden drop in track counts happening at the cyan and magenta regions’ boundaries confirms a significant portion of tracks has endpoints there. Because the bidirectional tracking chooses a random initial direction, this happens randomly at the cyan or magenta ends. The yellow region is always nicely (completely) “traversed”.
The potentially alternative behaviour I suggested in my previous post, would have all tracks truncated at both cyan and magenta ends, so you’d only have the portion of the cingulum between those regions.
Yes, unfortunately the -stop option was always a bit of a hack, implemented as a result of multiple user requests. I think to fix this properly requires a bit of a rethink. The way I see it, most users will expect one (or two) of their include ROIs to force track termination, with all other include ROIs treated as waypoints - they need to be visited, but streamlines shouldn’t be terminated there. The current implementation doesn’t allow this level of distinction, which means it has to use a ‘best guess’ policy, which clearly isn’t adequate…
So to get around this will I think require the definition of an -endpoint ROI, most likely with the renaming of -include to -waypoint or -via or similar. This would additionally allow control over whether the streamline will be terminated upon entry into the endpoint ROI, or upon exit. But it is quite a radical change to be making, it’ll probably break a few people’s scripts… Maybe this would fit nicely into the updated_syntax merge…? Although if we keep the name as -include, the only people affected would be those using the -stop option, and presumably they would welcome such a change anyway.
I feel a GitHub issue coming along here. Thoughts welcome…
Using the current behaviour, and if in your case the tracks are clearly coming from a specific “end” of the “last” inclusion region, you could patch it up by adding an extra inclusion region bordering the “last” inclusion region at its “far end”… if that makes sense…
Not really in favour of splitting -include regions into -endpoint and -waypoint for the sake of making -stop work as expected (at least not based on the current implementation; I’d rather have ‘wm’ and ‘gm’ ROIs, but that’s another story).
Really the expected behaviour here is that -stop should make include regions double as track masking. So one alternative would be to process it in this fashion. Let tracks generate as far as they like, but then crop at either end based on ROI visitation: either to the last point that is within any ROI, or to the first point that ensures that all ROIs are visited (probably with two mutually-exclusive command-line options). Possibly with a little trickery to account for tracks that double back on themselves.
Yes, I guess fixing the -stop option is probably the simplest thing to do here. Also has the advantage of not modifying the current interface. Maybe we can file an issue for this?
That said, I think that having the ability to specify which of your inclusion ROIs are also stopping ROIs is potentially beneficial. For instance, imagine trying to track the fibres of the corpus callosum that link lower limb motor-sensory cortices (i.e. the midline bits of the motor strip). Just placing two ROIs in each motor cortex produces the expected tracks plus lots of direct streamlines through the midline fissure. So one option is to add another inclusion ROI in the midbody of the corpus callosum. That helps, but there’s still loads of streamlines crossing over the midline fissure. Adding the -stop option seems like the right fix here, but because you can’t tell it which ROIs are endpoints, it still allows streamlines to cross the midline fissure and terminate in the midbody ROI.
That’s just an example, and could be fixed up any number of ways, including more advanced techniques like ACT. But the point is this is a simple example where the distinction would make a big difference.
Not saying we need to do something about this now, but I reckon it’s worth discussing as a possible future enhancement.