Opening and closing bins

Because IFCB data is stored in files, the files must be opened in order to read data from them, and then must be closed. For reasons of efficiency, pyifcb does not load each sample bin's image data into memory upon opening the sample bin. Instead, image data is read from the file as it is requested. To manage opening and closing the ROI file containing image data, sample bins provide context manager support, which is invoked using the with statement. Reading image data is then done within the code block under the with statement, and after that code block runs (or fails), pyifcb will close all open data files. In this example, a set of files is opened, the first image is read, and the files are closed.

import ifcb

PATHNAME = '/mnt/ifcb_data/D20170305T123456_IFCB107.adc'

with ifcb.open_raw(PATHNAME) as sample_bin:
    first = sample_bin.images.keys()[0]
    image = sample_bin.images[first]

If the sample bin is returned from a DataDirectory, then you should still use the context manager:

data_dir = ifcb.DataDirectory('/mnt/ifcb_data')

for sample_bin in data_dir:
    with sample_bin:
        first = sample_bin.images.keys()[0]
        image = sample_bin.images[first]
        ...

If you do not use the context manager, you can still access image data in exactly the same way, but pyifcb will open and close files as data is requested, opening and closing the ROI file many times if multiple images are accessed.

Reading all data at once

If you want to access all data and images from a sample bin, and don't want to leave any files open while you are doing that, you can read all bin data into memory using the sample bin's read method. The method returns a new sample bin that holds and provides access to all the metadata, ADC data, and image data, without requiring any additional file I/O. For example:

with sample_bin:
    all_data = sample_bin.read()

# all files are closed now

for roi_number in all_data.images:
    image = all_data.images[roi_number]
    ...

Note that if you read a large number of sample bins in this way and retain references to all of them, you may run out of memory. Each sample bin may contain over 20MB of image data. If you read each sample bin once, process it, and move on to the next one, you will not have this problem.

If you want to free up memory associated with a bin returned by read, you can use the del statement on it:

with sample_bin:
    all_data = sample_bin.read()

# all files are closed now

image = all_data.images[3]
del all_data

# 'image' still contains image data