[DOC] Methods explanations

[alexrockhill]

JOSS policy requires "A summary describing the high-level functionality and purpose of the software for a diverse, non-specialist audience."

Methodological choices such as why 8% prominence is used to qualify as a prominent peak or even why using prominent peaks is the best method for identifying crossing fibers don't seem readily understandable from the paper and documentation for a diverse audience.

Perhaps the best way to explain the methods would be to have an example or documentation walking the user through the process from raw data through each of the figures and to the output, considering parameter and processing choices along the way.

How and when to use --with_mask and --with_smoothing especially are not readily apparent.

EDIT: from reading appendix A of the Bioarvix paper, I see why you chose 8% prominence but it seems like the intensity range (Imax - Imin) may vary across setups, I'm not sure I would use 8% as a hard rule but would want to maybe check on some small section of the data that could be inspected manually or some other solution. Or maybe the goodness-of-fit and this and other parameters can be ascertained from Figure 8 (the parameter maps) but it is not clear from the documentation how to do so.

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

[miriammenzel]

We agree that we should motivate the use of 8% prominence. We will include a more detailed explanation (and a reference to Appx. A) in the Summary of the JOSS paper and in the “Introduction” of the README. The derivation of the 8% value is a major part of the arXiv paper and cannot be explained here in full detail. To obtain this value, many different brain regions with (crossing) nerve fibers and well-known fiber orientations have been considered. In this way, we could find the best compromise between correctly and wrongly detected peaks. Usually, we do not know the true underlying fiber orientations of the tissue. Therefore, it is important to know for which prominence the peaks are indicators of the fiber orientations, and for which prominence the peaks are caused by noise or details in the fiber structure that are not of interest. This cannot be determined on a small section of the data. The value of 8% prominence has been shown to be the optimal choice for the generation of reliable fiber orientations. If you like, we can add an optional parameter that allows experienced users to change this value? (although we would not recommend this).

You are right that the signal amplitude (I_max – I_min) may vary across setups. Therefore, the prominence is defined as a percentage of the signal amplitude (after normalizing the signal by the average value, i.e. accounting for different input intensities).

It is not possible to compute a goodness-of-fit because the SLI profiles are very different in shape and cannot be fitted by a reasonable function without overfitting. However, the parameter maps show indirectly how reliable the results are: The “low_prominence_peaks” map shows the number of peaks with a low prominence; the “high_prominence_peaks” map shows the number of peaks with a high prominence. In addition, the “peakprominence” map indicates the average prominence of the peaks. Regions with a clear signal, i.e. a well-defined fiber orientation, show only prominent peaks, a high average peak prominence, a small peak width, and a large peak distance. At the same time, the parameter maps can also be used to determine regions with out-of-plane fibers (regions with one prominent peak, large peak width, and lower peak prominence), as described in more detail in the arXiv paper.

Walking the user through the process from the raw data to the output is a good idea. We will add a more detailed description to the “Example” and “Resulting parameter maps” sections in the README, describing all parameter maps that can be generated with SLIX. We can include a Wiki and/or Jupyter notebook tutorial if you like?

The parameter “--with_mask” (and “--mask_threshold”) can be used to set all image pixels with low signals to zero, i.e. they are considered as background and not further evaluated. The parameter “--with_smoothing” can be used when the measurement has been performed with small steps of illumination angles (< 5°) to smoothen the resulting SLI signals and reduce the impact of irrelevant details in the fiber structure (cf. orange vs. black curve in Figure 1a in the JOSS paper). We will add more detailed descriptions to the “Optional parameters” section of the README.

[alexrockhill]

Thanks for your thoughtful response.

That makes sense about referencing the paper for the details of the 8% and other parameters but for just high-level user functionality, I would imagine that a user might at some point have an artifactually bright pixel that may throw off the stability of these metrics and they may need to change that value.

I think references related to when a user would actually use the data and what their data would look like when they should do so would be very helpful (i.e. the figure 1a reference).

[Thyre]

I agree that some users may want to change these high values if a pixel is artificially bright or even out of curiosity. Currently, users would only be able to change this value by modifying the Python file itself, which is especially impractical when SLIX is installed as a Python package. I will add parameters to change these values at startup from the command line. This should be done by tomorrow.

I also agree that some examples of the parameters and when they are used could be added to our README file. We will add further explanations.

[Thyre]

I‘ve added the parameter „—prominence_threshold“ which allows the user to change the prominence used for the peak detection (see 6-method-explanations). The update to the README.md is still in progress (see update-readme) but will include a more detailed explanation about the parameters and their function.

[miriammenzel]

The updated README.md now includes a more precise description of the arguments --with_mask and --with_smoothing (with reference to figure 1a). The Introduction has been completely revised, containing now details and explanations about the SLI profiles and the relevant parameter choices (such as the 8% peak prominence or the 6% peak tip height). I also added those details in the paper. As mentioned by @Thyre, the 8% prominence value can now be changed by the user (just as the 6% peak tip value). In addition, I've added a thorough explanation of all generated parameter maps (also below the "Example" section) and inserted figures for illustration purposes. @alexrockhill: Please let us know if there is anything missing.

[miriammenzel]

In addition to what I already mentioned, we included the option --with_mask in the tutorial to demonstrate the user how to use it and what the resulting parameter maps look like.

@alexrockhill: Please let us know if this meets your requirements and if we can close this issue.

[alexrockhill]

Sorry to take a while to get back, this looks great, thank you for incorporating my feedback