3d-pli / SLIX

Scattered Light Imaging ToolboX (SLIX) – an open-source Python package that allows a fully automated evaluation of SLI measurements and the generation of different parameter maps
MIT License
6 stars 3 forks source link

[DOC] Main Functionality Example #4

Closed alexrockhill closed 3 years ago

alexrockhill commented 3 years ago

I ran the first example and got the following figures output.zip. They look a bit sparse.

To make "a detailed reconstruction of the brain's nerve fiber architecture" as said in the paper, seems to me to be more like Figure 2i which I don't see in the output.

It would be helpful to have 1) explanations like those in the last section of the README for the examples and 2) the example generate a figure like 2i which I think would better qualify as a reconstruction of nerve architecture

Also, it is not immediately obvious how one would proceed with Figure 2i as input to do some kind of analysis. To bring up freesurfer as an example again, in the reconstruction you have different brain regions segmented out in volumetric boundaries. This seems like a fairly crucial part of a reconstruction; to have some format separating each nerve fiber. Perhaps I am not understanding the directional .tiff images appropriately if they in fact do just that.

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

miriammenzel commented 3 years ago

Thank you very much for your comment.

When looking at the parameter maps of the first example, you should keep in mind that the maps were generated with lower resolution (5 x 5 pixels are combined into one). Therefore, the parameter maps show less detail. You can generate the high-resolution maps by running the example without --roisize 5 (this takes 25 times longer). In the “sparse” images, regions that cannot be evaluated are set to -1 (shown in white in Figure 2f,g,h): As described in the “Output” section of the README, the peakdistance (in “_peakdistance.tiff”) is only defined if the SLI profile has not exactly two prominent peaks; the in-plane direction angles (in “_dir,1,2,3.tiff”) are only defined if the SLI profile has two, four or six prominent peaks with a pair-wise distance of (180 +/- 35)°. The parameter map “_dir_1.tiff” contains the smallest detected fiber direction angle. If there exists only one fiber, its orientation is shown in “_dir_1.tiff”. The parameter map “_dir_2.tiff” (“_dir_3.tiff”) shows the second (third) fiber direction in regions with two (three) crossing fibers. As the sample does not contain many regions with two crossing fibers and no regions with three crossing fibers (the sample consists of two fiber bundles/optic tracts, artificially placed on top of each other), there are a lot of values with -1 within the tissue. For visualization purposes, Figure 2h in the JOSS paper shows the direction angle phi_1 in all image pixels where phi_2 is not defined (non-crossing regions). We will point this out in the caption of Figure 2 and in the description of the parameter maps in the README. In addition to that, we will provide the full set of parameter maps and a more detailed description in the “Resulting parameter maps” section.

Concerning Figure 2i, this is only a visual representation of the data contained in the direction .tiff images (g,h): The direction angles for a certain region (here: 24 x 24 pixels) were represented by a line with the respective polar/direction angle. To generate the image, we used a simple FIJI Macro. In principle, any visualization tool that is able to represent multiple unit vectors as lines can be used. The visualization is not part of the SLIX software. If you like, we can provide the FIJI Macro to give users a more intuitive/visual understanding of the data?

The parameter maps generated by SLIX, especially the direction images, enhance the current reconstruction of nerve fiber orientations (obtained e.g. with 3D-Polarized Light Imaging), by adding crucial information about the orientations of crossing nerve fibers (in microscopic image pixels). Note that “reconstruction” is here used to describe the reconstruction of fiber orientations, i.e. a vector map containing different (crossing) nerve fiber orientations, not the nerve fibers themselves. Different brain regions can be determined from structures in the measured image stacks and in the derived parameter maps. A segmentation of brain regions is not aim of the reconstruction. We are only interested in the course, i.e. the orientation vectors of (crossing) nerve fibers in each image pixel (see also Response to #7).

alexrockhill commented 3 years ago

That all makes more sense, thanks for the explanation. I think the example could be greatly improved by walking the user through what you've just explained, whereas now they are just given the outputs without explanation.

Re the orientation vectors vs reconstructed fibers, I agree that this ties in with #7 and, I don't mean to be overly constrained toward the TRACULA approach to analysis as from my background that is what I know best, but I think it could be clarified by an example and/or more documentation what to do with the output to get to a place where a more diverse set of users could understand what to do and what software packages or what needs to be done that would help them continue their analysis.

alexrockhill commented 3 years ago

Re the FIJI Macro, specifically, that maybe wouldn't be my first choice as a dependency personally, which seems like maybe why it isn't already included, and pure python solution maybe be the ideal fit for this particular package (maybe in matplotlib if possible or mayavi) but my particular comment as it pertains to the review point about the functionality claim of SLIX that it reconstructs fiber orientation is hard to verify without an example that finishes with visualizations of fiber orientations. If there are third party dependencies and that are only included for the example, to me that's okay, but it is hard to review this package without some visualization of results.

matteomancini commented 3 years ago

I ran the first example as well, but without downsampling, trying to replicate the figures in the section "Resulting parameter maps". However, for some reason the results are different from the ones showed in the README (screenshot for direction 1 attached).

Screenshot 2020-10-15 at 11 00 21

I tried both on macOS Catalina and on Ubuntu 18.04, and the results are the same. If it a visualisation issue, is it possible to advise for a suitable image viewer? Here are the actual maps generated: Archive.zip On a related note, I wanted to say that I really appreciate the recent inclusion of the progress bar! 👍

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

miriammenzel commented 3 years ago

@matteomancini: The generated parameter maps look good (how long did it take for you to run the example with full resolution?) Which image viewer did you use? It seems that the image does not show the full range of values (-1 is displayed in dark gray values, all other values are shown in white). Examples for suitable image viewers are ImageJ or FIJI (https://imagej.net/Fiji). We will add a note in the README.

matteomancini commented 3 years ago

Thanks @miriammenzel it makes sense, I was using normal image viewers (e.g. Preview on macOS). I did not recorded execution time, but it was more or less 1 hour on macOS (2.8 GHz Quad-Core Intel Core i7) and around 30 minutes on Ubuntu (2.1GHz 8 Core Intel Xeon Silver 4110).

miriammenzel commented 3 years ago

The updated README.md now includes a thorough description and explanation of all resulting parameter maps and outputs (here). We also added a revised version of the paper, where we explain how the subfigures in Figure 2 were generated.

We are currently working on a visualization of the vector maps (with Python) – we will let you know as soon as this is done. We are also working on providing a brief tutorial to walk the user through all steps and provide different possibilities for visualization. We hope that this will clarify what the user can do with the output. @alexrockhill @matteomancini: Would this meet your requirements?

miriammenzel commented 3 years ago

We have now added a tutorial (Jupyter notebook) that walks the user step by step through the computation of the parameter maps and shows how the parameter maps can be visualized. We have added the file visualization.py that allows to display parameter maps with a certain color map (using matplotlib), and to visualize the fiber orientations as vector maps (colored lines displayed on top of the original image), which is also demonstrated in the tutorial. In addition, we included everything in a Wiki and also added API documentation for toolbox.py and visualization.py. @alexrockhill @matteomancini: Please let us know if this meets your requirements and if we can close this issue.

matteomancini commented 3 years ago

As mentioned in #7 I think the notebook really does the job, also in terms of providing further examples!

alexrockhill commented 3 years ago

Looks great