Package pyxudeconv

3D Deconvolution with Pyxu library. In particular, it includes the Goujon accelerated Richardson-Lucy (GARL). Please read the extended documentation (GARL PDF file) to know more about the method.

---

Installation

Before running pip install, please install via conda some packages beforehand (avoid incompatibilities):

conda install -c conda-forge numpy scipy

You can then install pyxudeconv via pip (please look at the next section first):

pip install pyxudeconv

or with GPU compatibility via pip (e.g., CUDA 12.x):

pip install pyxudeconv[gpu12]

Important note for GPU version

• Please install torch with the correct CUDA version via the official pytorch website and via conda.

To install latest development version :

pip install git+https://github.com/ThanhAnPham/pyxudeconv.git

Deconvolution with Pyxu

Deconvolving in a python code

After the package import, the deconvolution is performed by the function deconvolve which expects the parameters (namespace). To modify the parameters, there are two ways

• Load the default parameters via get_param and modify each field of interest

  import pyxudeconv
  par = pyxudeconv.get_param()
  par.psfpath = '/home/tampham/3DWCR/data/simulated/psf_sample_calib_nv_32_coi_2.ome.tif'
  par.datapath = '/home/tampham/3DWCR/data/simulated/g_sample_calib_nv_32_coi_2.ome.tif'
  par.phantom = '/home/tampham/3DWCR/data/simulated/phantom_sample_calib_nv_32_coi_2.ome.tif'
  par.fres = '/home/tampham/yo'
  par.saveIter = [10]
  par.methods = ['RL','GARL','Tikhonov']
  imdeconv = pyxudeconv.deconvolve(par)
  

• Change the json file and load it.

  import pyxudeconv
  par = pyxudeconv.get_param(param_file='./my_params.json')
  imdeconv = pyxudeconv.deconvolve(par)
  

Note that par.psfpathand par.datapath can be numpy.ndarray already loaded in the python code

par.psfpath = mypsf #numpy.ndarray
par.datapath = mydata #numpy.ndarray

Deconvolving in a terminal

The main function deconvolve can be called as a command-line with arguments or via a bash file (see main_example.sh or main_calibration.sh) with the option -m.

Two arguments are important if applied on your own data

• datapath: Path to the data to deconvolve OR if ran through a python script it can be a ndarray itself
• psfpath: Path to the point-spread function OR if ran through a python script it can be a ndarray itself

Currently supported file formats

• .czi: Carl Zeiss files
• .tif: Expected order of the dimension (Time, Views, Channels, Z, Y, X). Note that the file is first fully loaded, then the region of interest is kept for further processing. One drawback is that the RAM memory usage may be temporarily large.

An example of calling the script with a command-line

python -m pyxudeconv.deconvolve --fres '../res/donuts' --gpu 0 --datapath '../data/real_donut/data.tif' --psfpath '../data/real_donut/psf.tif' --saveIter 10 10 10 10 10 --nviews 1 --methods 'RL' 'GARL' --Nepoch 50 --bufferwidth 20 10 10   --pxsz 79.4 79.4 1000 --bg 0 --psf_sz -1 -1 128 128 --roi 0 0 150 150 --config_GARL 'widefield_params'

Note on dependencies

If Goujon accelerated Richardon-Lucy (GARL) and/or GPU will be used, please install torch¹ according to your case. For instance, If the GPU CUDA version is 12.1, the conda environment can be created in a terminal with the commands

• conda create -n pyxudeconv python=3.11 pytorch=2.4.1 pytorch-cuda=12.1 tifffile numpy scipy matplotlib -c pytorch -c nvidia -c conda-forge
• conda activate pyxudeconv
• pip install pyxu[complete]

Goujon Accelerated Richardson-Lucy (GARL)

To use GARL, call python -m pyxudeconv.deconvolve with the argument --methods 'GARL'. To run over different hyperparameters, you can add the argument --config_GARL 'full_path/your_config_file.json'.

Note: Each parameter must be a list of values, even if it is a single-valued list. For instance, here is an example of a .json config file

{
    "WCRnet": ["pyxudeconv/trained_models/3Dtubes/"],
    "epochoi": [40180],
    "lmbd": [0.1, 0.5],
    "sigWC": [0.1, 0.5]
}

Alternatively, one can set a range of values for a parameter (e.g., lmbd) as follows

{
    "WCRnet": ["pyxudeconv/trained_models/3Dtubes/"],
    "epochoi": [40180],
    "lmbd_min": 0.1,
    "lmbd_max": 0.5,
    "lmbd_nsteps": 2,
    "sigWC": [0.1, 0.5]
}

Simulation

The function simulatecan simulate measurements obtained from a phantom defined by --phantom your_phantom_file convolved with a PSF defined by --psfpath your_psf_file. Future releases may change the organisation of the simulation part.

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the MIT license, "pyxudeconv" is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.

Footnotes

1. 21/10/2024, there might be an incompatiblity with the sympy(==1.13.1) package version required by pytorch >= 2.5.0. Either downgrade sympy to 1.13.1 (but may create incompatibilities with pyxu) or install pytorch=2.4.1. ↩