search

hammerlab / flowdec

TensorFlow Deconvolution for Microscopy Data
Apache License 2.0
90 stars 26 forks source link

readme

Build Status

Flowdec

*Note*: This library is no longer actively maintained and requires older versions of Python and TensorFlow to run. If you have point spread functions already, then cucim.skimage.restoration.richardson_lucy is another implementation worth considering. If not, then the utilities in this library for generating them may still be useful.

Flowdec is a library containing TensorFlow (TF) implementations of image and signal deconvolution algorithms. Currently, only Richardson-Lucy Deconvolution has been implemented but others may come in the future.

Flowdec is designed to construct and execute TF graphs in python as well as use frozen, exported graphs from other languages (e.g. Java).

Here are a few other features, advantages, and disadvantages of the project currently:

Highlights

Disadvantages

Basic Usage

Here is a basic example demonstrating how Flowdec can be used in a single 3D image deconvolution:

See full example notebook here

%matplotlib inline
import numpy as np
import matplotlib.pyplot as plt
from skimage import exposure
from scipy import ndimage, signal
from flowdec import data as fd_data
from flowdec import restoration as fd_restoration

# Load "Purkinje Neuron" dataset downsampled from 200x1024x1024 to 50x256x256
# See: http://www.cellimagelibrary.org/images/CCDB_2
actual = fd_data.neuron_25pct().data
# actual.shape = (50, 256, 256)

# Create a gaussian kernel that will be used to blur the original acquisition
kernel = np.zeros_like(actual)
for offset in [0, 1]:
    kernel[tuple((np.array(kernel.shape) - offset) // 2)] = 1
kernel = ndimage.gaussian_filter(kernel, sigma=1.)
# kernel.shape = (50, 256, 256)

# Convolve the original image with our fake PSF
data = signal.fftconvolve(actual, kernel, mode='same')
# data.shape = (50, 256, 256)

# Run the deconvolution process and note that deconvolution initialization is best kept separate from 
# execution since the "initialize" operation corresponds to creating a TensorFlow graph, which is a 
# relatively expensive operation and should not be repeated across multiple executions
algo = fd_restoration.RichardsonLucyDeconvolver(data.ndim).initialize()
res = algo.run(fd_data.Acquisition(data=data, kernel=kernel), niter=30).data

fig, axs = plt.subplots(1, 3)
axs = axs.ravel()
fig.set_size_inches(18, 12)
center = tuple([slice(None), slice(10, -10), slice(10, -10)])
titles = ['Original Image', 'Blurred Image', 'Reconstructed Image']
for i, d in enumerate([actual, data, res]):
    img = exposure.adjust_gamma(d[center].max(axis=0), gamma=.2)
    axs[i].imshow(img, cmap='Spectral_r')
    axs[i].set_title(titles[i])
    axs[i].axis('off')

Neuron Example

As a more realistic use case, here is an example showing how a point spread function configuration can be used in a headless deconvolution:

See full deconvolution script here

# Generate a configuration file containing PSF parameters (see flowdec.psf module for more details)
echo '{"na": 0.75, "wavelength": 0.425, "size_z": 32, "size_x": 64, "size_y": 64}' > /tmp/psf.json

# Invoke deconvolution script with the above PSF configuration and an input dataset to deconvolve.
# If flowdec has been installed, you may run the “deconvolution” command.
python examples/scripts/deconvolution.py \
--data-path=flowdec/datasets/bars-25pct/data.tif \
--psf-config-path=/tmp/psf.json \
--output-path=/tmp/result.tif \
--n-iter=25 --log-level=DEBUG
> DEBUG:Loaded data with shape (32, 64, 64) and psf with shape (32, 64, 64)
> INFO:Beginning deconvolution of data file "flowdec/datasets/bars-25pct/data.tif"
> INFO:Deconvolution complete (in 7.427 seconds)
> INFO:Result saved to "/tmp/result.tif"

Examples

Python

Java

Installation

The project can be installed, ideally in a python 3.6 environment (though it should work in 3.5 too), by running:

pip install flowdec[tf_gpu]

The previous command will install flowdec, but also ensure that tensorflow is installed with GPU support. For test purposes, you may have the non-GPU enabled version of tensorflow installed by running:

pip install flowdec[tf]

If neither [tf] nor [tf_gpu] are specified, tensorflow installation is left as an externally managed prerequisite.

Alternatively, the project could be installed from source by doing the following:

git clone https://github.com/hammerlab/flowdec.git
cd flowdec/python
pip install -e .

Docker Instructions

A local docker image can be built by running:

cd flowdec  # Note: not flowdec/docker, just cd flowdec

docker build --no-cache -t flowdec -f docker/Dockerfile .

# If on a system that supports nvidia-docker, the GPU-enabled version can be built instead via:
# nvidia-docker build --no-cache -t flowdec -f docker/Dockerfile.gpu .

The image can then be run using:

# Run in foreground (port mapping is host:container if 8888 is already taken)
docker run -ti -p 8888:8888 flowdec

# Run in background
docker run -td -p 8888:8888 --name flowdec flowdec
docker exec -it flowdec /bin/bash # Connect

The Flowdec dockerfile extends the TensorFlow DockerHub Images 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.

The previous image is built from the current master branch of github.com/hammerlab/flowdec.git. To build an image using your local copy of the source instead, you can use this command:

docker build --no-cache -t flowdec -f docker/Dockerfile.devel .

You may want to combine this with a bind mount of your local source tree into the running container. This setup will let you make edits to the source and have them immediately take effect in the running container.

LOCAL_SRC=$(pwd)
DEST_SRC=/repos/flowdec

docker run -ti -p 8888:8888 -v ${LOCAL_SRC}:${DEST_SRC} flowdec

Validation

By in large, the purpose of this project is to attain near equivalence with a subset of the functionality provided by both DeconvolutionLab2 and PSFGenerator via much faster implementations.

To validate this much has been accomplished, there are two notebooks in the python/validation folder demonstrating the following:

Acknowledgements

Thanks to Kyle Douglass for explaining some of the finer aspects of this Python Gibson-Lanni PSF generator, 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.

Citation

To cite Flowdec, please use this reference:

@article {Czech460980,
    author = {Czech, Eric and Aksoy, Bulent Arman and Aksoy, Pinar and Hammerbacher, Jeff},
    title = {Cytokit: A single-cell analysis toolkit for high dimensional fluorescent microscopy imaging},
    elocation-id = {460980},
    year = {2018},
    doi = {10.1101/460980},
    publisher = {Cold Spring Harbor Laboratory},
    URL = {https://www.biorxiv.org/content/early/2018/12/14/460980},
    eprint = {https://www.biorxiv.org/content/early/2018/12/14/460980.full.pdf},
    journal = {bioRxiv}
}

References