[DOC] Integration with Fiber Tractography Software

[alexrockhill]

In your bioarxiv paper, it says "We developed the open-source software SLIX (Scattered Light Imaging ToolboX) that allows an automated evaluation of the measurement, and the computation of different parameter maps containing various tissue information. The resulting fiber direction maps can be used, for example, as input for fiber tractography algorithms."

From the perspective of a user, I'm not sure if SLIX meets the JOSS requirement that "that software should be feature-complete" without documentation and an example on how to integrate with a tractography software or algorithm. It looks like it is very close to being able to be used in a TRACULA pipeline for instance (there might be a step or two missing such as coregistration), but it is not apparent, to me at least, how the SLIX output images would be integrated.

https://github.com/openjournals/joss-reviews/issues/2675

[miriammenzel]

There exist different ways and existing tools how the parameter maps generated by SLIX can be further processed. The direction maps generated by SLIX contain the in-plane direction angles of the nerve fibers, which can be used as a-priori information for tractography algorithms or as direct input (in-plane vector maps) for further analysis. For example, the in-plane direction angles can be combined with out-of-plane inclination angles obtained from 3D-Polarized Light Imaging measurements of the same tissue sample to generate three-dimensional vectors in space. Using existing registration tools, the average intensities of consecutive brain sections can be registered onto each other, hence creating a volume of (crossing) vectors. This set of unit vectors can be used as direct input for streamline-based tractography algorithms, as described in https://doi.org/10.1007/978-3-658-25326-4_17 . The input needed depends on the implementation of the tractography algorithm, and there exist already other registration and tractography tools. Therefore, SLIX provides the direction maps (and other parameter maps) to keep the software as focused as possible.

[alexrockhill]

That all sounds very reasonable, and I understand better how you would actually use the outputs. I think it would help add an example of using other tractography registration and analysis softwares to do just one example of an analysis with the output. This wouldn't have to add core dependencies to SLIX, if the software tools were not used in the core API but just in the examples.

[matteomancini]

I agree with @alexrockhill - as someone who works with tractography but is not that familiar with light imaging it is not immediately clear to me how to practically use the output of SLIX to inform a tracking algorithm implemented in some software (e.g. MRtrix, Diffusion Toolkit). I think that something that could help to immediately make the connection would be some functionality to either generate automatically the vectors represented in figure 2i (as it was mentioned in #4 - ideally in Python) or to show how to use one of the maps available at the moment as an input to an existing tracking tool.

@miriammenzel I think that the procedure you describe is very interesting, but also has some challenges, as registering contiguous sections to reconstruct a 3D volume leads to several issues (e.g. "banana" effect, z-shift). Of course these go beyond the scope of SLIX and the JOSS paper, but this is to say the overall procedure could quickly become quite complex. Again, I do not believe such an elaborate example (involving registration and tracking) is required to present an interesting tool such as SLIX. What would make it feel more complete is explaining how one of the outputs could be easily used to inform tracking procedures.

[miriammenzel]

Thank you for your replies. We are currently working on an automatic generation and visualization of the vector maps (with Python) – we will let you know as soon as this is done. The vector maps could be used as input e.g. for streamline tractography algorithms. Unfortunately, we have not yet enough data to perform tractography on 3D volumes (we would need a sufficient number of consecutive brain sections measured with SLI that we can register onto each other to generate a 3D volume of vectors). This is part of future work (and will not change the scope of SLIX - as the tool does not include registration or tractography).

[miriammenzel]

We have added the automatic generation of unit vectors from a given direction image (visualization.py). The unit vectors could be used for example as input for streamline tractography algorithms. The tutorial shows how the vector map can be visualized (similar to the vectors shown in figure 2i, see last image in the tutorial) so that the user is now able to reproduce all figures, including the vector maps. Furthermore, we added a statement to the Introduction to explain the purpose of SLIX: it allows to transform the raw data of SLI measurements to parameter maps that can be interpreted by researchers or be used for further analysis, e.g. tractography. If other output formats are required, this can be easily added to the software. To explain the user how to contribute to SLIX, e.g. adding new features, we added the section “Feature additions” in the CONTRIBUTING.md. @alexrockhill @matteomancini: Please let us know if this now meets your requirements and if we can close this issue.

[alexrockhill]

The tutorial looks really good, and is much more what I would consider as meeting the requirements for a full solution. I'll take a look later about the actual results now that the process can be worked through in python to the unit vector visualization.

The title of this issue is on the integration with tractography software, if there were to be one or two cells added at the end of the tutorial on how to integrate with your preferred tractography software I still think that would be a helpful addition.

[miriammenzel]

Thank you @alexrockhill for the suggestion. We have now added the section “Possible Integration in Tractograpy Algorithm” at the end of our tutorial to explain how the unit vector maps obtained by SLIX can be prepared to be used as input in streamline-based tractography algorithms (seed points propagating through the vector field). As we currently have no data set available that could be used as input (as mentioned above, we would need SLI measurements of several consecutive brain sections to generate a sufficient 3D volume of unit vectors), we show an example where a 3D vector field (obtained by 3D Polarized Light Imaging) has been used as input for in-house developed tractography software. @alexrockhill: Please let us know if this meets your requirements and if we can close this issue.

[matteomancini]

I think that the notebook looks amazing and it really makes things clear!

[alexrockhill]

I second @matteomancini, this looked like a bit of effort but I think it improves the toolbox so thank you for incorporating the feedback