iohub

Status
Package
Meta
Cite

N-dimensional bioimaging produces data and metadata in various formats, and iohub aims to become a unified Python interface to the most common formats used at the Biohub and in the broader imaging community.

Project status: Active development. iohub is alpha software, and its APIs and file-format support may change between releases.

Supported formats

Read

• OME-Zarr (OME-NGFF v0.5, OME-NGFF v0.4)
• Micro-Manager TIFF sequence, OME-TIFF (MMStack), and NDTiff datasets
• Nikon ND2 (via nd2)
• Custom data formats generated by Biohub microscopes
  • Supported: Falcon (PTI), Dorado (ClearControl), Dragonfly (OpenCell OME-TIFF), Mantis (NDTiff), Osprey (ND2)
  • WIP: DaXi

Write

• OME-Zarr (OME-NGFF v0.5)

Quick start

Installation

Install iohub from PyPI:

pip install iohub

With optional TensorStore support:

pip install "iohub[tensorstore]"

Or install the latest development version:

pip install git+https://github.com/czbiohub-sf/iohub.git

For development setup, see the contributing guide.

Command-line interface

To check if iohub works for a dataset:

iohub info /path/to/data/

The CLI can show a summary of the dataset, point to relevant Python calls, and convert other data formats to the latest OME-Zarr. See the full CLI help message by typing iohub or iohub [command] --help in the terminal.

Working with OME-Zarr

Load and modify an example OME-Zarr dataset:

import numpy as np
from iohub import open_ome_zarr

with open_ome_zarr(
    "20200812-CardiomyocyteDifferentiation14-Cycle1.zarr",
    mode="r",
    layout="auto",
) as dataset:
    dataset.print_tree()  # prints the hierarchy of the zarr store
    channel_names = dataset.channel_names
    print(channel_names)
    img_array = dataset[
        "B/03/0/0"
    ]  # lazy Zarr array for the raw image in the first position
    raw_data = img_array.numpy()  # loads a CZYX 4D array into RAM
    print(raw_data.mean())  # does some analysis

with open_ome_zarr(
    "max_intensity_projection.zarr",
    mode="w-",
    layout="hcs",
    channel_names=channel_names,
) as dataset:
    new_fov = dataset.create_position(
        "B", "03", "0"
    )  # creates fov with the same path
    new_fov["0"] = raw_data.max(axis=1).reshape(
        (1, 1, 1, *raw_data.shape[2:])
    )  # max projection along Z axis and prepend dims to 5D
    dataset.print_tree()  # checks that new data has been written

For more about API usage, refer to the documentation and the example scripts.

Reading Micro-Manager TIFF data

Read a directory containing a TIFF dataset:

from iohub import read_images

reader = read_images("/path/to/data/")
print(reader)

Why iohub?

This project is inspired by the existing Python libraries for bioimaging data I/O, including ome-zarr-py, tifffile and aicsimageio. They support some of the most widely adopted and/or promising formats in microscopy, such as OME-Zarr and OME-TIFF.

iohub bridges the gaps among them with the following features:

• Efficient reading of data in various TIFF-based formats produced by the Micro-Manager/Pycro-Manager acquisition stack.
• Efficient and customizable conversion of data and metadata from TIFF to OME-Zarr.
• Pythonic and atomic access of OME-Zarr data with parallelized analysis in mind.
• OME-Zarr metadata is automatically constructed and updated for writing, and verified against the specification when reading.
• Adherence to the latest OME-NGFF specification (v0.5) whenever possible.

Community

Read the contributing guide before proposing a change. Participation in iohub is governed by the Contributor Covenant Code of Conduct.

Security

Do not report security vulnerabilities in public issues. Follow our security policy to report them privately.