SLIX 2.0.0

SLIX allows an automated evaluation of SLI measurements and generates different parameter maps.

SLIX – Scattered Light Imaging ToolboX

• Introduction
  • SLI Measurement
  • SLI Profiles
  • Parameter Maps
• System recommendations
• Installation of SLIX
• Evaluation of SLI Profiles
  • Required Arguments
  • Optional Arguments
  • Example
• Generation of Parameter Maps
  • Required Arguments
  • Optional Arguments
  • Example
  • Resulting Parameter Maps
• Tutorial
• Performance Metrics
• Authors
• References
• Acknowledgements
• License

Introduction

Scattered Light Imaging (SLI) is a novel neuroimaging technique that allows to explore the substructure of nerve fibers, especially in regions with crossing nerve fibers, in whole brain sections with micrometer resolution (Menzel et al. (2020)). By illuminating histological brain sections from different angles and measuring the transmitted light under normal incidence, characteristic light intensity profiles (SLI profiles) can be obtained which provide crucial information such as the directions of crossing nerve fibers in each measured image pixel.

This repository contains the 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. The purpose of SLIX is twofold: First, it allows to transform the raw data of SLI measurements (SLI image stack) to human-readable parameter maps that can be used for further analysis and interpreted by researchers. To this end, SLIX also contains functions to visualize the resulting parameter maps, e.g. as colored vector maps. Second, the results of SLIX can be processed further for use in tractography algorithms. For example, the resulting fiber direction maps can be stored as angles or as unit vectors, which can be used as input for streamline tractography algorithms (Nolden et al. (2019)).

The figure belows shows the different steps, from the SLI measurement to the generation of parameter maps:

SLI Measurement

The sample is illuminated from different angles, with constant polar angle and different equidistant azimuthal angles (starting on top and rotating clock-wise), see figure (a). A camera behind the sample records an image of the transmitted light under normal incidence for each direction of illumination, yielding a series of images (b).

The SLI image stack is used as input for SLIX (.nii or .tiff are accepted). The software assumes that the measurement has been performed with equidistant angles over a full range of 360°. The number of images defines the illumination angles (e.g. when using 24 images as input, the software assumes that the images were recorded with = 0°,15°,...,345°).

SLI Profiles

Each pixel in the SLI image stack contains a light intensity profile (SLI profile ), which is characteristic for the brain tissue structure at this point (see Menzel et al. (2020) for more details). With SLIX, it is possible to automatically extract and evaluate the SLI profiles for all image pixels.

The peak positions are computed with scipy.signal.find_peaks, taking the 360° periodicity of the signal into account. To account for inaccuracies introduced by the discretization of the SLI profile, the determined peak positions are corrected by calculating the geometric center of the peak tips with a height corresponding to 6% of the total signal amplitude. The value of 6% turned out to be the best choice to obtain reliable fiber orientations (see Menzel et al. (2020), Appx. B), but can be changed by the user. Figure (c) shows an SLI profile with 15° discretization and the corrected peak positions as vertical lines.

To avoid that peaks caused by noise or details in the fiber structure impair the computed fiber direction angles, only prominent peaks are used for further evaluation. The peak prominence (scipy.signal.peak_prominences) indicates how strongly a peak stands out from the background signal and is defined by the vertical distance between the top of the peak and the higher of the two neighboring minima (see figure (c), in red). If not defined otherwise by the user, peaks with a prominence above 8% of the total signal amplitude (max-min) are considered as prominent peaks. The value of 8% turned out to be the optimal choice for the generation of reliable fiber orientations (best compromise between correctly and wrongly detected peaks for regions with known fiber orientations, see Menzel et al. (2020), Appx. A).

The peak width (see figure (c), in dark blue) is determined as the full width of the peak at a height corresponding to the peak height minus half of the peak prominence.

The in-plane fiber direction angles are computed from the (corrected) mid positions of prominent peak pairs with a pair-wise distance of (180 +/- 35)°, see figure (c) in green/magenta. The range of possible distances has been limited to ensure that the out-of-plane angles of the nerve fibers are not too large (the direction angles of inclined crossing fibers cannot be reliably determined).

Parameter Maps

By evaluating the SLI profiles of each image pixel, SLIX generates different parameter maps, which provide various information about the investigated brain tissue:

• The average map shows the overall scattering of the tissue; maximum and minimum can be used to get an idea of the signal amplitude and the signal-to-noise ratio.
• The number of non-prominent peaks and the number of prominent peaks indicate the clarity of the signal (regions with indefinite scattering signals, such as background or regions with a small number of nerve fibers, show a higher number of non-prominent peaks); the average peak prominence indicates the reliability of the peak positions.
• The average peak width and the peak distance correlate with the out-of-plane angle of the nerve fibers (in-plane fibers show two narrow peaks with a large distance of about 180°).
• The direction maps show the in-plane direction angles of the nerve fibers for up to three different crossing fibers. The fiber directions can be represented by a colored vector map, as described in the tutorial below.

With SLIXLineplotParameterGenerator, it is possible to evaluate individual SLI profiles and compute characteristics such as the number of peaks, their positions, and in-plane fiber direction angles. For a given SLI image stack, SLIXParameterGenerator computes the desired parameter maps for all image pixels.

System recommendations

• Operating System: Windows, Linux, MacOS
• Python version: Python 3.6+
• Processor: At least four threads if executed on CPU only
• RAM: 8 GiB or more
• (optional GPU: NVIDIA GPU supported by CUDA 9.0+)

Installation of SLIX

How to clone SLIX (for further work)

git clone [e-mail]:3d-pli/SLIX.git
cd SLIX

# A virtual environment is recommended:
python3 -m venv venv
source venv/bin/activate

pip3 install -r requirements.txt

How to install SLIX as Python package

# Install via PyPi
pip install SLIX

# Install after cloning locally
git clone [e-mail]:3d-pli/SLIX.git
cd SLIX
pip install .

Run SLIX locally

git clone [e-mail]:3d-pli/SLIX.git
cd SLIX
python3 SLIXParameterGenerator.py [options]
python3 SLIXLineplotParameterGenerator.py [options]

# alternatively, after installation of SLIX
pip3 install SLIX
SLIXParameterGenerator [options]
SLIXLineplotParameterGenerator [options]

Evaluation of SLI Profiles

SLIXLineplotParameterGenerator allows the evaluation of individual SLI profiles (txt-files with a list of intensity values): For each SLI profile, the maximum, minimum, number of prominent peaks, corrected peak positions, fiber direction angles, and average peak prominence are computed and stored in a text file. The user has the option to generate a plot of the SLI profile that shows the profile together with the peak positions before/after correction. The corrected peak positions are determined by calculating the geometric center of the peak tip, improving the accuracy of the determined peak positions in discretized SLI profiles. If not defined otherwise, the peak tip height corresponds to 6% of the total signal amplitude (for derivation, see Menzel et al. (2020), Appx. B).

SLIXLineplotParameterGenerator -i [INPUT-TXT-FILES] -o [OUTPUT-FOLDER] [[parameters]]

Required Arguments

Argument	Function
-i, --input	Input text files, describing the SLI profiles (list of intensity values).
-o, --output	Output folder used to store the characteristics of the SLI profiles in a txt-file (Max, Min, Num_Peaks, Peak_Pos, Directions, Prominence). Will be created if not existing.

Optional Arguments

Argument	Function
--smoothing	Smoothing of SLI profiles before evaluation. The smoothing is performed using a Savitzky-Golay filter with 45 sampling points and a second order polynomial. (Designed for measurements with < 5° steps to reduce the impact of irrelevant details in the fiber structure, cf. orange vs. black curve in Figure 1c in the paper.)
--with_plots	Generates plots (png-files) showing the SLI profiles and the determined peak positions (orange dots: before correction; green crosses: after correction).
--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! (default: 0.08)

Example

The following example demonstrates the evaluation of two SLI profiles, which can be found in the "examples" folder of the SLIX repository:

SLIXLineplotParameterGenerator -i examples/*.txt -o output --with_plots

The resulting plot and txt-file are shown below, exemplary for one of the SLI profiles (90-Stack-1647-1234.txt):

Max: 119.0
Min: 68.0
Num_Peaks: 4
Peak_Pos: [2.5935516 7.723009 14.294096 20.10292]
Directions: [143.3426513671875 61.305511474609375 -1.0]
Prominence: 0.27323946356773376

The plot shows the SLI profile derived from a stack of 24 images. The x-axis displays the number of images, the y-axis the measured light intensity [a.u.]. To detect peaks at the outer boundaries, the profile was extended taking the 360° periodicity of the signal into account; the red line indicates the boundary. The orange dots are the original peak positions, the green crosses indicate the corrected peak positions, taking the discretization of the profile into account.

The txt-file lists the maximum and minimum intensity values in the SLI profile, the number of prominent peaks (i.e. peaks with a prominence above 8% of the total signal amplitude), the corrected peak positions (on the x-axis), the direction angles of the nerve fibers (in degrees, derived from the mid-positions between peak pairs), and the average prominence of the peaks normalized by the average of the signal.

Generation of Parameter Maps

SLIXParameterGenerator allows the generation of different parameter maps from an SLI image stack.

SLIXParameterGenerator -i [INPUT-STACK] -o [OUTPUT-FOLDER] [[parameters]]

Required Arguments

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.

Optional Arguments

Argument	Function
--thinout	Average every NxN pixels in the SLI image stack and run the evaluation on the resulting (downsampled) images. (Default: N=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)
--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 < 5° steps to reduce the impact of irrelevant details in the fiber structure, cf. orange vs. black curve in Figure 1c in the paper.)
--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!
--detailed	Save 3D images in addition to 2D mean images which include more detailed information but will need a lot more disk space.
--disable_gpu	Use the CPU in combination with Numba instead of the GPU variant. This is only recommended if your GPU is significantly slower than your CPU.
--no_centroids	Disable centroid calculation for the parameter maps. This is absolutely not recommended and will result in worse parameter maps but can lower the computing time significantly.

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.

Example

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):

  

How to run the demo yourself:

1. Download the needed files:

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

2. Run SLIX:

SLIXParameterGenerator -i ./SLI-human-Sub-01_2xOpticTracts_s0037_30um_SLI_105_Stack_3days_registered.nii -o . --thinout 5

SLIXParameterGenerator -i ./Vervet1818_s0512_60um_SLI_090_Stack_1day.nii -o . --thinout 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.

Resulting Parameter Maps

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 --thinout 3, which greatly speeds up the generation of the parameter maps.

SLIXParameterGenerator -i ./Vervet1818_s0512_60um_SLI_090_Stack_1day.nii -o .

Average

_average.tiff shows the average intensity for each SLI profile (image pixel). Regions with high scattering show higher values.

Low Prominence Peaks

_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

_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.

Average Peak Prominence

_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.

Average Peak Width

_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.

Peak Distance

_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.

Direction Angles

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).

In case of three or five prominent peaks, the peak pairs cannot be safely assigned and are therefore not evaluated. SLI profiles with three peaks could also be caused e.g. by strongly inclined crossing fibers, where a reliable determination of the in-plane fiber directions is not possible. If an SLI profile contains three prominent peaks, it might also be the case that the forth peak lies below the prominence threshold because the signal is not very clear. To account for missing peaks, the user has the possibility to decrease the prominence threshold by setting another value with --prominence_threshold. However, this should be done with caution, as this also causes non-significant peaks that are generated by noise or other artifacts to be considered for evaluation and might yield wrong fiber direction angles. Therefore, we strongly recommend to read the derivation in Menzel et al. (2020), Appx. A, before adjusting the threshold.

_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.

Maximum

_max.tiff shows the maximum of the SLI profile for each image pixel.

Minimum

_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.

Tutorial

The Jupyter notebook demonstrates how SLIX can be used to analyze SLI measurements and to visualize the results. For example, it allows to display the generated parameter maps in different colors, and to show the orientations of (crossing) nerve fibers as colored lines (vector maps) by computing unit vector maps from the direction maps. The following vector map has been generated with the function visualize_unit_vectors, using alpha = 0.8 (defining the transparency of the background image), thinout = 30 (i.e. 30 x 30 pixels were evaluated together), and background_threshold = 0.7 (i.e. if more than 70% of the evaluated pixels are -1, no vector will be computed).

Performance Metrics

The actual runtime depends on the complexity of the SLI image stack. Especially the number of images in the stack and the number of image pixels can have a big influence. To test the performance, one SLI image stack from the coronal vervet brain section (containing 24 images with 2469x3272 pixels each) was analyzed by running benchmark.py. This script will create all parameter maps (non detailed ones in addition to all detailed parameter maps) without any downsampling. All performance measurements were taken without times for reading and writing files. When utilizing the GPU and parameter maps are necessary for further operations, they are kept on the GPU to reduce processing time. The SLI measurement, high prominence peaks and centroids are therefore calculated only once each iteration and are used throughout the whole benchmark. Each benchmark used an Anaconda environment with Python 3.8.5 and all neccessary packages installed.

CPU	Operating system	With GPU	Time in seconds for this example (8.078.658 pixels)
AMD Ryzen 3700X	Manjaro (Nov 9th 2020)	Disabled	23.000 ± 1.374
AMD Ryzen 3700X	Manjaro (Nov 9th 2020)	NVIDIA GTX 1070	32.013 ± 0.371
AMD Ryzen 3700X	Manjaro (Dez 8th 2020)	NVIDIA RTX 3070	22.467 ± 0.370
Intel Core i3-2120	Ubuntu 18.04 LTS	-N/A-	86.138 ± 3.57
Intel Core i5-3470	Ubuntu 20.04 LTS	Disabled	77.768 ± 6.101
Intel Core i5-3470	Ubuntu 20.04 LTS	NVIDIA GTX 1070	34.169 ± 0.975
Intel Core i5-8350U	Ubuntu 20.10	-N/A-	58.945 ± 2.799
Intel Core i7-7820HQ	MacOS Big Sur	-N/A-	55.709 ± 3.446
2x Intel Xeon CPU E5-2690	Ubuntu 18.04 LTS	Disabled	42.363 ± 3.475
2x Intel Xeon CPU E5-2690	Ubuntu 18.04 LTS	NVIDIA GTX 1080	27.712 ± 4.052

Authors

• Jan André Reuter
• Miriam Menzel

References

	Fiber Architecture - INM1 - Forschungszentrum Jülich
	Human Brain Project

Acknowledgements

This open source software code was developed in part or in whole in the Human Brain Project, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 785907 and 945539 ("Human Brain Project" SGA2 and SGA3). The project also received funding from the Helmholtz Association port-folio theme "Supercomputing and Modeling for the Human Brain".

License

This software is released under MIT License

Copyright (c) 2020 Forschungszentrum Jülich / Jan André Reuter.
Copyright (c) 2020 Forschungszentrum Jülich / Miriam Menzel.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.python input parameters -i -o

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.