python-bioformats: read and write life sciences image file formats

The python-bioformats package is an interface to the Bio-Formats library for reading and writing life sciences image file formats.

Because Bio-Formats is a Java library, python-bioformats uses python-javabridge to start and interact with a Java virtual machine.

Python-bioformats and python-javabridge were developed for and are used by the cell image analysis software CellProfiler (cellprofiler.org).

python-bioformats is licensed under the GNU General Public License (GPL). Many files are licensed under the more permissive BSD license.

Installation and testing

Install using pip

pip install python-bioformats

Running the unit tests

Running the unit tests requires Nose:

nosetests

On some installations, the following also works:

python nosetests.py

Starting the JVM

When starting the Java virtual machine with python-javabridge’s javabridge.start_vm(), you must add the contents of bioformats.JARS to the class path. Example:

>>> import javabridge
>>> import bioformats
>>> javabridge.start_vm(class_path=bioformats.JARS)
bioformats.JARS list of strings

List of directories, jar files, and zip files that should be added to the Java virtual machine’s class path.

Initialization and termination

The javabridge package must be used to start the JVM with loci_tools.jar which is the Bio-Formats library packaged with python-bioformats or with your own build of Bio-Formats. As a convenience, bioformats.JARS has a list of the required jar files.

import javabridge
import bioformats
javabridge.start_vm(class_path=bioformats.JARS)

# your program goes here

javabridge.kill_vm()

Reading images

class bioformats.ImageReader(path=None, url=None, perform_init=True)[source]

Find the appropriate reader for a file.

This class is meant to be harnessed to a scope like this:

>>> with GetImageReader(path) as reader:
>>>     ....

It uses __enter__ and __exit__ to manage the random access stream that can be used to cache the file contents in memory.

read(c=None, z=0, t=0, series=None, index=None, rescale=True, wants_max_intensity=False, channel_names=None, XYWH=None)[source]

Read a single plane from the image reader file. :param c: read from this channel. None = read color image if multichannel

or interleaved RGB.
Parameters:
  • z – z-stack index
  • t – time index
  • series – series for .flex and similar multi-stack formats
  • index – if None, fall back to zct, otherwise load the indexed frame
  • rescale – True to rescale the intensity scale to 0 and 1; False to return the raw values native to the file.
  • wants_max_intensity – if False, only return the image; if True, return a tuple of image and max intensity
  • channel_names – provide the channel names for the OME metadata
  • XYWH – a (x, y, w, h) tuple
close()[source]

Convenience functions that create an image reader for a file path or URL and use it to read an image:

bioformats.load_image(path, c=None, z=0, t=0, series=None, index=None, rescale=True, wants_max_intensity=False, channel_names=None)

Load the given image file using the Bioformats library.

Parameters:
  • path – path to the file
  • z – the frame index in the z (depth) dimension.
  • t – the frame index in the time dimension.
  • channel_names – None if you don’t want them, a list which will be filled if you do.
Returns:

either a 2-d (grayscale) or 3-d (2-d + 3 RGB planes) image.
bioformats.load_image_url(url, c=None, z=0, t=0, series=None, index=None, rescale=True, wants_max_intensity=False, channel_names=None)

Load a file from Bio-formats via a URL

Cached image readers

bioformats.get_image_reader(key, path=None, url=None)[source]

Make or find an image reader appropriate for the given path

path - pathname to the reader on disk.

key - use this key to keep only a single cache member associated with
that key open at a time.
bioformats.release_image_reader(key)[source]

Tell the cache that it should flush the reference for the given key

bioformats.clear_image_reader_cache()[source]

Get rid of any open image readers

Metadata

bioformats.get_omexml_metadata(path=None, url=None)[source]

Read the OME metadata from a file using Bio-formats

Parameters:
  • path – path to the file
  • groupfiles – utilize the groupfiles option to take the directory structure into account.
Returns:

the metdata as XML.
class bioformats.OMEXML(xml=None)[source]

Reads and writes OME-XML with methods to get and set it.

The OMEXML class has four main purposes: to parse OME-XML, to output OME-XML, to provide a structured mechanism for inspecting OME-XML and to let the caller create and modify OME-XML.

There are two ways to invoke the constructor. If you supply XML as a string or unicode string, the constructor will parse it and will use it as the base for any inspection and modification. If you don’t supply XML, you’ll get a bland OME-XML object which has a one-channel image. You can modify it programatically and get the modified OME-XML back out by calling to_xml.

There are two ways to get at the XML. The arduous way is to get the root_node of the DOM and explore it yourself using the DOM API (http://docs.python.org/library/xml.dom.html#module-xml.dom). The easy way, where it’s supported is to use properties on OMEXML and on some of its derived objects. For instance:

>>> o = OMEXML()
>>> print o.image().AcquisitionDate

will get you the date that image # 0 was acquired.

>>> o = OMEXML()
>>> o.image().Name = "MyImage"

will set the image name to “MyImage”.

You can add and remove objects using the “count” properties. Each of these handles hooking up and removing orphaned elements for you and should be less error prone than creating orphaned elements and attaching them. For instance, to create a three-color image:

>>> o = OMEXML()
>>> o.image().Pixels.channel_count = 3
>>> o.image().Pixels.Channel(0).Name = "Red"
>>> o.image().Pixels.Channel(1).Name = "Green"
>>> o.image().Pixels.Channel(2).Name = "Blue"

See the OME-XML schema documentation.

image_count Settable.

The number of images (= series) specified by the XML

image(index=0)[source]

Return an image node by index

class Image(node)[source]

Representation of the OME/Image element

Pixels

The OME/Image/Pixels element.

Example: >>> md = bioformats.omexml.OMEXML(xml) >>> pixels = omemetadata.image(i).Pixels >>> channel_count = pixels.SizeC >>> stack_count = pixels.SizeZ >>> timepoint_count = pixels.SizeT

Writing images

bioformats.write_image(pathname, pixels, pixel_type, c=0, z=0, t=0, size_c=1, size_z=1, size_t=1, channel_names=None)[source]

Write the image using bioformats.

Parameters:
  • filename – save to this filename
  • pixels – the image to save
  • pixel_type – save using this pixel type
  • c – the image’s channel index
  • z – the image’s z index
  • t – the image’s t index
  • size_c – # of channels in the stack
  • size_z – # of z stacks
  • size_t – # of timepoints in the stack
  • channel_names – names of the channels (make up names if not present).
bioformats.PT_UINT16 = u'uint16'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

bioformats.PT_UINT8 = u'uint8'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

bioformats.PT_BIT = u'bit'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

OMERO

Python-bioformats can load images from OMERO URLs. To do this, you’ll need to put the JAR files for your OMERO server version onto your Java classpath when you start. For OMERO server 5.0.0, these are blitz.jar, common.jar, ice.jar, ice-glacier2.jar, ice-storm.jar and ice-grid.jar. You’ll also need to use the matching version of the Bio-formats library for the OMERO release instead of the one included with python-bioformats.

bioformats.use_omero_credentials(credentials)[source]

Use the session ID from an existing login as credentials.

Parameters:credentials – credentials from get_omero_credentials.
bioformats.set_omero_credentials(omero_server, omero_port, omero_username, omero_password)[source]

Set the credentials to be used to connect to the Omero server

Parameters:
  • omero_server – DNS name of the server
  • omero_port – use this port to connect to the server
  • omero_username – log on as this user
  • omero_password – log on using this password

The session ID is valid after this function is called. An exception is thrown if the login fails. bioformats.omero_logout() can be called to log out.

bioformats.get_omero_credentials()[source]

Return a pickleable dictionary representing the Omero credentials.

Call bioformats.use_omero_credentials() in some other process to use this.

bioformats.omero_logout()[source]

Abandon any current Omero session.

bioformats.set_omero_login_hook(fn)[source]

Set the function to be called when a login to Omero is needed.

Keys for the credentials dict

bioformats.K_OMERO_SERVER = u'omero_server'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

bioformats.K_OMERO_PORT = u'omero_port'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

bioformats.K_OMERO_USER = u'omero_user'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

bioformats.K_OMERO_SESSION_ID = u'omero_session_id'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

bioformats.K_OMERO_PASSWORD = u'omero_password'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

bioformats.K_OMERO_CONFIG_FILE = u'omero_config_file'

unicode(object=’‘) -> unicode object unicode(string[, encoding[, errors]]) -> unicode object

Create a new Unicode object from the given encoded string. encoding defaults to the current default string encoding. errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

Indices and tables