BIFS

Bayesian Image Analysis in Fourier Space

BIFS is a framework and set of computational tools for implementation of Bayesian Image analysis in Fourier Space. The BIFS approach enables enhanced feature contrast and noise reduction, analogous to, but much more efficiently than Bayesian methods applied directly in image space, such as Markov Chain Monte Carlo methods. This efficiency is provided by the fact that for a large class of images the Fourier modes can reasonably be approximated as being independent, thus reducing the optimization problem from one involving a large number of coupled variables to one involving a product of independent one dimensional optimizations. BIFS is useful for a large class of images and in particular for medical imaging problems, including clinical imaging studies, screening, diagnosis, and treatment evaluation.

Installation

Prerequisites:

• Python3 installed on your computer.

For the impatient, here are steps which should install the package and launch the GUI:

#python may work instead of python3, depending on your environment
#py -3 should work on MS-Windows
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install bifs
bifs_gui

bifs requires a number of other substantial software packages, including SciPy and PyQt5, which the installation should take care of if they are not already present.

Virtual Environments

See this guide for much more information about how to install python packages. In particular, we endorse their strong recommendation to use virtual environments, which are omitted from the steps above.

On Windows inside a virtual environment we have found python rather than python3 is necessary.

We recommend against using the Windows-specific py command since it only respects the venv sometimes, for example py -3 will ignore it, under Python 3.9, and may have been even less reliable with earlier versions.

Qt Compatibility Problems

The graphical program bifs_gui depends on the Qt graphic framework. This will be installed automatically if it is not present, but if it is already present the packages that pip installs may not be compatible with it. We found this to be the case on Debian GNU/Linux 10 (buster). If you get such a problem, you can fix it by specifying an explicit version for PyQt5 with ==:

(testEnv) ross@barley:~/UCSF/Kornak$ python -m pip install PyQt5==5.11.2
Collecting PyQt5==5.11.2
  Downloading PyQt5-5.11.2-5.11.1-cp35.cp36.cp37.cp38-abi3-manylinux1_x86_64.whl (117.9 MB)
     |████████████████████████████████| 117.9 MB 84 kB/s 
Collecting PyQt5_sip<4.20,>=4.19.11
  Downloading PyQt5_sip-4.19.19-cp37-cp37m-manylinux1_x86_64.whl (67 kB)
     |████████████████████████████████| 67 kB 997 kB/s 
Installing collected packages: PyQt5-sip, PyQt5
  Attempting uninstall: PyQt5-sip
    Found existing installation: PyQt5-sip 12.9.0
    Uninstalling PyQt5-sip-12.9.0:
      Successfully uninstalled PyQt5-sip-12.9.0
  Attempting uninstall: PyQt5
    Found existing installation: PyQt5 5.15.4
    Uninstalling PyQt5-5.15.4:
      Successfully uninstalled PyQt5-5.15.4
Successfully installed PyQt5-5.11.2 PyQt5-sip-4.19.19

5.11.2 is the version of Qt that was already on the system, while 5.15.4 is the version that pip installed.

The current stable release of Debian is 11 (bullseye) and uses Qt 5.15.2, probably close enough to work with the default installation of PyQt5.

See https://github.com/ucsf-deb/bifs/issues/25 for more.

An alternative would be to manually install the required packages (see the requirements.txt or setup.py files) using your OS's package manager instead of pip, and then install bifs without using a virtual environment.

Fallback Installation of Dependencies

We are still working on the packaging, as well as the instructions, and it is possible you will encounter difficulties. If the necessary dependencies are not installed automatically, try changing to the top level of the repository and executing

python3 -m pip install -r requirements.txt

If even that doesn't work, you can manually tell it to install the packages listed in the requirements file, e.g.,

python3 -m pip install numpy

Fallback Package Setup

If the regular setup fails it means that import bifs will not be able to find the package. Since the bifs code itself does such imports, it won't run without it.

A workaround is to manually add an entry to the PYTHONPATH environment variable for the root directory of the repository you cloned from GitHub.

If you clone the project following the instructions above and you are in /tmp, it will create a directory /tmp/bifs. It is this directory, not /tmp/bifs/bifs that you will find under it, that should go in PYTHONPATH. See how to do it graphically or from the command line on MS-Windows or for Mac or Linux. One can also manipulate sys.path inside a Python program.

Known Compatible Software Versions

BIFS is known to work with the following versions but will typically work with many earlier versions as well:

• Python 3
• numpy 1.17 (no earlier)
• scipy 1.2.1-1
• matplotlib 2.2.4-2
• imageio 2.4.1
• jsonpickle 1.2
• pyqt5 5.7.1-1 (note: some version of PyQT 5 is required, i.e. the package will not work with PyQT 4)
• nibabel is listed in the requirements file, but the software will run without it. It is only needed if you load an image type for which it is required, e.g., a .nii file.

Using BIFS

See the more detailed guide and the extensive comments in the code for how to use the package.

Exploring the code

https://github.com/ucsf-deb/bifs