OME-NGFF (OME-Zarr)#

Convenience#

iohub.open_ome_zarr(store_path: StrOrBytesPath, layout: Literal['auto', 'fov', 'hcs', 'tiled'] = 'auto', mode: Literal['r', 'r+', 'a', 'w', 'w-'] = 'r', channel_names: list[str] = None, axes: list[AxisMeta] = None, version: Literal['0.1', '0.4'] = '0.4', synchronizer: zarr.ThreadSynchronizer | zarr.ProcessSynchronizer = None, **kwargs)[source]#

Convenience method to open OME-Zarr stores.

Parameters:

store_pathStrOrBytesPath

File path to the Zarr store to open

layout: Literal[“auto”, “fov”, “hcs”, “tiled”], optional

NGFF store layout: “auto” will infer layout from existing metadata (cannot be used for creation); “fov” opens a single position/FOV node; “hcs” opens the high-content-screening multi-fov hierarchy; “tiled” opens a “fov” layout with tiled image array (cannot be automatically inferred since this not NGFF-specified); by default “auto”

modeLiteral[“r”, “r+”, “a”, “w”, “w-“], optional

Persistence mode: ‘r’ means read only (must exist); ‘r+’ means read/write (must exist); ‘a’ means read/write (create if doesn’t exist); ‘w’ means create (overwrite if exists); ‘w-’ means create (fail if exists), by default “r”.

channel_nameslist[str], optional

Channel names used to create a new data store, ignored for existing stores, by default None

axeslist[AxisMeta], optional

OME axes metadata, by default None:

[AxisMeta(name='T', type='time', unit='second'),
AxisMeta(name='C', type='channel', unit=None),
AxisMeta(name='Z', type='space', unit='micrometer'),
AxisMeta(name='Y', type='space', unit='micrometer'),
AxisMeta(name='X', type='space', unit='micrometer')]

versionLiteral[“0.1”, “0.4”], optional

OME-NGFF version, by default “0.4”

synchronizerobject, optional

Zarr thread or process synchronizer, by default None

kwargsdict, optional

Keyword arguments to underlying NGFF node constructor, by default None

Returns:

Dataset: NGFF node object (iohub.ngff.Position, iohub.ngff.Plate, or iohub.ngff.TiledPosition)

NGFF Nodes#

class iohub.ngff.NGFFNode(group: Group, parse_meta: bool = True, channel_names: list[str] | None = None, axes: list[AxisMeta] | None = None, version: Literal['0.1', '0.4'] = '0.4', overwriting_creation: bool = False)[source]#

A node (group level in Zarr) in an NGFF dataset.

array_keys()[source]#

Sorted list of keys to all the child zarrays (if any).

Returns:

list[str]

close()[source]#: Close Zarr store.

dump_meta()[source]#: Dumps metadata JSON to the .zattrs file.

get_channel_index(name: str)[source]#

Get the index of a given channel in the channel list.

Parameters:

namestr: Name of the channel.

Returns:

int: Index of the channel.

group_keys()[source]#

Sorted list of keys to all the child zgroups (if any).

Returns:

list[str]

is_leaf()[source]#

Wheter this node is a leaf node, meaning that no child Zarr group is present. Usually a position/fov node for NGFF-HCS if True.

Returns:

bool

is_root()[source]#

Whether this node is the root node

Returns:

bool

print_tree(level: int | None = None)[source]#

Print hierarchy of the node to stdout.

Parameters:

levelint, optional: Maximum depth to show, by default None

property version#: NGFF version

property zattrs#: Zarr attributes of the node. Assignments will modify the metadata file.

property zgroup#: Corresponding Zarr group of the node.

class iohub.ngff.Position(group: Group, parse_meta: bool = True, channel_names: list[str] | None = None, axes: list[AxisMeta] | None = None, version: Literal['0.1', '0.4'] = '0.4', overwriting_creation: bool = False)[source]#

The Zarr group level directly containing multiscale image arrays.

Parameters:

groupzarr.Group: Zarr heirarchy group object
parse_metabool, optional: Whether to parse NGFF metadata in .zattrs, by default True
channel_nameslist[str], optional: List of channel names, by default None
axeslist[AxisMeta], optional: List of axes (ngff_meta.AxisMeta, up to 5D), by default None
overwriting_creationbool, optional: Whether to overwrite or error upon creating an existing child item, by default False

Attributes:

versionLiteral[“0.1”, “0.4”]: NGFF version
zgroupGroup: Corresponding Zarr group of the node.
zattrAttributes: Zarr attributes of the group
channel_nameslist[str]: Name of the channels
axeslist[AxisMeta]: Axes metadata

append_channel(chan_name: str, resize_arrays: bool = True)[source]#

Append a channel to the end of the channel list.

Parameters:

chan_namestr: Name of the new channel
resize_arraysbool, optional: Whether to resize all the image arrays for the new channel, by default True

create_image(name: str, data: ndarray[Any, dtype[_ScalarType_co]], chunks: tuple[int] | None = None, transform: list[TransformationMeta] | None = None, check_shape: bool = True)[source]#

Create a new image array in the position.

Parameters:

namestr: Name key of the new image.
dataNDArray: Image data.
chunkstuple[int], optional: Chunk size, by default None. ZYX stack size will be used if not specified.
transformlist[TransformationMeta], optional: List of coordinate transformations, by default None. Should be specified for a non-native resolution level.
check_shapebool, optional: Whether to check if image shape matches dataset axes, by default True

Returns:

ImageArray: Container object for image stored as a zarr array (up to 5D)

Create a new zero-filled image array in the position. Under default zarr-python settings of lazy writing, this will not write the array values, but only create a .zarray file. This is useful for writing larger-than-RAM images and/or writing from multiprocesses in chunks.

Parameters:

namestr: Name key of the new image.
shapetuple: Image shape.
dtypeDTypeLike: Data type.
chunkstuple[int], optional: Chunk size, by default None. ZYX stack size will be used if not specified.
transformlist[TransformationMeta], optional: List of coordinate transformations, by default None. Should be specified for a non-native resolution level.
check_shapebool, optional: Whether to check if image shape matches dataset axes, by default True

Returns:

ImageArray: Container object for a zero-filled image as a lazy zarr array

property data#

Warning

This property does NOT aim to retrieve all the arrays. And it may also fail to retrive any data if arrays exist but are not named conventionally.

Alias for an array named ‘0’ in the position, which is usually the raw data (or the finest resolution in a pyramid).

Returns:

ImageArray

Raises:

KeyError: If no array is named ‘0’.

Notes

Do not depend on this in non-interactive code! The name is hard-coded and is not guaranteed by the OME-NGFF specification.

dump_meta()[source]#: Dumps metadata JSON to the .zattrs file.

images() → Generator[tuple[str, ImageArray]][source]#

Returns a generator that iterate over the name and value of all the image arrays in the group.

Yields:

tuple[str, ImageArray]: Name and image array object.

initialize_pyramid(levels: int) → None[source]#

Initializes the pyramid arrays with a down scaling of 2 per level. Decimals shapes are rounded up to ceiling. Scales metadata are also updated.

Parameters:

levelsint: Number of down scaling levels, if levels is 1 nothing happens.

rename_channel(old: str, new: str)[source]#

Rename a channel in the channel list.

Parameters:

oldstr: Current name of the channel
newstr: New name of the channel

property scale: list[float]#: Helper function for scale transform metadata of highest resolution scale.

set_transform(image: str | Literal['*'], transform: list[TransformationMeta])[source]#

Set the coordinate transformations metadata for one image array or the whole FOV.

Parameters:

imageUnion[str, Literal[“*”]]: Name of one image array (e.g. “0”) to transform, or “*” for the whole FOV
transformlist[TransformationMeta]: List of transformations to apply (iohub.ngff_meta.TransformationMeta)

Update a channel slice of the target image array with new data.

The incoming data shape needs to be the same as the target array except for the non-existent channel dimension. For example a TCZYX array of shape (2, 3, 4, 1024, 2048) can be updated with data of shape (2, 4, 1024, 2048)

Parameters:

chan_namestr: Channel name
target: str: Name of the image array to update
dataArrayLike: New data array to write

Notes

This method is a syntactical variation of assigning values to the slice with the = operator, and users are encouraged to use array indexing directly.

class iohub.ngff.TiledPosition(group: Group, parse_meta: bool = True, channel_names: list[str] | None = None, axes: list[AxisMeta] | None = None, version: Literal['0.1', '0.4'] = '0.4', overwriting_creation: bool = False)[source]#

Variant of the NGFF position node with convenience methods to create and access tiled arrays. Other parameters and attributes are the same as iohub.ngff.Position.

Make a tiled image array filled with zeros. Chunk size is inferred from tile shape.

Parameters:

namestr: Name of the array.
grid_shapetuple[int, int]: 2-tuple of the tiling grid shape (rows, columns).
tile_shapetuple[int]: Shape of each tile (up to 5D).
dtypeDTypeLike: Data type in NumPy convention
transformlist[TransformationMeta], optional: List of coordinate transformations, by default None. Should be specified for a non-native resolution level.
chunk_dimsint, optional: Non-singleton dimensions of the chunksize, by default 2 (chunk by 2D (y, x) tile size).

Returns:

TiledImageArray

class iohub.ngff.Plate(group: Group, parse_meta: bool = True, channel_names: list[str] | None = None, axes: list[AxisMeta] | None = None, name: str | None = None, acquisitions: list[AcquisitionMeta] | None = None, version: Literal['0.1', '0.4'] = '0.4', overwriting_creation: bool = False)[source]#

create_position(row_name: str, col_name: str, pos_name: str, row_index: int | None = None, col_index: int | None = None, acq_index: int = 0)[source]#

Creates a new position group in the plate. The new position will have empty group metadata, which will not be created until an image is written.

Parameters:

row_namestr: Name key of the row
col_namestr: Name key of the column
row_indexint, optional: Index of the row, will be set by the sequence of creation if not provided, by default None
col_indexint, optional: Index of the column, will be set by the sequence of creation if not provided, by default None
acq_indexint, optional: Index of the acquisition, by default 0

Returns:

Position: Position node object

create_well(row_name: str, col_name: str, row_index: int | None = None, col_index: int | None = None)[source]#

Creates a new well group in the plate. The new well will have empty group metadata, which will not be created until a position is written.

Parameters:

row_namestr: Name key of the row
col_namestr: Name key of the column
row_indexint, optional: Index of the row, will be set by the sequence of creation if not provided, by default None
col_indexint, optional: Index of the column, will be set by the sequence of creation if not provided, by default None

Returns:

Well: Well node object

dump_meta(field_count: bool = False)[source]#

Dumps metadata JSON to the .zattrs file.

Parameters:

field_countbool, optional: Whether to count all the FOV/positions and populate the metadata field ‘plate.field_count’; this operation can be expensive if there are many positions, by default False

classmethod from_positions(store_path: StrOrBytesPath, positions: dict[str, Position]) → Plate[source]#

Create a new HCS store from existing OME-Zarr stores by copying images and metadata from a dictionary of positions.

Parameters:

store_pathStrOrBytesPath: Path of the new store
positionsdict[str, Position]: Dictionary where keys are destination path names (‘row/column/fov’) and values are iohub.ngff.Position objects.

Returns:

Plate: New plate with copied data

Examples

Combine an HCS-layout store and an FOV-layout store:

>>> from iohub.ngff import open_ome_zarr, Plate

>>> with open_ome_zarr("hcs.zarr") as old_plate:
>>>     fovs = dict(old_plate.positions())

>>> with open_ome_zarr("fov.zarr") as old_position:
>>>     fovs["Z/1/0"] = old_position

>>> new_plate = Plate.from_positions("combined.zarr", fovs)

positions() → Generator[tuple[str, Position], None, None][source]#

Returns a generator that iterate over the path and value of all the positions (along rows, columns, and wells) in the plate.

Yields:

[str, Position]: Path and position object.

rows()[source]#

Returns a generator that iterate over the name and value of all the rows in the plate.

Yields:

tuple[str, Row]: Name and row object.

wells()[source]#

Returns a generator that iterate over the path and value of all the wells (along rows, columns) in the plate.

Yields:

[str, Well]: Path and well object.