4. Image import/export¶

We have already seen a quick example of image import. Here, we are going to learn about this in more details.

4.1 Simple case¶

Most of the time the simples command imread() will do the job. One has just to specifiy the path of the file or a url. In general your path is going to look something like:

image = io.imread('/This/is/a/path/MyData/Klee.jpg')

Here we only use a relative path, knowing that the Data folder is one level above the notebook folder. However you can also give a complete path. We can also check what's the complete path of the current file:

Now we can import the image:

Now with a url:

4.2 Series of images (.tif)¶

Popular compressed formats such as jpg are usually used for natural images e.g. in facial recognition. The reason for that is that for those applications, in most situations one does not care about quantitative information and effects of information compression occurring in jpg are irrelevant. Also, those kind of data are rarely multi-dimensional (except for RGB).

In most other cases, the actual pixel intensity gives important information and one needs a format that preserves that information. Usually this is the .tif format or one of its many derivatives and we are focusing throughout this course on this format.

Very often data contain multiple levels of information e.g. channels, time-lapses etc. There are two ways of storing that information: as separate single-plane tif files or as large multi-dimensional tif files.

4.2.1 Series of separate images¶

In the first case, you would have multiple single .tif files within one folder. In that case, the file name usually contains indications about the content of the image, e.g a time point or a channel. The general way of dealing with this kind of situation is to use regular expressions, a powerful tool to parse information in text. This can be done in Python using the re module.

Here we will use an approach that identifies much simpler patterns.

Let's first see what files are contained within a folder of a microscopy experiment containing images acquired at two wavelengths using the os module:

Let's list all the files contained in the folder

The two channels are defined by the last character before .tif. Using the wild-card sign * we can define a pattern to select only the 'd' channel: *d.tif. We complete that name with the correct path. Now we use the native Python module glob to parse the folder content using this pattern:

Then we use again the imread() function to import a specific file:

These two steps can in principle be done in one step using the imread_collection() function of skimage.

We can also import all images and put them in list if we have sufficient memory:

Or better:

Let's see what we have in that list of images by plotting them:

scikit-image offers an out-of-the box solutions for such cases. You can simply import a series of images using:

4.2.2 Multi-dimensional stacks via skimage¶

We now look at a more complex multi-dimensional case taken from a public dataset (J Cell Biol. 2010 Jan 11;188(1):49-68) that can be found here. It is already provided it in the Data folder:

The dataset is a time-lapse 3D confocal microscopy acquired in two channels, one showing the location of tubulin, the other of lamin (cell nuclei).

All .tif variants have the same basic structure: single image planes are stored in individual "sub-directories" within the file. Some meta information is stored with each plane, some is stored for the entire file. However, how the different dimensions are ordered within the file (e.g. all time-points of a given channel first, or alternatively all channels of a given time-point) can vary wildly, and thus image import might have different outcomes. The simplest we can do is to just try to import the dataset with the imread() function:

From the reference, we know that we are supposed to have 72 time-points, 2 channels, 5 z-stacks, so the importer did a good job at creating a mulit-dimensional numpy array. One of the drawbacks of this approach is that it's not usable for very large datasets as all data are loaded into RAM.

Using slicing, we look at the first time point, of both channels, of the first plane, and we indeed get an appropriate result:

Now that we have a Numpy array, we can do the various operations on arrays that we learned about previously. For example, knowing that z is the third dimension (index = 2) we can do a z-projection on that axis for a given channel (0) and time point (0). Note that since we fix the two first dimensions, our array is reduced to a 3D array and we project along what is now the 1st dimension:

skimage also allows one to use specific import plug-ins for various applications (e.g. gdal for geographic data, FITS for astronomy etc.). See here for more details.

In addition, one can have access to a lower level reader in particular for tiff files. It is accessible through the MultiImage object of the skimage.io module:

The advantage of this approach is that, using the default options, the reader doesn't load the full dataset into RAM but only parses the content of the file. The length of data indicates the number of images found in the file:

We see that this matches what we obtained before with the standard image reader which had $72 x 5 x 2 = 720$ images.

Then we can actually load a single plane with:

This loads only the first plane of the stack. The following ones are loaded by using indices 1-719. We can visually verify that we indeed load image planes:

Multi-dimensional stacks via other importers¶

skimage is not designed to parse metadata, but gives a low-level access to the data. If you are using data that have some standardized metadata you can attempt to use other importers that will parse that information. For example in the example above MultiImage just gave us a list of images, but no info on the dimensions. We show here how to use the package AICSImageIO (from the Allen Institute for Cell Science) which gives access to the metadata, as well many other features not demonstrated here.

Just like before we start by importing the reader object and then use it to read data:

Now we have access to a long list of metadata. For example the order of the dimensions:

Or the size of each dimension, for example time or z-stacks:

Finally, we can access the actualy data, and in particular specify sub-stacks:

4.2.3 Alternative formats¶

While a large majority of image formats is somehow based on tif, instrument providers often make their own tif version by creating a proprietary format. This is for example the case of the Zeiss microscopes with .lsm or .czi formats. Some of those files can still be read by skimage.io.imread() albeit using a specific reader to make sure the data are read properly. Let's try for example to open the following file from Zenodo:

It looks like we only have a single plane of two channels. However, as the file name indicates, we expect to have a z-stack. The default importer did not manage to properly read the .lsm metadata and failed to import all files. We can fix this by using a specific plugin to read the file. In a large number of cases this is going to be tifffile (based on this work).

For more "exotic" cases, you will need to find a specific package capable of importing your file format however it is extremely rare that no reader already exists. Here we open for example an DeltaVision file for which a reader is available here.

4.3 Exporting images¶

There are two ways to save images. Either as plain matrices, which can be written and re-loaded very fast, or as actual images.

Just like for loading, saving single planes is easy. Let us save a small region of one of the images above:

Saving multi-dimensional .tif files is a bit more complicated as one has of course to be careful with the dimension order. Here's an example of how to save a dataset with two time poins, 5 stacks, 3 channels into a file that can then be opened as a hyper-stack in Fiji:

When opened in Fiji, the stack is correctly interpreted:

4.4 Interactive plotting¶

Jupyter offers a solution to interact with various types of plots: ipywidget

The interact() function takes as input a function and a value for that function. That function should plot or print some information. interact() then creates a widget, typically a slider, executes the plotting function and adjusts the ouptut when the slider is moving. For example:

Depending on the values passed as arugments, interact() will create different widgets. E.g. with text:

An important note for our imaging topic: when moving the slider, the function is continuously updated. If the function does some computationally intensitve work, this might just overload the system. To avoid that, one can explicitly specifiy the slider type and its specificities:

If we want to scroll through our image stack we can do just that. Let's first define a function that will plot the first plane of the channel 1 at all time points:

Of course we can do that for multiple dimensions:

And we can make it as fancy as we want: