sakoho81 / miplib Goto Github PK

A Python software library with a variety of functions for (optical) microscopy image restoration, reconstruction and analysis.

License: Other

Batchfile 0.01% Shell 0.01% Python 13.26% C 0.96% Jupyter Notebook 85.78%

image-processing image-restoration image-resolution image-analysis microscopy-images deconvolution-microscopy fourier-analysis

miplib's Introduction

MIPLIB

Microscope Image Processing Library (MIPLIB) is a Python based software library, created especially for processing and analysis of fluorescece microscopy images. It contains functions for example for:

image registration 2D/3D
image deconvolution and fusion (2D/3D), based on efficient CUDA GPU accelerated algorithms
Fourier Ring/Shell Correlation (FRC/FSC) based image resolution analysis -- and several blind image restoration methods based on FRC/FSC.
Image quality analysis
...

The library is distributed under a BSD open source license.

How do I install it?

I would recommend going with the Anaconda Python distribution, as it removes all the hassle from installing the necessary packages. MIPLIB should work on all platforms (Windows, MacOS, Linux), however I do not actively test it on Windows.

Here's how to setup your machine for development:

There are some C extensions in miplib that need to be compiled. Therefore, if you are on a mac, you will also need to install XCode command line tools. In order to do this, Open Terminal and write xcode-select --install. If you are on Windows, you will need the C++ compiler
The Bioformats plugin that I leverage in MIPLIB to read microscopy image formats requires Java. Therefore, make sure that you have JRE installed if you want to use the bioformats reader. If you are on Windows, also make sure that the JAVA_HOME environment variable is set. You may also have to add the JAVA_HOME to your PATH. More info on that can be found here: JPYPE.
Fork and clone the MIBLIB repository (git clone [email protected]:<your_account>/miplib.git). The code will be saved to a sub-directory called miplib of the current directory. Put the code somewhere where it can stay. You may need to generate an SSH key, if you have not used GitHub previously.
Go to the miplib directory and create a new Python virtual environment conda env create -f environment.yml. Alternatively use environment_nocuda.yml, if you do not want to use GPU acceleration.
Activate the created virtual environment by writing conda activate miplib
Now, install the miplib package to the new environment by executing the following in the miplib directory python setup.py develop. This will only create a link to the source code, so don't delete the miplib directory afterwards.

And if you are not a developer

If you just want to use the library, you can get everything running as follows:

Download the environment_client.yml file and create a Python virtual environment conda env create -f environment_client.yml.
Activate the created virtual environment by writing conda activate miplib

How do I use it?

My preferred tool for explorative tasks is Jupyter Notebook/Lab. Please look for updates in the Examples/ folder (a work in progress). Let me know if you would be interested in some specific example to be included.

There are also a number of command line scripts (entry points) in the bin/ directory that may be handy in different batch processing tasks. They are also a good place to start exploring the library.

Contribute?

MIPLIB was born as a combination of several previously separate libraries. The code and structure, although working, might (does) not in all places make sense. Any suggestions for improvements, new features etc. are welcome.

Regarding Python versions

I recenly migrated MIPLIB to Python 3, and have no intention to maintain backwards compatibility to Python 2.7. You can checkout an older version of the library, if you need to work on Python 2.7.

About GPU acceleration

The deconvolution algorithms can be accelerated with a GPU. On MacOS the CUDA GPU acceleration currently does not work, because there are no NVIDIA drivers available for the latest OS versions. I recently re-factored the GPU acceleration functions, using the CuPy library. It would in principle be possible to use OpenCL backend, instead of CUDA, but I have not tried that (yet).

Publications

Here are some works that have been made possible by the MIPLIB (and its predecessors):

Koho, S. V. et al. Two-photon image-scanning microscopy with SPAD array and blind image reconstruction. Biomed. Opt. Express, BOE 11, 2905–2924 (2020)

Koho, S. et al. Fourier ring correlation simplifies image restoration in fluorescence microscopy. Nat. Commun. 10 3103 (2019).

Koho, S., T. Deguchi, and P. E. E. Hänninen. 2015. “A Software Tool for Tomographic Axial Superresolution in STED Microscopy.” Journal of Microscopy 260 (2): 208–18.

Koho, Sami, Elnaz Fazeli, John E. Eriksson, and Pekka E. Hänninen. 2016. “Image Quality Ranking Method for Microscopy.” Scientific Reports 6 (July): 28962.

Prabhakar, Neeraj, Markus Peurla, Sami Koho, Takahiro Deguchi, Tuomas Näreoja, H-C Huan-Cheng Chang, Jessica M. J. M. Rosenholm, and Pekka E. P. E. Hänninen. 2017. “STED-TEM Correlative Microscopy Leveraging Nanodiamonds as Intracellular Dual-Contrast Markers.” Small 1701807 (December): 1701807.

Deguchi, Takahiro, Sami Koho, Tuomas Näreoja, and Pekka Hänninen. 2014. “Axial Super-Resolution by Mirror-Reflected Stimulated Emission Depletion Microscopy.” Optical Review 21 (3): 389–94.

Deguchi, Takahiro, Sami V. Koho, Tuomas Näreoja, Juha Peltonen, and Pekka Hänninen. 2015. “Tomographic STED Microscopy to Study Bone Resorption.” In Proceedings of the SPIE, 9330:93301M – 93301M – 6.

miplib's People

Contributors

Stargazers

Watchers

miplib's Issues

trying to to solve the problem of error reporting after interpolation

Hi,
I'm very interested in your open source code, and attempts to reconstruct, but when I changed the input of the example, I met some error below (multiple sets of data were tried, just part of them were wrong ), I tried to change the border of the minimum optimization problem, but useless. I'm confused, what is the problem of this error? data or the interpolation value?

//..
error: ~.conda\envs\miplib\lib\site-packages\scipy\interpolate\interpolate.py in _check_bounds(self, x_new)
689 "range.")
690 if self.bounds_error and above_bounds.any():
--> 691 raise ValueError("A value in x_new is above the interpolation "
692 "range.")
693

ValueError: A value in x_new is above the interpolation range.

trying to figure out the image input requirements

Hi,

I liked your article. i was looking for fsc/frc analysis and the work you did to develop deconvolution algorithm based on the psf is pretty neat. I was trying to use it using the library.

if you could update the "FRC based frequency domain filtering" notebooks for broken links? example. ffutils and ideal_fft_filter. didn't take me long to debug but was confusing to figure out where you had moved files.

2.Could i ask for some ground rules on the shape/format for data that the code is looking for (only square?) More importantly i'm trying to figure out why i get the following error...only sometimes. I had a stack of 91 images and 90 work but i can't figure out why this one won't. I also tried to upscale an image so 200x200 --> 400x400 and i get the same error. I had a dickens of a time trying to puzzle out how to change args in the arg list. Perhaps there is some size limit? or is it that i'm not correcting some other parameter? i haven't been able to puzzle it out yet. Thank you again. love the code i want to share it with a colleague who might find it useful for x-ray fluorescence microscopy deconvolution.

If i could request a meeting to discuss? [email protected]

best regards,

Aaron

solved

A question about the three-sigma theshold criteria.

Hi Thank you for your generous sharing of the code, they are pretty neat and readable. I am wondering if you could please explain that in the definition of the three-sigma criteria (analysis.py): 3/(sqrt(number of points) + 3 - 1), what does the +3-1 account for in the denominator?

I really appreciate any help you can provide.

Issues related to deconvolution in ‘deconvolve.py’ files

Yes it's me again, haha. I appreciate your work very much and I have read your procedures carefully，but I still have some doubts due to my own inadequacies.
1、Unable to open file ops_ext.cp36-win_amd64.pyd，so I can't understand how to use the function div_unit_grad() and the update_estimate_poisson() .What is the meaning of their return value？I can only literally understand what they mean，like calculate divergence and Poisson distribution ？
2、I want to use total variation regularization to constrain the RL deconvolution.Can I just assign a value to tv-lambda?What is the appropriate value for tv-lambda, I'll assign it to him. Running the program often results in errors
3、In your article, after using the background mask to remove the background ,the deconvolution works very well.I've added a paragraph “ rl_auto_background=Ture ”to the args_list ,but it doesn't seem to be working properly.
I hope you can give me some guidance in your busy schedule. Thank you！

Version issues when installing

I'm trying to install your library into a fresh conda environment on a Ubuntu system with an Nvidia Titan RTX GPU and ran into a few issues. I replicated these issues on a Windows 10 machine with an Nvidia Titan XP.

pyculib is no longer maintained - so you need to pull it from channel numba (or somewhere else)
I believe cudatoolkit=7.5 is no longer on the conda channel. Is it safe to update this to the modern toolkit version (e.g. 10.2?) Or does your library require an older version of CUDA? If so, what channel should it be installed from?
Once I get the package installed using a modified environment_client.yml to address 1 and 2 above, I am unable to run the examples. This appears to be an issue with changes to Numpy on how boolean operations are handled. If I try to run the One Image Sectioned FSC and 3D Wiener Filtering notebook, I get the follow error for this code:
%% capture
result = fsc.calculate_one_image_sectioned_fsc(image,args,z_correction=z_correction)

Error (truncated to most important part):
TypeError: numpy boolean subtract, the '-' operator, is deprecated, use the bitwise_xor, the '^' operator, or the logical _xor function instead.

What version of Numpy is the library complied for? After some internet searching, this appears to be a change in Numpy somewhere around version 1.14, but if I try numpy=1.13.3 in the enviroment_client.yml file, I get a version mismatch error when attempting import miplib.ui.cli.miplib_entry_point_options as options.

Thanks.

Some tif images don't include pixel size information in their tags.

Some tif images don't include pixel size information in their tags.I have to assign a value to their ‘spacing’ attribute.But that's not accurate and it doesn't work well.I'd be happy if you had a good solution.Thank you！

3d fsc

Hi,

Thank you for your earlier comment. i'm having some issue trying to run the 3d fsc. i don't think its the same issue as before with the threshold not crossing.

python gives some warning: RankWarning: Polyfit may be poorly conditioned, otherwise it fails for the spline giving:
"A value in x_new is above the interpolation range."

I really wanted to see if i could do the 1 dataset fsc but it just flat lines. i can do the projections ok with the FRC...any thoughts? maybe some setting i'm not aware of? there are a lot of options that i'm not clear about. thank you for your time.

How do I use image quality ranking?

How do I use the image quality assessment functions? For example : In batch_evaluate_image_quality(path, options) what are the 'options' ?
Also, can I use this method for ranking images of beads?