Generation
SLIXParameterGenerator allows the generation of different parameter maps from an SLI image stack.
SLIXParameterGenerator -i [INPUT-STACK] -o [OUTPUT-FOLDER] [[parameters]]
| Argument | Function |
|---|---|
-i, --input |
Input file: SLI image stack (as .tif(f) or .nii). |
-o, --output |
Output folder where resulting parameter maps (.tiff) will be stored. Will be created if not existing. |
| Argument | Function |
|---|---|
-r, --roisize |
Average every NxN pixels in the SLI image stack and run the evaluation on the resulting (downsampled) images. Later on, the images will be upscaled to match the input file dimensions. (Default: N=1, i.e.-r 1) |
--with_mask |
Consider all image pixels with low scattering as background: Pixels for which the maximum intensity value of the SLI profile is below a defined threshold (--mask_threshold) are set to zero and will not be further evaluated. |
--mask_threshold |
Set the threshold for the background mask (can only be used together with --with_mask). Higher values might remove the background better but will also include more regions with gray matter. (Default = 10) |
--num_procs |
Run the program with the selected number of processes. (Default = either 16 threads or the maximum number of threads available.) |
--with_smoothing |
Apply smoothing to the SLI profiles for each image pixel before evaluation. The smoothing is performed using a Savitzky-Golay filter with 45 sampling points and a second order polynomial. (Designed for measurements with |
--prominence_threshold |
Change the threshold for prominent peaks. Peaks with lower prominences will not be used for further evaluation. (Default: 8% of total signal amplitude.) Only recommended for experienced users! |
The arguments listed below determine which parameter maps will be generated from the SLI image stack. If any such argument (except –-optional) is used, no parameter map besides the ones specified will be generated. If none of these arguments is used, all parameter maps except the optional ones will be generated: peakprominence, number of (prominent) peaks, peakwidth, peakdistance, direction angles in crossing regions.
| Argument | Function |
|---|---|
--peakprominence |
Generate a parameter map (_peakprominence.tiff) containing the average prominence (scipy.signal.peak_prominence) of an SLI profile (image pixel), normalized by the average of the SLI profile. |
--peaks |
Generate two parameter maps (_low_prominence_peaks.tiff and _high_prominence_peaks.tiff) containing the number of peaks in an SLI profile (image pixel) with a prominence below and above the defined prominence_threshold (Default: 8% of the total signal amplitude). |
--peakwidth |
Generate a parameter map (_peakwidth.tiff) containing the average peak width (in degrees) of all prominent peaks in an SLI profile. |
--peakdistance |
Generate a parameter map (_peakdistance.tiff) containing the distance between two prominent peaks (in degrees) in an SLI profile. Pixels for which the SLI profile shows more/less than two prominent peaks are set to -1. |
--direction |
Generate three parameter maps (_dir_1.tiff, _dir_2.tiff, _dir_3.tiff) indicating up to three in-plane direction angles of (crossing) fibers (in degrees). If any or all direction angles cannot be determined for an image pixel, this pixel is set to -1 in the respective map. |
--optional |
Generate four additional parameter maps: average value of each SLI profile (_avg.tiff), maximum value of each SLI profile (_max.tiff), minimum value of each SLI profile (_min.tiff), and in-plane direction angles (in degrees) in regions without crossings (_dir.tiff). Image pixels for which the SLI profile shows more than two prominent peaks are set to -1 in the direction map. |
The following example demonstrates the generation of the parameter maps, for two artificially crossing sections of human optic tracts (left) and the upper left corner of a coronal vervet brain section (right):
Command line:
wget https://object.cscs.ch/v1/AUTH_227176556f3c4bb38df9feea4b91200c/hbp-d000048_ScatteredLightImaging_pub/Human_Brain/optic_tracts_crossing_sections/SLI-human-Sub-01_2xOpticTracts_s0037_30um_SLI_105_Stack_3days_registered.nii
wget https://object.cscs.ch/v1/AUTH_227176556f3c4bb38df9feea4b91200c/hbp-d000048_ScatteredLightImaging_pub/Vervet_Brain/coronal_sections/Vervet1818_s0512_60um_SLI_090_Stack_1day.nii
Links:
SLI-human-Sub-01_2xOpticTracts_s0037_30um_SLI_105_Stack_3days_registered.nii
Vervet1818_s0512_60um_SLI_090_Stack_1day.nii
SLIXParameterGenerator -i ./SLI-human-Sub-01_2xOpticTracts_s0037_30um_SLI_105_Stack_3days_registered.nii -o . --num_procs 4 --roisize 5
SLIXParameterGenerator -i ./Vervet1818_s0512_60um_SLI_090_Stack_1day.nii -o . --roisize 10 --direction
The execution of both commands should take around one minute max. The resulting parameter maps will be downsampled. To obtain full resolution parameter maps, do not use the roisize option. In this case, the computing time will be higher (around 25 times higher for the first example and 100 times higher for the second example).
To display the resulting parameter maps, you can use e.g. ImageJ or Fiji. More examples (SLI image stacks and resulting parameter maps) can be found on the EBRAINS data repository.
All 12 parameter maps that can be generated with SLIX are shown below, exemplary for the coronal vervet brain section used in the above demo (available here). In contrast to the above demo, the parameter maps were generated with full resolution. For testing purposes, we suggest to run the evaluation on downsampled images, e.g. with --roisize 10, which greatly speeds up the generation of the parameter maps.
SLIXParameterGenerator -i ./Vervet1818_s0512_60um_SLI_090_Stack_1day.nii -o .
_average.tiff shows the average intensity for each SLI profile (image pixel). Regions with high scattering show higher values.
_low_prominence_peaks.tiff shows the number of non-prominent peaks for each image pixel, i.e. peaks that have a prominence below 8% of the total signal amplitude (max-min) of the SLI profile and are not used for further evaluation. For a reliable reconstruction of the direction angles, this number should be small, ideally zero.
_high_prominence_peaks.tiff shows the number of prominent peaks for each image pixel, i.e. peaks with a prominence above 8% of the total signal amplitude (max-min) of the SLI profile. The position of these peaks is used to compute the fiber direction angles.
_peakprominence.tiff shows the average prominence of the peaks for each image pixel, normalized by the average of each profile. The higher the value, the clearer the signal.
_peakwidth.tiff shows the average width of all prominent peaks for each image pixel. A small peak width implies that the fiber directions can be precisely determined. Larger peak widths occur for out-of-plane fibers and/or fibers with small crossing angles.
_peakdistance.tiff shows the distance between two prominent peaks for each image pixel. If an SLI profile contains only one peak, the distance is zero. In regions with crossing nerve fibers, the distance is not defined and the image pixels are set to -1. The peak distance is a measure for the out-of-plane angle of the fibers: A peak distance of about 180° implies that the region contains in-plane fibers; the more the fibers point out of the section plane, the smaller the peak distance becomes. For fibers with an inclination angle of about 70° and above, a single broad peak is expected.
The in-plane direction angles are only computed if the SLI profile has one, two, four, or six prominent peaks with a pair-wise distance of (180 +/- 35)°. Otherwise, the image pixel is set to -1. The direction angle is computed from the mid position of one peak pair, or (in case of only one peak) from the position of the peak itself. All direction angles are in degrees (with 0° being along the positive x axis, and 90° along the positive y-axis).
_dir_1.tiff shows the first detected fiber direction angle.
_dir_2.tiff shows the second detected fiber direction angle (only defined in regions with two or three crossing fibers).
_dir_3.tiff shows the third detected fiber direction angle (only defined in regions with three crossing fibers).
_dir.tiff shows the fiber direction angle only in regions with one or two prominent peaks, i.e. excluding regions with crossing fibers.
_max.tiff shows the maximum of the SLI profile for each image pixel.
_min.tiff shows the minimum of the SLI profile for each image pixel.
To obtain a measure for the signal-to-noise, the difference between maximum and minimum can be divided by the average.