Installation notes

Introduction

We have tried to make it as easy as possible to install and use the jicbioimage package. Here we detail two options:

If you are not familiar with Docker it is probably easiest to start with a manual install. However, if you are already familiar with Docker it is certainly a very convenient way of creating an environment in which to install and run jicbioimage.

Manual install

Install the freeimage library

The jicbioimage package depends on freeimage to open image file.

On Linux bases system freeimage can usually be installed using the package manager. For example on Fedora it can be installed using the command below.

yum install freeimage

On Macs it can be installed using homebrew using the command below.

brew install freeimage

On Windows download and unzip the FreeImage DLL (in the example below this was done to the root of the C: drive). You will then need to add the relevant directory to your PATH, for example on a 64-bit system:

set PATH=C:\FreeImage\Dist\x64;%PATH%

Install the Python package dependencies

The jicbioimage package depends on a number of other scientific Python packages. These can be installed using pip.

pip install numpy
pip install scipy
pip install scikit-image

Although the jicbioimage package does not depend on it you may also want to install the IPython notebook. The jicbioimage package has been designed to work well with IPython notebook, for example by providing the ability to view jicbioimage.core.image.Image and jicbioimage.core.image.ImageCollection objects as images and tables of images in the IPython notebook.

pip install jupyter

Install the BioFormats command line tools

The jicbioimage package does not explicitly depend on the BioFormats command line tools. However, they are needed if you want to be able to work with microscopy files.

Download the bftools.zip file from the openmicroscopy website.

Warning

jicbioimage.core version 0.14 and greater require BioFormats to be version 5.2.1 or greater to make use of the -nolookup option.

You will then need to unzip the file and add it to your PATH.

On Linux and Mac based systems unzip the bftools.zip file into a memorable location, for example a directory named tools.

mkdir ~/tools
mv ~/Downloads/bftools.zip ~/tools/
cd ~/tools
unzip bftools.zip

Finally add the bftools directory to your PATH.

export PATH=$PATH:~/tools/bftools

Note

You may want to add the line above to your .bashrc file.

On Windows unzip the bftools.zip file to a memorable location, for example the C:\ drive and set the PATH appropriately:

set PATH=C:\bftools;%PATH%

Install the jicbioimage package

Finally install the jicbioimage package using pip.

pip install jicbioimage.core
pip install jicbioimage.transform
pip install jicbioimage.segment
pip install jicbioimage.illustrate

Using Docker

Docker is a technology that allows one to package software along with all its dependencies in a fashion that ensures that the software will always run the same.

For this purpose we have created the jicscicomp/bioformats docker image. It contains all the jicbioimage dependencies, but not the jicbioimage package itself. You can find out how this Docker image was built in the JIC-CSB/scicomp_docker GitHub repository.

If you are already familiar with Docker you can try it out using the command below.

$ docker run -it --rm jicscicomp/bioformats
[root@03fda753e799 /]# pip install jicbioimage.core
[root@03fda753e799 /]# pip install jicbioimage.transform
[root@03fda753e799 /]# pip install jicbioimage.segment
[root@03fda753e799 /]# pip install jicbioimage.illustrate

If you have not used Docker before you will need to install it. On Mac and Windows download and install the Docker Toolbox. Docker runs natively on Linux, but you will need to install it, see the Docker Installation Notes.

For our image analysis projects we tend to create three directories in our project: scripts (where we put the Python scripts), data (where we put the raw images) and output (where our scripts write their output). When then use a bash script along the lines of the below to launch a container that has access to these directories (read only for the data and scripts directories).

#!/bin/bash

docker run -it --rm -v `pwd`/data:/data:ro  \
                    -v `pwd`/scripts:/scripts:ro  \
                    -v `pwd`/output:/output jicscicomp/bioformats

You will have noticed that we did not include the jicbioimage package in the jicscicomp/bioformats Docker image. The reason for this is that we like to create a specific Docker image for each bioimage analysis project.

If you want to do this you need to create a directory for your Docker image, for example cell_analysis. In that directory you then create a requirements.txt file with all your Python requirements, e.g.:

jicbioimage.core
jicbioimage.transform
jicbioimage.segment
jicbioimage.illustrate

And a Dockerfile containing the instructions below.

FROM jicscicomp/bioformats

COPY requirements.txt .
RUN pip install -r requirements.txt

You can now use this setup to build your own Docker image using the command below.

docker build -t cell_analysis .

Now you can update your bash script to make use of your custom built image, tagged cell_analysis.

#!/bin/bash

docker run -it --rm -v `pwd`/data:/data:ro  \
                    -v `pwd`/scripts:/scripts:ro  \
                    -v `pwd`/output:/output cell_analysis

In our day to day work, providing bioimage analysis support across the John Innes Centre, we have templated much of our initial project setup using Cookiecutter. For some inspiration you may want to install Cookiecutter and create a project setup using our JIC-Image-Analysis/cookiecutter-image-analysis template hosted on GitHub. The command below uses Cookiecutter to create a new project using this template.

$ cookiecutter gh:JIC-Image-Analysis/cookiecutter-image-analysis

Enjoy!