{
"info": {
"author": "Eric Czech",
"author_email": "eric@hammerlab.org",
"bugtrack_url": null,
"classifiers": [
"Environment :: Console",
"Intended Audience :: Science/Research",
"License :: OSI Approved :: Apache Software License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3.6",
"Topic :: Scientific/Engineering :: Bio-Informatics"
],
"description": "[](https://travis-ci.org/hammerlab/flowdec)\n\n# Flowdec\n\n**Flowdec** is a library containing [TensorFlow](https://github.com/tensorflow/tensorflow) (TF) implementations of image and signal deconvolution algorithms. Currently, only [Richardson-Lucy Deconvolution](https://en.wikipedia.org/wiki/Richardson%E2%80%93Lucy_deconvolution) has been implemented but others may come in the future.\n\nFlowdec is designed to construct and execute TF graphs in python as well as use frozen, exported graphs from other languages (e.g. Java).\n\nHere are a few other features, advantages, and disadvantages of the project currently:\n\n*Highlights*\n\n- **Support for Windows, Mac, and Linux** - Because TensorFlow can run on these platforms, so can Flowdec.\n- **Client Support for Java, Go, C++, and Python** - Using Flowdec graphs from Python and Java has been tested, but theoretically they could also be used by any [TensorFlow API Client Libraries](https://www.tensorflow.org/api_docs/).\n- **Point Spread Functions** - PSFs can be defined as json configuration files to be generated dynamically during the deconvolution process using a [Fast Gibson-Lanni Approximation Model](http://www.ee.cuhk.edu.hk/~jzli/MicroscPSF/) (which can also create Born & Wolf kernels as a degenerate case).\n- **GPU Accleration** - Executing [TensorFlow graphs on GPUs](https://www.tensorflow.org/programmers_guide/using_gpu) is trivial and will happen by default w/ Flowdec if you meet all of the TensorFlow requirements for this (i.e. CUDA Toolkit installed, Nvidia drivers, etc.).\n- **Performance** - There are other open source and commercial deconvolution libraries that run with *partial* GPU acceleration, which generally means that only FFT and iFFT operations run on GPUs while all other operations run on the CPU. For example, on a roughly 1000x1000x11 3D volume with a PSF of the same dimensions this means that execution times look like:\n - CPU-only solutions: **10 minutes**\n - Other solutions with FFT/iFFT GPU acceleration: **~40 seconds**\n - Flowdec/TensorFlow with full GPU acceleration: **~1 second**\n- **Signal Dimensions** - Flowdec can support 1, 2, or 3 dimensional images/signals.\n- **Multi-GPU Usage** - This has yet to be tested, but theoretically this is possible since TF can do it (and this [Multi-GPU Example](java/flowdec/src/main/java/org/hammerlab/flowdec/examples/MultiGPUExample.java) is a start).\n- **Image Preprocessing** - A trickier part of deconvolution implementations is dealing with image padding and cropping necessary to use faster FFT implementations -- in Flowdec, image padding using the reflection of the image along each axis can be specified manually or by letting it automatically round up and pad to the nearest power of 2 (which will enable use of faster Cooley-Tukey algorithm instead of the Bluestein algorithm provided by Nvidia cuFFT used by TF).\n- **Visualizing Iterations** - Another difficulty with iterative deconvolution algorithms is in determining when they should stop. With Richardson Lucy, this is usually done somewhat subjectively based on visualizing results for different iteration counts and Flowdec at least helps with this by letting ```observer``` functions be given that take intermediate results of the deconvolution process to be written out to image sequences or stacks for manual inspection. Future work may include using [Tensorboard](https://www.tensorflow.org/programmers_guide/summaries_and_tensorboard) to do this instead but for now, it has been difficult to get image summaries working within TF \"while\" loops.\n\n*Disadvantages*\n\n- **No GUIs** - Flowdec is intended for use by those familiar with programming but some future work might include an ImageJ plugin (if there's interest in that). For those looking for something more interactive, [imagej-ops](https://github.com/imagej/imagej-ops) is likely your best bet which currently supports the same PSF generation model used in Flowdec as well as Richardson Lucy deconvolution. At the moment it doesn't include full GPU acceleration but that may be on the way as part of [imagej-ops-experiments](https://github.com/imagej/ops-experiments). See this [github issue](https://github.com/hadim/DeconvolutionLab2/issues/1) for more details.\n- **No Blind Deconvolution** - Currently, nothing in this arena has been attempted but since much recent research on this subject is centered around solutions in deep learning, TensorFlow will hopefully make for a good platform in the future.\n\n## Basic Usage\n\nHere is a basic example demonstrating how Flowdec can be used in a single 3D image deconvolution:\n\n*See full example notebook [here](python/examples/notebooks/Neuron%20-%203D%20Deconvolution.ipynb)*\n\n```python\n%matplotlib inline\nimport numpy as np\nimport matplotlib.pyplot as plt\nfrom skimage import exposure\nfrom scipy import ndimage, signal\nfrom flowdec import data as fd_data\nfrom flowdec import restoration as fd_restoration\n\n# Load \"Purkinje Neuron\" dataset downsampled from 200x1024x1024 to 50x256x256\n# See: http://www.cellimagelibrary.org/images/CCDB_2\nactual = fd_data.neuron_25pct().data\n# actual.shape = (50, 256, 256)\n\n# Create a gaussian kernel that will be used to blur the original acquisition\nkernel = np.zeros_like(actual)\nfor offset in [0, 1]:\n kernel[tuple((np.array(kernel.shape) - offset) // 2)] = 1\nkernel = ndimage.gaussian_filter(kernel, sigma=1.)\n# kernel.shape = (50, 256, 256)\n\n# Convolve the original image with our fake PSF\ndata = signal.fftconvolve(actual, kernel, mode='same')\n# data.shape = (50, 256, 256)\n\n# Run the deconvolution process and note that deconvolution initialization is best kept separate from \n# execution since the \"initialize\" operation corresponds to creating a TensorFlow graph, which is a \n# relatively expensive operation and should not be repeated across multiple executions\nalgo = fd_restoration.RichardsonLucyDeconvolver(data.ndim).initialize()\nres = algo.run(fd_data.Acquisition(data=data, kernel=kernel), niter=30).data\n\nfig, axs = plt.subplots(1, 3)\naxs = axs.ravel()\nfig.set_size_inches(18, 12)\ncenter = tuple([slice(None), slice(10, -10), slice(10, -10)])\ntitles = ['Original Image', 'Blurred Image', 'Reconstructed Image']\nfor i, d in enumerate([actual, data, res]):\n img = exposure.adjust_gamma(d[center].max(axis=0), gamma=.2)\n axs[i].imshow(img, cmap='Spectral_r')\n axs[i].set_title(titles[i])\n axs[i].axis('off')\n```\n\n![Neuron Example](docs/images/neuron.png \"Neuron Results\")\n\n\nAs a more realistic use case, here is an example showing how a point spread function configuration can be used in a headless deconvolution:\n\n*See full deconvolution script [here](python/flowdec/cmd/deconvolution.py)*\n\n```bash\n# Generate a configuration file containing PSF parameters (see flowdec.psf module for more details)\necho '{\"na\": 0.75, \"wavelength\": 0.425, \"size_z\": 32, \"size_x\": 64, \"size_y\": 64}' > /tmp/psf.json\n\n# Invoke deconvolution script with the above PSF configuration and an input dataset to deconvolve.\n# If flowdec has been installed, you may run the \u201cdeconvolution\u201d command.\npython examples/scripts/deconvolution.py \\\n--data-path=flowdec/datasets/bars-25pct/data.tif \\\n--psf-config-path=/tmp/psf.json \\\n--output-path=/tmp/result.tif \\\n--n-iter=25 --log-level=DEBUG\n> DEBUG:Loaded data with shape (32, 64, 64) and psf with shape (32, 64, 64)\n> INFO:Beginning deconvolution of data file \"flowdec/datasets/bars-25pct/data.tif\"\n> INFO:Deconvolution complete (in 7.427 seconds)\n> INFO:Result saved to \"/tmp/result.tif\"\n```\n\n## Examples\n\n### Python \n\n- [Neuron](python/examples/notebooks/Neuron%20-%203D%20Deconvolution.ipynb) - Deconvolution of a natural 3D image with synthetic point spread function\n- [C. Elegans](python/examples/notebooks/CElegans%20-%20Multiple%20Channel%20Example.ipynb) - Deconvolution of 712x672x104 acquisition for 3 separate channels\n- [Astronaut](python/examples/notebooks/Astronaut%20-%20Ringing%20Artifacts.ipynb) - Dealing with artifacts in deconvolved images\n- [Monitoring Iterations](python/examples/notebooks/Monitoring%20Iterations.ipynb) - Tracking deconvolution progress by visualizing results at each iteration\n- [Hollow Bars](python/examples/notebooks/Hollow%20Bars%20-%20Synthetic%20Deconvolution.ipynb) - Deconvolution of downsampled 64x64x32 synthetic volume (as a CPU-friendly example)\n- [Hollow Bars GPU Benchmarking](python/examples/notebooks/Hollow%20Bars%20-%20Benchmarking.ipynb) - Testing running times on full 256x256x128 volume with GPU-enabled system\n- [DeconvolutionLab2 Comparison](python/examples/notebooks/DeconvolutionLab2%20-%20Benchmarking.ipynb) - Comparing execution times between [DeconvolutionLab2](http://bigwww.epfl.ch/deconvolution/deconvolutionlab2/) and Flowdec\n- [Graph Export](python/examples/notebooks/Algorithm%20Graph%20Export.ipynb) - Defining and exporting TensorFlow graphs\n- [Command Line Interface](python/flowdec/cmd/deconvolution.py) - CLI for executing single deconvolutions with either a pre-defined or dynamically generated point spread function\n\n### Java\n\n- [Multi-GPU Example](java/flowdec/src/main/java/org/hammerlab/flowdec/examples/MultiGPUExample.java) - Prototype example for how to be able to execute deconvolution against multiple GPUs in parallel (not tested yet -- waiting for the use case to come up though it is very likely possible to do)\n\n## Installation\n\nThe project can be installed, ideally in a python 3.6 environment (though it should work in 3.5 too), by running:\n\n```bash\npip install flowdec[tf_gpu]\n```\n\nThe previous command will install `flowdec`, but also ensure that `tensorflow`\nis installed with GPU support. For test purposes, you may have the non-GPU\nenabled version of `tensorflow` installed by running:\n\n```bash\npip install flowdec[tf]\n```\n\nIf neither `[tf]` or `[tf_gpu]` are specified, tensorflow installation is left\nas an externally managed prerequisite.\n\nAlternatively, the project could be installed from source by doing the following:\n\n```bash\ngit clone https://github.com/hammerlab/flowdec.git\ncd flowdec/python\npip install -e .\n``` \n\n### Docker Instructions\n\nA local docker image can be built by running:\n\n```bash\ncd flowdec # Note: not flowdec/docker, just cd flowdec\n\ndocker build --no-cache -t flowdec -f docker/Dockerfile .\n\n# If on a system that supports nvidia-docker, the GPU-enabled version can be built instead via:\n# nvidia-docker build --no-cache -t flowdec -f docker/Dockerfile.gpu .\n```\n\nThe image can then be run using:\n\n```bash\n# Run in foreground (port mapping is host:container if 8888 is already taken)\ndocker run -ti -p 8888:8888 flowdec\n\n# Run in background\ndocker run -td -p 8888:8888 --name flowdec flowdec\ndocker exec -it flowdec /bin/bash # Connect \n```\n\nThe Flowdec dockerfile extends the [TensorFlow DockerHub Images](https://hub.docker.com/r/tensorflow/tensorflow/) so its usage is similar where running it in the foreground automatically starts jupyter notebook and prints a link to connect to it via a browser on the host system.\n\nThe previous image is built from the current master branch\nof github.com/hammerlab/flowdec.git. To build an image using\nyour local copy of the source instead, you can use this command:\n\n```bash\ndocker build --no-cache -t flowdec -f docker/Dockerfile.devel .\n```\n\nYou may want to combine this with a bind mount of your local source tree into\nthe running container. This setup will let you make edits to the source and\nhave them immediately take effect in the running container.\n\n```bash\nLOCAL_SRC=$(pwd)\nDEST_SRC=/repos/flowdec\n\ndocker run -ti -p 8888:8888 -v ${LOCAL_SRC}:${DEST_SRC} flowdec\n```\n\n## Validation\n\nBy in large, the purpose of this project is to attain near equivalence with a subset of the functionality provided by both [DeconvolutionLab2](http://bigwww.epfl.ch/deconvolution/deconvolutionlab2/) and [PSFGenerator](http://bigwww.epfl.ch/algorithms/psfgenerator/) via much faster implementations.\n\nTo validate this much has been accomplished, there are two notebooks in the [python/validation](python/validation) folder demonstrating the following:\n\n- [Deconvolution Validation](python/validation/deconvolution/validation.ipynb) - This notebook aggregates results from Flowdec and DeconvolutionLab2 applied to several reference datasets and verifies that deconvolved volumes are very nearly identical\n- [PSF Generation Validation](python/validation/psfgeneration/validation.ipynb) - This notebook aggregates results from Flowdec and PSFGenerator used to generate PSFs from a variety of different configurations and evaluates their similarity (which is also very high)\n\n## Acknowledgements\n\nThanks to Kyle Douglass for explaining some of the finer aspects of this Python [Gibson-Lanni PSF generator](http://kmdouglass.github.io/posts/implementing-a-fast-gibson-lanni-psf-solver-in-python.html), Jizhou Li for helping to better understand that diffraction model, Hadrien Mary for giving great context on the state of open-source deconvolution libraries, and Brian Northan for lending great advice/context on library performance, blind deconvolution and how point spread functions work in general.\n\n## References\n\n- [1] D. Sage, L. Donati, F. Soulez, D. Fortun, G. Schmit, A. Seitz, R. Guiet, C. Vonesch, M. Unser
\n DeconvolutionLab2: An Open-Source Software for Deconvolution Microscopy
\n Methods - Image Processing for Biologists, 115, 2017.
\n- [2] J. Li, F. Xue and T. Blu
\n Fast and accurate three-dimensional point spread function computation for fluorescence microscopy
\n J. Opt. Soc. Am. A, vol. 34, no. 6, pp. 1029-1034, 2017.
\n- [3] Brandner, D. and Withers, G.
\n The Cell Image Library, CIL: 10106, 10107, and 10108.
\n Available at http://www.cellimagelibrary.org. Accessed December 08, 2010.
\n\n",
"description_content_type": "",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/hammerlab/flowdec",
"keywords": "",
"license": "http://www.apache.org/licenses/LICENSE-2.0.html",
"maintainer": "",
"maintainer_email": "",
"name": "flowdec",
"package_url": "https://pypi.org/project/flowdec/",
"platform": "",
"project_url": "https://pypi.org/project/flowdec/",
"project_urls": {
"Homepage": "https://github.com/hammerlab/flowdec"
},
"release_url": "https://pypi.org/project/flowdec/1.0.7/",
"requires_dist": null,
"requires_python": "",
"summary": "TensorFlow Implementations of Signal Deconvolution Algorithms",
"version": "1.0.7"
},
"last_serial": 4805913,
"releases": {
"0.0.1": [
{
"comment_text": "",
"digests": {
"md5": "6ad983a0e244733ace9d72bb7308e03d",
"sha256": "e54d2cebdb8f72e759c045d394c097173d25bcdef8c33fcd32f8f46417ff7ae3"
},
"downloads": -1,
"filename": "flowdec-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6ad983a0e244733ace9d72bb7308e03d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4232632,
"upload_time": "2019-01-06T12:35:48",
"url": "https://files.pythonhosted.org/packages/e2/c1/c29ac7d1edcf72ef1cf09a8d6f7533ff058c87274683ca4245d29800ca51/flowdec-0.0.1.tar.gz"
}
],
"1.0.7": [
{
"comment_text": "",
"digests": {
"md5": "e327a3647b31067cce33fc14d4f89ab4",
"sha256": "c2fdde71d621fdf03df17bef905f9cee12bcc511415e911c5df8ab2bbd47f9e5"
},
"downloads": -1,
"filename": "flowdec-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "e327a3647b31067cce33fc14d4f89ab4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4238276,
"upload_time": "2019-02-11T13:06:54",
"url": "https://files.pythonhosted.org/packages/8d/e2/e1b5c50f210ef7a59248b8836ab0be3ce8b2a3f9c9b6c8108a041e7f8923/flowdec-1.0.7.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "e327a3647b31067cce33fc14d4f89ab4",
"sha256": "c2fdde71d621fdf03df17bef905f9cee12bcc511415e911c5df8ab2bbd47f9e5"
},
"downloads": -1,
"filename": "flowdec-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "e327a3647b31067cce33fc14d4f89ab4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4238276,
"upload_time": "2019-02-11T13:06:54",
"url": "https://files.pythonhosted.org/packages/8d/e2/e1b5c50f210ef7a59248b8836ab0be3ce8b2a3f9c9b6c8108a041e7f8923/flowdec-1.0.7.tar.gz"
}
]
}