Skip to content

Commit

Permalink
Merge branch 'master' of github.com:3d-pli/SLIX
Browse files Browse the repository at this point in the history 
Signed-off-by: Jan André Reuter <[email protected]>
  • Loading branch information
@Thyre
Thyre committed Mar 30, 2022
2 parents ffe6286 + 57cba85 commit aa00e79
Show file tree
Hide file tree
Showing 7 changed files with 106 additions and 74 deletions.
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,15 @@

## v2.4.1
### Added
- Added inclination sign map in SLIXParameterGenerator
- Added `SLIX.parameters` which contains all the parameters for the operations of the toolbox.
- Added `SLIX._logging` to replace the print statements in SLIX. This is a private variable and should not be used.
- Added `SLIX._decorators` for additional checks of the toolbox. This should ensure that the toolbox is not used in a wrong way.

### Changed
- Added check for write operations before actually trying to generate any content reducing the computing time if the program would fail anyways.
- Changed the memory management between CPU and GPU in SLIXParameterGenerator which might reduce computing time.

- Changed print statements in SLIX to logging statements where possible. The tqdm progress bar is still used.
- `SLIX.GPU` now uses more than 1 thread for the GPU. The current value is 16x16 threads per block.
- Replaced `uint8` with `int8` in `_centroid_correction_bases`. This shouldn't affect the toolbox itself but ensures that the correct data type is used.
Expand All @@ -17,6 +21,8 @@
- Fixed out-of-bounds issues in `SLIX.GPU` when using more than 1x1 threads per block.
- Fixed issue in centroid calculation on the GPU where the normalized image wasn't stored in the GPU memory resulting in additional transfers through the CPU and GPU.
- Fixed an issue with `SLIX.attributemanager` where the method `set_reference_modality_to` was not working because it got overwritten.
- Fixed an issue where you could use any amount of arguments after the `--smoothing` flag in SLIXParameterGenerator resulting in weird behaviour for the users.
- Fixed an issue where the GPU would still be used to calculate the centroids even though the GPU execution was disabled.

## v2.4.0
### Added
Expand Down
57 changes: 26 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,43 +85,37 @@ With [`SLIXLineplotParameterGenerator`](#evaluation-of-sli-profiles), it is poss

## Installation of SLIX

##### How to clone SLIX (for further work)
```bash
git clone [email protected]: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 SLIX via PyPI
Installing the currently available version of SLIX through PyPI is the recommended way. Use the following command to install SLIX into your Python enviroment.
```bash
# Install via PyPi
pip install SLIX
```

# Install after cloning locally
##### How to install SLIX as Python package from source
If you want to use the latest available version from the GitHub repository, you can use the following commands.
Please note that features available here in comparison to the PyPI release might still be in development.
```bash
git clone [email protected]:3d-pli/SLIX.git
cd SLIX
pip install .
```

##### Run SLIX locally

##### How to clone SLIX (for further work)
If you want to contribute to SLIX, clone the repository and install the requirements in a virtual environment like seen below.
```bash
git clone [email protected]: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]
# A virtual environment is recommended:
python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt
```



## 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)](https://arxiv.org/abs/2008.01037), Appx. B).
Expand Down Expand Up @@ -224,15 +218,16 @@ SLIXParameterGenerator -i [INPUT-STACK] -o [OUTPUT-FOLDER] [[parameters]]

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](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.peak_prominences.html#scipy.signal.peak_prominences)) 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. |
| `--unit_vectors` | Generate unit vectors maps (`.nii`) from direction images. |
| `--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. |
| Argument | Function |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--peakprominence` | Generate a parameter map (`_peakprominence.tiff`) containing the average prominence ([scipy.signal.peak_prominence](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.peak_prominences.html#scipy.signal.peak_prominences)) 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. |
| `--unit_vectors` | Generate unit vectors maps (`.nii`) from direction images. |
| `--inclination_sign` | Generate a direction map not corrected by the 270° and without the restriction to the area of [0°;180°] which allows to search the inclination direction. |
| `--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):
Expand Down
2 changes: 1 addition & 1 deletion SLIX/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
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
"""
__version__ = '2.4.0'
__version__ = '2.4.1'
__all__ = ['toolbox', 'io', 'visualization', 'preparation',
'attributemanager', 'classification']

Expand Down
16 changes: 9 additions & 7 deletions SLIX/_cmd/LineplotParameterGenerator.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,11 +151,12 @@ def create_plot(profile, filtered_profile, significant_peaks, centroids):
filtered_profile = filtered_profile.flatten()

profile = (profile - profile.min()) / (profile.max() - profile.min())
plt.plot(profile)
filtered_profile = (filtered_profile - filtered_profile.min()) / \
(filtered_profile.max() - filtered_profile.min())

if not numpy.all(profile == filtered_profile):
filtered_profile = filtered_profile / filtered_profile.max()
plt.plot(filtered_profile)
plt.plot(filtered_profile, label='filtered profile')
plt.plot(profile, label='profile')

significant_peaks = numpy.argwhere(significant_peaks.flatten()) \
.flatten()
Expand Down Expand Up @@ -220,9 +221,10 @@ def subprocess(input_file, detailed, low_prominence, with_angle,
# Parameters than can change their output depending on the detailed parameters
output_parameters['peaks'] = generate_all_peaks(output_parameters['filtered'],
detailed)
output_parameters['significant peaks'] = generate_significant_peaks(output_parameters['filtered'],
low_prominence,
detailed)
significant_peaks = generate_significant_peaks(output_parameters['filtered'],
low_prominence,
True)
output_parameters['significant peaks'] = numpy.sum(significant_peaks) if not detailed else significant_peaks
output_parameters['prominence'] = generate_prominence(output_parameters['filtered'],
sig_peaks,
detailed)
Expand All @@ -238,7 +240,7 @@ def subprocess(input_file, detailed, low_prominence, with_angle,

write_parameter_file(output_parameters, output_file)
create_plot(output_parameters['profile'], output_parameters['filtered'],
output_parameters['significant peaks'],
significant_peaks,
output_parameters['centroids'])
plt.savefig(output_file + ".png", dpi=300)
plt.clf()
Expand Down
Loading

0 comments on commit aa00e79

Please sign in to comment.