# Red lionfish (RL) deconvolution
*Richardson-Lucy deconvolution for fishes, scientists and engineers.*
This software is for filtering 3D data using the Richardson-Lucy deconvolution algorithm.
Richardson-Lucy is an iterative deconvolution algorithm that is used to remove
point spread function (PSF) or optical transfer function (OTF) artifacts from experimental images.
The method was originally developed for astronomy to remove optical effects and simultaneously reduce poisson noise in 2D images.
[Lucy, L. B. An iterative technique for the rectification of observed distributions. The Astronomical Journal 79, 745 (1974). DOI: 10.1086/111605](https://ui.adsabs.harvard.edu/abs/1974AJ.....79..745L/abstract)
The method can also be applied to 3D data. Nowadays this filtering technique is also widely used by microscopists.
The Richardson-Lucy deconvolution algorigthm is iterative. Each iteration involves the calculation of 2 convolutions, one element-wise multiplication and one element-wise division.
When dealing with 3D data, the Richardson-Lucy algorithm is quite computional intensive primarly due to the calculation of the convolution, and can take a while to complete depending on the resources available. Convolution is significantly sped up using FFT compared to raw convolution.
This software was developed with the aim to make the R-L computation faster by exploiting GPU resources, and with the use of FFT convolution.
To make RedLionfish easily accessible, it is available through PyPi and anaconda (conda-forge channel). A useful plugin for Napari is also available.
Please note that this software only works with 3D data. For 2D data there are many alternatives such as the DeconvolutionLab2 in Fiji (ImageJ) and sckikit-image.
## Napari plugin
You can now use the Napari's plugin installation in *Menu -> Plugins -> Install/Uninstall Plugins...*.
However, if you chose to use this method, GPU acceleration may not be available and it will use the CPU backend. Better check.
Alternatively, if you follow the installation instructions below, and install the napari in the same python environment
then the plugin should be immediately available in the *Menu -> Plugins -> RedLionfish*.
## Installation
Previously there was a problem in installing using `pip`, because no PyOpenCL wheels for windows were avaiable. It is now avaialble. This package can be installed using pip or conda.
### Conda install
This package is available in conda-forge channel.
It contains the precompiled libraries and it will install all the requirments for GPU-accelerated RL calculations.
`conda install redlionfish -c conda-forge`
### Install from PyPi
```
pip install redlionfish
```
In Linux , the package `ocl-icd-system` may also be useful.
```
conda install reikna pyopencl ocl-icd-system -c conda-forge
```
#### Manual installation using the conda package file.
Download the appropriate conda package .bz2 at [https://github.com/rosalindfranklininstitute/RedLionfish/releases](https://github.com/rosalindfranklininstitute/RedLionfish/releases)
In the command line, successively run:
```
conda install <filename.bz2>
conda update --all -c conda-forge
```
The second line is needed because you are installing from a local file, conda installer will not install dependencies. Right after this you should run the update command given.
### Manual installation (advanced and for developers)
Please note that in order to use OpenCL GPU accelerations, PyOpenCL must be installed.
The best way to get it working is to install it under a conda environment.
The installation is similar to the previously described for PyPi.
`conda install reikna pyopencl`
or
`conda install reikna pyopencl ocl-icd-system -c conda-forge` (Linux)
Clone/download from source [https://github.com/rosalindfranklininstitute/RedLionfish/](https://github.com/rosalindfranklininstitute/RedLionfish/)
and run
`python setup.py install`
### Debug installation
If you want to test and modify the code then you should probably install in debug mode using:
`python setup.py develop`
or
`pip install -e .`
## More information
The software has algorithms for Richardson-Lucy deconvolution that use either CPU and GPU.
The CPU version is very similar to the [skimage.restoration.richardson_lucy](https://scikit-image.org/docs/dev/api/skimage.restoration.html#skimage.restoration.richardson_lucy) code, with improvments in speed.
major differences are:
- the convolution steps use FFT only.
- PSF and PSF-flipped FFTs are precalculated before starting iterations.
The GPU version, was written in to use Reikna package, which does FFT using OpenCL, via PyOpenCL.
Unfortunately, a major limitation in RAM usage exists with PyOpenCL.
Large 3D data volumes with cause out-of-memory error when trying to upload data to the GPU for FFT calculations.
As such, to overcome this problem, a block algorithm is used, which splits data into blocks with padded data.
The results are then combined together to give the final result.
This affects the perfomance of the calculation rather significantly, but with the advantage of being possible to handle large data volumes.
If Richardson-Lucy deconvolution using the GPU method fails, RedLionfish will falls back to CPU calculation. Check console output for messages.
If you are using the RedLionfish in your code, note that, by default, `def doRLDeconvolutionFromNpArrays()` method it uses the GPU OpenCL version.
## Testing
Many examples can be found in `/test' folder.
A quick and benchmarking installation can be run from the proect root using the command:
'python test\test_and_benchm.py'
or (*nix)
'python test/test_and_benchm.py'
This will print out information about your GPU device (if available) and run some deconvolutions.
It initially creates some data programatically, convolutes with a gaussian PSF, and add Poisson noise.
Then it executes executes the
Richardson-Lucy deconvolution calculation using CPU and GPU methods, for 10 iterations.
During the calculation it will print some information to the console/terminal, including the time it takes to run the calculation.
Computer generated data and an experimental PSF can be found in `test\testdata`
### Testing Redlionfish in napari
Here is an example testing the Redlionfish plugin in napari:
1. load data `test\testdata\gendata_psfconv_poiss_large.tif` (can use draga and drop)
2. load psf data `test\testdata\PSF_RFI_8bit.tif`
3. In the RedLionfish side window ensure that 'gendata_psfconv_poiss_large' is selected in data dropdown widget, and `PSF_RFI_8bit` is selected in psfdata widget.
4. Choose number of iterations (default=10)
5. Click 'Go' button and wait until result shows as a new data layer.
6. Use controls of the left panel to compare before and after RL deconvolution: select 'RL-deconvolution' layer and set colormap to red. Hide PSF_RFI_8bit. Make sure that both 'RL-deconvolution' and 'gendata-psfconv' are visible. Now, hide/unhide RL-deconvolution layer to see before and after deconvolution. Adjust contrast limits of each layer as desired.
## GPU vs CPU
You may notice that choosing GPU does not make RL-calculation much faster compared with CPU, and sometimes is slower.
Which method runs the R-L deconvolution faster. That depends on the computer configuration/architecture.
GPU calculations will be generally faster than CPU with bigger data volumes.
GPU calculation will be significantly faster if using a dedicated GPU card.
Please see benchmark values that highlights significant variability in calculation speeds.
## Coding
Please feel free to browse /test folder for examples.
In your code, add the import.
`import RedLionfishDeconv`
in order to use the functions.
The most useful function is perhaps the following.
`def doRLDeconvolutionFromNpArrays(data_np , psf_np ,*, niter=10, method='gpu', useBlockAlgorithm=False, callbkTickFunc=None, resAsUint8 = False) `
This will do the Richardson-Lucy deconvolution on the data_np (numpy, 3 dimensional data volume) using the provided PSF data volume, for 10 iterations. GPU method is generally faster but it may fail. If it does fail, the program will automatically use the CPU version that uses the scipy fft package.
## Manually building the conda package
For this installation, ensure that the conda-build package is installed
`conda install conda-build`
In windows, simply execute
`conda-create-package.bat`
Or, execute the following command-line to create the installation package.
`conda-build --output-folder ./conda-built-packages -c conda-forge conda-recipe`
and the conda package will be created in folder *conda-built-packages*.
Otherwise, navigate to `conda-recipe`, and execute on the command-line `conda build .`
It will take a while to complete.
## Contact
Report issues and questions in project's github page, please. Please don't try to send emails as they may be igored or spam-filtered.
Raw data
{
"_id": null,
"home_page": "https://github.com/rosalindfranklininstitute/RedLionfish",
"name": "RedLionfish",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Luis Perdigao",
"author_email": "luis.perdigao@rfi.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/07/10/d7ebdaa5ae1b779600b3419b666726a83ba01a2464c6562d846c77090a81/RedLionfish-0.8.tar.gz",
"platform": null,
"description": "# Red lionfish (RL) deconvolution\n\n*Richardson-Lucy deconvolution for fishes, scientists and engineers.*\n\n\nThis software is for filtering 3D data using the Richardson-Lucy deconvolution algorithm.\n\nRichardson-Lucy is an iterative deconvolution algorithm that is used to remove\npoint spread function (PSF) or optical transfer function (OTF) artifacts from experimental images.\n\nThe method was originally developed for astronomy to remove optical effects and simultaneously reduce poisson noise in 2D images.\n\n[Lucy, L. B. An iterative technique for the rectification of observed distributions. The Astronomical Journal 79, 745 (1974). DOI: 10.1086/111605](https://ui.adsabs.harvard.edu/abs/1974AJ.....79..745L/abstract)\n\nThe method can also be applied to 3D data. Nowadays this filtering technique is also widely used by microscopists.\n\nThe Richardson-Lucy deconvolution algorigthm is iterative. Each iteration involves the calculation of 2 convolutions, one element-wise multiplication and one element-wise division.\n\nWhen dealing with 3D data, the Richardson-Lucy algorithm is quite computional intensive primarly due to the calculation of the convolution, and can take a while to complete depending on the resources available. Convolution is significantly sped up using FFT compared to raw convolution.\n\nThis software was developed with the aim to make the R-L computation faster by exploiting GPU resources, and with the use of FFT convolution.\n\nTo make RedLionfish easily accessible, it is available through PyPi and anaconda (conda-forge channel). A useful plugin for Napari is also available.\n\nPlease note that this software only works with 3D data. For 2D data there are many alternatives such as the DeconvolutionLab2 in Fiji (ImageJ) and sckikit-image.\n\n## Napari plugin\n\nYou can now use the Napari's plugin installation in *Menu -> Plugins -> Install/Uninstall Plugins...*.\nHowever, if you chose to use this method, GPU acceleration may not be available and it will use the CPU backend. Better check.\n\n\n\nAlternatively, if you follow the installation instructions below, and install the napari in the same python environment\nthen the plugin should be immediately available in the *Menu -> Plugins -> RedLionfish*.\n\n\n## Installation\n\nPreviously there was a problem in installing using `pip`, because no PyOpenCL wheels for windows were avaiable. It is now avaialble. This package can be installed using pip or conda.\n\n### Conda install\n\nThis package is available in conda-forge channel.\nIt contains the precompiled libraries and it will install all the requirments for GPU-accelerated RL calculations.\n\n`conda install redlionfish -c conda-forge`\n\n### Install from PyPi\n\n```\npip install redlionfish\n```\n\nIn Linux , the package `ocl-icd-system` may also be useful.\n\n```\nconda install reikna pyopencl ocl-icd-system -c conda-forge\n```\n\n\n#### Manual installation using the conda package file.\n\nDownload the appropriate conda package .bz2 at [https://github.com/rosalindfranklininstitute/RedLionfish/releases](https://github.com/rosalindfranklininstitute/RedLionfish/releases)\n\nIn the command line, successively run:\n```\nconda install <filename.bz2>\nconda update --all -c conda-forge\n```\nThe second line is needed because you are installing from a local file, conda installer will not install dependencies. Right after this you should run the update command given.\n\n\n### Manual installation (advanced and for developers)\n\nPlease note that in order to use OpenCL GPU accelerations, PyOpenCL must be installed.\nThe best way to get it working is to install it under a conda environment.\n\nThe installation is similar to the previously described for PyPi.\n\n`conda install reikna pyopencl`\n\nor\n`conda install reikna pyopencl ocl-icd-system -c conda-forge` (Linux)\n\nClone/download from source [https://github.com/rosalindfranklininstitute/RedLionfish/](https://github.com/rosalindfranklininstitute/RedLionfish/)\n\nand run\n\n`python setup.py install`\n\n\n### Debug installation\nIf you want to test and modify the code then you should probably install in debug mode using:\n\n`python setup.py develop`\n\nor\n\n`pip install -e .`\n\n\n## More information\n\nThe software has algorithms for Richardson-Lucy deconvolution that use either CPU and GPU.\n\nThe CPU version is very similar to the [skimage.restoration.richardson_lucy](https://scikit-image.org/docs/dev/api/skimage.restoration.html#skimage.restoration.richardson_lucy) code, with improvments in speed.\nmajor differences are:\n\n- the convolution steps use FFT only.\n- PSF and PSF-flipped FFTs are precalculated before starting iterations.\n\nThe GPU version, was written in to use Reikna package, which does FFT using OpenCL, via PyOpenCL.\n\nUnfortunately, a major limitation in RAM usage exists with PyOpenCL.\nLarge 3D data volumes with cause out-of-memory error when trying to upload data to the GPU for FFT calculations.\nAs such, to overcome this problem, a block algorithm is used, which splits data into blocks with padded data.\nThe results are then combined together to give the final result.\nThis affects the perfomance of the calculation rather significantly, but with the advantage of being possible to handle large data volumes.\n\nIf Richardson-Lucy deconvolution using the GPU method fails, RedLionfish will falls back to CPU calculation. Check console output for messages.\n\nIf you are using the RedLionfish in your code, note that, by default, `def doRLDeconvolutionFromNpArrays()` method it uses the GPU OpenCL version.\n\n## Testing\n\nMany examples can be found in `/test' folder.\n\nA quick and benchmarking installation can be run from the proect root using the command:\n\n'python test\\test_and_benchm.py'\n\nor (*nix)\n\n'python test/test_and_benchm.py'\n\nThis will print out information about your GPU device (if available) and run some deconvolutions.\nIt initially creates some data programatically, convolutes with a gaussian PSF, and add Poisson noise.\nThen it executes executes the\nRichardson-Lucy deconvolution calculation using CPU and GPU methods, for 10 iterations.\nDuring the calculation it will print some information to the console/terminal, including the time it takes to run the calculation.\n\n\nComputer generated data and an experimental PSF can be found in `test\\testdata`\n\n### Testing Redlionfish in napari\n\nHere is an example testing the Redlionfish plugin in napari:\n\n1. load data `test\\testdata\\gendata_psfconv_poiss_large.tif` (can use draga and drop)\n2. load psf data `test\\testdata\\PSF_RFI_8bit.tif`\n3. In the RedLionfish side window ensure that 'gendata_psfconv_poiss_large' is selected in data dropdown widget, and `PSF_RFI_8bit` is selected in psfdata widget.\n4. Choose number of iterations (default=10)\n5. Click 'Go' button and wait until result shows as a new data layer.\n6. Use controls of the left panel to compare before and after RL deconvolution: select 'RL-deconvolution' layer and set colormap to red. Hide PSF_RFI_8bit. Make sure that both 'RL-deconvolution' and 'gendata-psfconv' are visible. Now, hide/unhide RL-deconvolution layer to see before and after deconvolution. Adjust contrast limits of each layer as desired.\n\n\n## GPU vs CPU\n\nYou may notice that choosing GPU does not make RL-calculation much faster compared with CPU, and sometimes is slower.\n\nWhich method runs the R-L deconvolution faster. That depends on the computer configuration/architecture.\n\nGPU calculations will be generally faster than CPU with bigger data volumes.\n\nGPU calculation will be significantly faster if using a dedicated GPU card.\n\nPlease see benchmark values that highlights significant variability in calculation speeds.\n\n\n## Coding\n\nPlease feel free to browse /test folder for examples.\n\nIn your code, add the import.\n\n`import RedLionfishDeconv`\n\nin order to use the functions.\n\nThe most useful function is perhaps the following.\n\n`def doRLDeconvolutionFromNpArrays(data_np , psf_np ,*, niter=10, method='gpu', useBlockAlgorithm=False, callbkTickFunc=None, resAsUint8 = False) `\n\nThis will do the Richardson-Lucy deconvolution on the data_np (numpy, 3 dimensional data volume) using the provided PSF data volume, for 10 iterations. GPU method is generally faster but it may fail. If it does fail, the program will automatically use the CPU version that uses the scipy fft package.\n\n\n\n## Manually building the conda package\n\nFor this installation, ensure that the conda-build package is installed\n\n`conda install conda-build`\n\nIn windows, simply execute\n\n`conda-create-package.bat`\n\n\nOr, execute the following command-line to create the installation package.\n\n`conda-build --output-folder ./conda-built-packages -c conda-forge conda-recipe`\n\nand the conda package will be created in folder *conda-built-packages*.\n\nOtherwise, navigate to `conda-recipe`, and execute on the command-line `conda build .`\n\nIt will take a while to complete.\n\n## Contact\n\nReport issues and questions in project's github page, please. Please don't try to send emails as they may be igored or spam-filtered.\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Fast Richardson-Lucy deconvolution of 3D volume data using GPU or CPU with napari plugin.",
"version": "0.8",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "805e586ff3e11e12b937b0c59e43cfc4",
"sha256": "d8ab2270ebdefe5e9f91c3d32459f7c61c0724f5c480c0bfab4f52d39b1a9d1e"
},
"downloads": -1,
"filename": "RedLionfish-0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "805e586ff3e11e12b937b0c59e43cfc4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25503,
"upload_time": "2022-09-30T20:40:24",
"upload_time_iso_8601": "2022-09-30T20:40:24.914946Z",
"url": "https://files.pythonhosted.org/packages/6a/ba/b5079d0c2d02b106043b1c33ace214dc748307673e829691b1e4ef2704f3/RedLionfish-0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "fb6921cd400568a61c56fee58b646e95",
"sha256": "30662cb8e6c85705decd53542b6cd6ca5624381f2ca223da161aaaef84c470b1"
},
"downloads": -1,
"filename": "RedLionfish-0.8.tar.gz",
"has_sig": false,
"md5_digest": "fb6921cd400568a61c56fee58b646e95",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22950,
"upload_time": "2022-09-30T20:40:28",
"upload_time_iso_8601": "2022-09-30T20:40:28.499450Z",
"url": "https://files.pythonhosted.org/packages/07/10/d7ebdaa5ae1b779600b3419b666726a83ba01a2464c6562d846c77090a81/RedLionfish-0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-09-30 20:40:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "rosalindfranklininstitute",
"github_project": "RedLionfish",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "redlionfish"
}
JSON
