User API

The flimage API is built upon the hdf5 file format using h5py. It is almost identical to the user API of qpimage. Each instance of flimage.FLImage generates an hdf5 file, either on disk or in memory, depending on the preferences of the user.

Storing FLImage data on disk

To cache the FLImage data on disk, use the with statement in combination with the h5file keyword argument

with flimage.FLImage(data=fluorescence_ndarray, h5file="/path/to/file.h5"):
    pass

where all data is stored in /path/to/file.h5. This will create an hdf5 file on disk that, at a later time point, can be used to create an instance of FLImage:

# open previously cached data for reading
fli = flimage.FLImage(h5file="/path/to/file.h5", h5mode="r")

# or open cached data for writing (e.g. for changing the background)
with flimage.FLImage(h5file="/path/to/file.h5", h5mode="a") as fli:
    # do something here

The default value of h5mode is “a”, which means that data will be overridden. In the hdf5 file, the following data is stored:

  • all data for reproducing the background-corrected fluorescence (fli.fluorescence) including

    • the experimental fluorescence data

    • the experimental background data

  • all measurement specific meta data, given by the keyword argument meta_data

Dealing with measurement series

Flimage also comes with a FLSeries class for handling multiple instances of FLImage in one hdf5 file. For instance, to combine two FLImages in one series file, one could use:

paths = ["file_a.h5", "file_b.h5", "file_c.h5"]

with flimage.FLSeries(h5file="/path/to/series_file.h5", h5mode="w") as fls:
    for ii, pp in enumerate(paths):
        fli = flimage.FLImage(h5file="/path/to/file.h5", h5mode="r")
        fls.add_flimage(fli=fli, identifier="my_name_{}".format(ii))

Note that the function add_flimage accepts the optional keyword argument “identifier” (overriding the identifier of the FLImage) which can also be used for indexing later:

with flimage.FLSeries(h5file="/path/to/series_file.h5", h5mode="r") as fls:
    # these two are equivalent
    fli = fls[0]
    fli = fls["my_name_0"]

Notes

  • Even though the hdf5 data is stored as gzip-compressed single precision floating point values, using flimage hdf5 files may result in file sizes that are considerably larger compared to when only the output of e.g. qpi.fluorescence is stored using e.g. numpy.save().

  • Units in flimage follow the international system of units (SI).

  • flimage.FLSeries provides convenience functions for bleach correction.