OME-NGFF (OME-Zarr)¶

Convenience¶

`open_ome_zarr(store_path, layout='auto', mode='r', channel_names=None, axes=None, version='0.4', disable_path_checking=False, **kwargs)` ¶

Convenience method to open OME-Zarr stores.

Parameters:

Name	Type	Description	Default
`store_path`	`str \| Path`	File path to the Zarr store to open	required
`layout`	`Literal['auto', 'fov', 'hcs', 'tiled']`	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"	`'auto'`
`mode`	`Literal['r', 'r+', 'a', 'w', 'w-']`	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".	`'r'`
`channel_names`	`list[str]`	Channel names used to create a new data store, ignored for existing stores, by default None	`None`
`axes`	`list[AxisMeta]`	OME axes metadata, by default None: .. code-block:: text `[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')]`	`None`
`version`	`Literal['0.4', '0.5']`	OME-NGFF version, by default "0.4"	`'0.4'`
`disable_path_checking`	`bool`	Whether to allow overwriting a path that does not contain '.zarr', by default False .. warning:: This can lead to severe data loss if the input path is not checked carefully.	`False`
`kwargs`	`dict`	Keyword arguments to underlying NGFF node constructor, by default None	`{}`

Returns:

Type	Description
`Dataset`	NGFF node object (:py:class:`iohub.ngff.Position`, :py:class:`iohub.ngff.Plate`, or :py:class:`iohub.ngff.TiledPosition`)

NGFF Nodes¶

`NGFFNode` ¶

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

`channel_names` `cached` `property` ¶

Channel names. Subclasses override for lazy resolution.

`axes` `cached` `property` ¶

Axes metadata. Lazily resolves to defaults if not set.

`zgroup` `property` ¶

Corresponding Zarr group of the node.

`zattrs` `property` ¶

Zarr attributes of the node. Assignments will modify the metadata file.

`maybe_wrapped_ome_attrs` `property` ¶

Container of OME metadata attributes.

`version` `property` ¶

NGFF version

`delitem(key)` ¶

.. Warning: this does NOT clean up metadata!

`group_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`array_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`is_root()` ¶

Whether this node is the root node

Returns:

Type	Description
`bool`

`is_leaf()` ¶

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:

Type	Description
`bool`

`print_tree(level=None)` ¶

Print hierarchy of the node to stdout.

Parameters:

Name	Type	Description	Default
`level`	`int`	Maximum depth to show, by default None	`None`

`get_channel_index(name)` ¶

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

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the channel.	required

Returns:

Type	Description
`int`	Index of the channel.

`dump_meta()` ¶

Dumps metadata JSON to the .zattrs file.

`close()` ¶

Close Zarr store.

`Position` ¶

Bases: NGFFNode

The Zarr group level directly containing multiscale image arrays.

Parameters:

Name	Type	Description	Default
`group`	`Group`	Zarr heirarchy group object	required
`parse_meta`	`bool`	Whether to parse NGFF metadata in `.zattrs`, by default True	`True`
`channel_names`	`list[str]`	List of channel names, by default None	`None`
`axes`	`list[AxisMeta]`	List of axes (`ngff_meta.AxisMeta`, up to 5D), by default None	`None`
`overwriting_creation`	`bool`	Whether to overwrite or error upon creating an existing child item, by default False	`False`

Attributes:

Name	Type	Description
`version`	`Literal['0.4', '0.5']`	OME-NGFF specification version
`zgroup`	`Group`	Root Zarr group holding arrays
`zattr`	`Attributes`	Zarr attributes of the group
`channel_names`	`list[str]`	Name of the channels
`axes`	`list[AxisMeta]`	Axes metadata

`channel_names` `cached` `property` ¶

Channel names. Subclasses override for lazy resolution.

`axes` `cached` `property` ¶

Axes metadata. Lazily resolves to defaults if not set.

`zgroup` `property` ¶

Corresponding Zarr group of the node.

`zattrs` `property` ¶

Zarr attributes of the node. Assignments will modify the metadata file.

`maybe_wrapped_ome_attrs` `property` ¶

Container of OME metadata attributes.

`version` `property` ¶

NGFF version

`data` `property` ¶

.. 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:

Type	Description
`ImageArray`

Raises:

Type	Description
`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.

`scale` `property` ¶

Helper function for scale transform metadata of highest resolution scale.

`axis_names` `property` ¶

Helper function for axis names of the highest resolution scale.

Returns lowercase axis names.

`delitem(key)` ¶

.. Warning: this does NOT clean up metadata!

`group_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`array_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`is_root()` ¶

Whether this node is the root node

Returns:

Type	Description
`bool`

`is_leaf()` ¶

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:

Type	Description
`bool`

`print_tree(level=None)` ¶

Print hierarchy of the node to stdout.

Parameters:

Name	Type	Description	Default
`level`	`int`	Maximum depth to show, by default None	`None`

`get_channel_index(name)` ¶

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

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the channel.	required

Returns:

Type	Description
`int`	Index of the channel.

`close()` ¶

Close Zarr store.

`dump_meta()` ¶

Dumps metadata JSON to the .zattrs file.

`getitem(key)` ¶

Get an image array member of the position. E.g. Raw-coordinates image, a multi-scale level, or labels

Parameters:

Name	Type	Description	Default
`key`	`int \| str`	Name or path to the image array. Integer key is converted to string (name).	required

Returns:

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

`setitem(key, value)` ¶

Write an up-to-5D image with default settings.

`images()` ¶

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

Yields:

Type	Description
`tuple[str, ImageArray]`	Name and image array object.

`create_image(name, data, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

Create a new image array in the position.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name key of the new image.	required
`data`	`NDArray`	Image data.	required
`chunks`	`tuple[int, ...]`	Chunk size, by default None. ZYX stack size will be used if not specified.	`None`
`shards_ratio`	`tuple[int, ...]`	Sharding ratio for each dimension, by default None. Each shard contains the product of the ratios number of chunks. No sharding will be used if not specified.	`None`
`transform`	`list[TransformationMeta]`	List of coordinate transformations, by default None. Should be specified for a non-native resolution level.	`None`
`check_shape`	`bool`	Whether to check if image shape matches dataset axes, by default True	`True`

Returns:

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

`create_zeros(name, shape, dtype, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

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:

Name	Type	Description	Default
`name`	`str`	Name key of the new image.	required
`shape`	`tuple[int, ...]`	Image shape.	required
`dtype`	`DTypeLike`	Data type.	required
`chunks`	`tuple[int, ...]`	Chunk size, by default None. ZYX stack size will be used if not specified.	`None`
`shards_ratio`	`tuple[int, ...]`	Sharding ratio for each dimension, by default None. Each shard contains the product of the ratios number of chunks. No sharding will be used if not specified.	`None`
`transform`	`list[TransformationMeta]`	List of coordinate transformations, by default None. Should be specified for a non-native resolution level.	`None`
`check_shape`	`bool`	Whether to check if image shape matches dataset axes, by default True	`True`

Returns:

Type	Description
`ImageArray`	Container object for a zero-filled image as a lazy zarr array

`append_channel(chan_name, resize_arrays=True)` ¶

Append a channel to the end of the channel list.

Parameters:

Name	Type	Description	Default
`chan_name`	`str`	Name of the new channel	required
`resize_arrays`	`bool`	Whether to resize all the image arrays for the new channel, by default True	`True`

`rename_channel(old, new)` ¶

Rename a channel in the channel list.

Parameters:

Name	Type	Description	Default
`old`	`str`	Current name of the channel	required
`new`	`str`	New name of the channel	required

`update_channel(chan_name, target, data)` ¶

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:

Name	Type	Description	Default
`chan_name`	`str`	Channel name	required
`target`	`str`	Name of the image array to update	required
`data`	`ArrayLike`	New data array to write	required

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.

`initialize_pyramid(levels)` ¶

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:

Name	Type	Description	Default
`levels`	`int`	Number of down scaling levels, if levels is 1 nothing happens.	required

`compute_pyramid(levels=None, method='mean')` ¶

Compute pyramid by downsampling from source level.

Creates pyramid structure if none exists. Uses cascade downsampling where each level is derived from the previous level to prevent aliasing artifacts and chunk boundary issues.

Parameters:

Name	Type	Description	Default
`levels`	`int`	Number of pyramid levels. If None, uses existing pyramid structure.	`None`
`method`	`str`	Downsampling method: "mean", "median", "mode", "min", "max", "stride". By default "mean".	`'mean'`

Raises:

Type	Description
`ValueError`	If level 0 array doesn't exist, pyramid structure is invalid, or if a pyramid already exists with a different number of levels.

Examples:

>>> # Create and compute pyramid with 4 levels
>>> pos.compute_pyramid(levels=4, method="mean")

>>> # Recompute existing pyramid structure
>>> pos.compute_pyramid(method="median")

>>> # Change pyramid levels (must delete first)
>>> pos.delete_pyramid()
>>> pos.compute_pyramid(levels=3, method="mean")

`delete_pyramid()` ¶

Delete all dataset pyramid levels except the base (level 0) array.

Use this before calling compute_pyramid() with different levels on a position that already has a pyramid structure.

This method removes both the zarr arrays and updates the OME-NGFF multiscales metadata to reflect the deletion.

`get_axis_index(axis_name)` ¶

Get the index of a given axis.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the axis. Case insensitive.	required

Returns:

Type	Description
`int`	Index of the axis.

`get_effective_scale(image)` ¶

Get the effective coordinate scale metadata for one image array or the whole FOV.

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to query, or "*" for the whole FOV	required

Returns:

Type	Description
`list[float]`	A list of floats representing the total scale for the image or FOV for each axis.

`get_effective_translation(image)` ¶

Get the effective coordinate translation metadata for one image array or the whole FOV.

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to query, or "*" for the whole FOV	required

Returns:

Type	Description
`list[float]`	A list of floats representing the total translation for the image or FOV for each axis.

`set_transform(image, transform)` ¶

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

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to transform, or "*" for the whole FOV	required
`transform`	`list[TransformationMeta]`	List of transformations to apply (:py:class:`iohub.ngff_meta.TransformationMeta`)	required

`set_scale(image, axis_name, new_scale)` ¶

Set the scale for a named axis. Either one image array or the whole FOV.

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to transform, or "*" for the whole FOV	required
`axis_name`	`str`	Name of the axis to set.	required
`new_scale`	`float`	Value of the new scale.	required

`set_contrast_limits(channel_name, window)` ¶

Set the contrast limits for a channel.

Parameters:

Name	Type	Description	Default
`channel_name`	`str`	Name of the channel to set	required
`window`	`WindowDict`	Contrast limit (min, max, start, end)	required

`to_xarray()` ¶

Export full Position data as a labeled xarray.DataArray (tczyx).

The DataArray is backed by a dask array (lazy, no data loaded until .values or .compute() is called).

Coordinate units follow CF conventions: each coordinate carries its own attrs["units"] (e.g. xa.coords["z"].attrs["units"] == "micrometer"). xa.attrs is reserved for value-level metadata (e.g. xa.attrs["units"] = "nanometer" for ret).

Returns:

Type	Description
`DataArray`	5D labeled array with coordinates derived from channel names and physical scales/units.

`write_xarray(data_array, image='0')` ¶

Write an xarray.DataArray into this Position.

Supports writing a subset of channels and/or timepoints. The image array is created on first call; subsequent calls write into the existing array at the correct indices.

Scales, translations, axis units, and DataArray attrs are set from the first write and updated on subsequent writes.

Parameters:

Name	Type	Description	Default
`data_array`	`DataArray`	5D labeled array with tczyx dimensions. The "c" coordinate must be a subset of this Position's channel names. "t" coordinates are mapped to time indices via the scale and translation.	required
`image`	`str`	Name of the image array to write to, by default "0".	`'0'`

`TiledPosition` ¶

Bases: Position

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

`channel_names` `cached` `property` ¶

Channel names. Subclasses override for lazy resolution.

`axes` `cached` `property` ¶

Axes metadata. Lazily resolves to defaults if not set.

`zgroup` `property` ¶

Corresponding Zarr group of the node.

`zattrs` `property` ¶

Zarr attributes of the node. Assignments will modify the metadata file.

`maybe_wrapped_ome_attrs` `property` ¶

Container of OME metadata attributes.

`version` `property` ¶

NGFF version

`data` `property` ¶

.. 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:

Type	Description
`ImageArray`

Raises:

Type	Description
`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.

`scale` `property` ¶

Helper function for scale transform metadata of highest resolution scale.

`axis_names` `property` ¶

Helper function for axis names of the highest resolution scale.

Returns lowercase axis names.

`getitem(key)` ¶

Get an image array member of the position. E.g. Raw-coordinates image, a multi-scale level, or labels

Parameters:

Name	Type	Description	Default
`key`	`int \| str`	Name or path to the image array. Integer key is converted to string (name).	required

Returns:

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

`setitem(key, value)` ¶

Write an up-to-5D image with default settings.

`delitem(key)` ¶

.. Warning: this does NOT clean up metadata!

`group_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`array_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`is_root()` ¶

Whether this node is the root node

Returns:

Type	Description
`bool`

`is_leaf()` ¶

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:

Type	Description
`bool`

`print_tree(level=None)` ¶

Print hierarchy of the node to stdout.

Parameters:

Name	Type	Description	Default
`level`	`int`	Maximum depth to show, by default None	`None`

`get_channel_index(name)` ¶

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

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the channel.	required

Returns:

Type	Description
`int`	Index of the channel.

`dump_meta()` ¶

Dumps metadata JSON to the .zattrs file.

`close()` ¶

Close Zarr store.

`images()` ¶

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

Yields:

Type	Description
`tuple[str, ImageArray]`	Name and image array object.

`create_image(name, data, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

Create a new image array in the position.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name key of the new image.	required
`data`	`NDArray`	Image data.	required
`chunks`	`tuple[int, ...]`	Chunk size, by default None. ZYX stack size will be used if not specified.	`None`
`shards_ratio`	`tuple[int, ...]`	Sharding ratio for each dimension, by default None. Each shard contains the product of the ratios number of chunks. No sharding will be used if not specified.	`None`
`transform`	`list[TransformationMeta]`	List of coordinate transformations, by default None. Should be specified for a non-native resolution level.	`None`
`check_shape`	`bool`	Whether to check if image shape matches dataset axes, by default True	`True`

Returns:

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

`create_zeros(name, shape, dtype, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

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:

Name	Type	Description	Default
`name`	`str`	Name key of the new image.	required
`shape`	`tuple[int, ...]`	Image shape.	required
`dtype`	`DTypeLike`	Data type.	required
`chunks`	`tuple[int, ...]`	Chunk size, by default None. ZYX stack size will be used if not specified.	`None`
`shards_ratio`	`tuple[int, ...]`	Sharding ratio for each dimension, by default None. Each shard contains the product of the ratios number of chunks. No sharding will be used if not specified.	`None`
`transform`	`list[TransformationMeta]`	List of coordinate transformations, by default None. Should be specified for a non-native resolution level.	`None`
`check_shape`	`bool`	Whether to check if image shape matches dataset axes, by default True	`True`

Returns:

Type	Description
`ImageArray`	Container object for a zero-filled image as a lazy zarr array

`append_channel(chan_name, resize_arrays=True)` ¶

Append a channel to the end of the channel list.

Parameters:

Name	Type	Description	Default
`chan_name`	`str`	Name of the new channel	required
`resize_arrays`	`bool`	Whether to resize all the image arrays for the new channel, by default True	`True`

`rename_channel(old, new)` ¶

Rename a channel in the channel list.

Parameters:

Name	Type	Description	Default
`old`	`str`	Current name of the channel	required
`new`	`str`	New name of the channel	required

`update_channel(chan_name, target, data)` ¶

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:

Name	Type	Description	Default
`chan_name`	`str`	Channel name	required
`target`	`str`	Name of the image array to update	required
`data`	`ArrayLike`	New data array to write	required

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.

`initialize_pyramid(levels)` ¶

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:

Name	Type	Description	Default
`levels`	`int`	Number of down scaling levels, if levels is 1 nothing happens.	required

`compute_pyramid(levels=None, method='mean')` ¶

Compute pyramid by downsampling from source level.

Creates pyramid structure if none exists. Uses cascade downsampling where each level is derived from the previous level to prevent aliasing artifacts and chunk boundary issues.

Parameters:

Name	Type	Description	Default
`levels`	`int`	Number of pyramid levels. If None, uses existing pyramid structure.	`None`
`method`	`str`	Downsampling method: "mean", "median", "mode", "min", "max", "stride". By default "mean".	`'mean'`

Raises:

Type	Description
`ValueError`	If level 0 array doesn't exist, pyramid structure is invalid, or if a pyramid already exists with a different number of levels.

Examples:

>>> # Create and compute pyramid with 4 levels
>>> pos.compute_pyramid(levels=4, method="mean")

>>> # Recompute existing pyramid structure
>>> pos.compute_pyramid(method="median")

>>> # Change pyramid levels (must delete first)
>>> pos.delete_pyramid()
>>> pos.compute_pyramid(levels=3, method="mean")

`delete_pyramid()` ¶

Delete all dataset pyramid levels except the base (level 0) array.

Use this before calling compute_pyramid() with different levels on a position that already has a pyramid structure.

This method removes both the zarr arrays and updates the OME-NGFF multiscales metadata to reflect the deletion.

`get_axis_index(axis_name)` ¶

Get the index of a given axis.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the axis. Case insensitive.	required

Returns:

Type	Description
`int`	Index of the axis.

`get_effective_scale(image)` ¶

Get the effective coordinate scale metadata for one image array or the whole FOV.

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to query, or "*" for the whole FOV	required

Returns:

Type	Description
`list[float]`	A list of floats representing the total scale for the image or FOV for each axis.

`get_effective_translation(image)` ¶

Get the effective coordinate translation metadata for one image array or the whole FOV.

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to query, or "*" for the whole FOV	required

Returns:

Type	Description
`list[float]`	A list of floats representing the total translation for the image or FOV for each axis.

`set_transform(image, transform)` ¶

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

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to transform, or "*" for the whole FOV	required
`transform`	`list[TransformationMeta]`	List of transformations to apply (:py:class:`iohub.ngff_meta.TransformationMeta`)	required

`set_scale(image, axis_name, new_scale)` ¶

Set the scale for a named axis. Either one image array or the whole FOV.

Parameters:

Name	Type	Description	Default
`image`	`str \| Literal['*']`	Name of one image array (e.g. "0") to transform, or "*" for the whole FOV	required
`axis_name`	`str`	Name of the axis to set.	required
`new_scale`	`float`	Value of the new scale.	required

`set_contrast_limits(channel_name, window)` ¶

Set the contrast limits for a channel.

Parameters:

Name	Type	Description	Default
`channel_name`	`str`	Name of the channel to set	required
`window`	`WindowDict`	Contrast limit (min, max, start, end)	required

`to_xarray()` ¶

Export full Position data as a labeled xarray.DataArray (tczyx).

The DataArray is backed by a dask array (lazy, no data loaded until .values or .compute() is called).

Coordinate units follow CF conventions: each coordinate carries its own attrs["units"] (e.g. xa.coords["z"].attrs["units"] == "micrometer"). xa.attrs is reserved for value-level metadata (e.g. xa.attrs["units"] = "nanometer" for ret).

Returns:

Type	Description
`DataArray`	5D labeled array with coordinates derived from channel names and physical scales/units.

`write_xarray(data_array, image='0')` ¶

Write an xarray.DataArray into this Position.

Supports writing a subset of channels and/or timepoints. The image array is created on first call; subsequent calls write into the existing array at the correct indices.

Scales, translations, axis units, and DataArray attrs are set from the first write and updated on subsequent writes.

Parameters:

Name	Type	Description	Default
`data_array`	`DataArray`	5D labeled array with tczyx dimensions. The "c" coordinate must be a subset of this Position's channel names. "t" coordinates are mapped to time indices via the scale and translation.	required
`image`	`str`	Name of the image array to write to, by default "0".	`'0'`

`make_tiles(name, grid_shape, tile_shape, dtype, transform=None, chunk_dims=2)` ¶

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

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the array.	required
`grid_shape`	`tuple[int, int]`	2-tuple of the tiling grid shape (rows, columns).	required
`tile_shape`	`tuple[int, ...]`	Shape of each tile (up to 5D).	required
`dtype`	`DTypeLike`	Data type in NumPy convention	required
`transform`	`list[TransformationMeta]`	List of coordinate transformations, by default None. Should be specified for a non-native resolution level.	`None`
`chunk_dims`	`int`	Non-singleton dimensions of the chunksize, by default 2 (chunk by 2D (y, x) tile size).	`2`

Returns:

Type	Description
`TiledImageArray`

`Plate` ¶

Bases: NGFFNode

`zgroup` `property` ¶

Corresponding Zarr group of the node.

`zattrs` `property` ¶

Zarr attributes of the node. Assignments will modify the metadata file.

`maybe_wrapped_ome_attrs` `property` ¶

Container of OME metadata attributes.

`version` `property` ¶

NGFF version

`delitem(key)` ¶

.. Warning: this does NOT clean up metadata!

`group_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`array_keys()` ¶

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

Returns:

Type	Description
`list[str]`

`is_root()` ¶

Whether this node is the root node

Returns:

Type	Description
`bool`

`is_leaf()` ¶

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:

Type	Description
`bool`

`print_tree(level=None)` ¶

Print hierarchy of the node to stdout.

Parameters:

Name	Type	Description	Default
`level`	`int`	Maximum depth to show, by default None	`None`

`get_channel_index(name)` ¶

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

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the channel.	required

Returns:

Type	Description
`int`	Index of the channel.

`close()` ¶

Close Zarr store.

`from_positions(store_path, positions)` `classmethod` ¶

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

.. warning: This assumes same channel names and axes across the FOVs and does not check for consistent shape and chunk size.

Parameters:

Name	Type	Description	Default
`store_path`	`str \| Path`	Path of the new store	required
`positions`	`dict[str, Position]`	Dictionary where keys are destination path names ('row/column/fov') and values are :py:class:`iohub.ngff.Position` objects.	required

Returns:

Type	Description
`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)

`dump_meta(field_count=False)` ¶

Dumps metadata JSON to the .zattrs file.

Parameters:

Name	Type	Description	Default
`field_count`	`bool`	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	`False`

`create_well(row_name, col_name, row_index=None, col_index=None)` ¶

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:

Name	Type	Description	Default
`row_name`	`str`	Name key of the row	required
`col_name`	`str`	Name key of the column	required
`row_index`	`int`	Index of the row, will be set by the sequence of creation if not provided, by default None	`None`
`col_index`	`int`	Index of the column, will be set by the sequence of creation if not provided, by default None	`None`

Returns:

Type	Description
`Well`	Well node object

`create_positions(positions)` ¶

Creates multiple position groups in the plate efficiently.

This is a vectorized version of :py:meth:create_position that creates multiple positions in a single call. Wells are created as needed and metadata is written in batches for better performance.

Parameters:

Name	Type	Description	Default
`positions`	`list[PositionSpec]`	List of position specifications. Each tuple can have 3-6 elements: 3 elements: `(row_name, col_name, pos_name)` 4 elements: `(row_name, col_name, pos_name, row_index)` 5 elements: `(row_name, col_name, pos_name, row_index, col_index)` 6 elements: `(row_name, col_name, pos_name, row_index, col_index, acq_index)` Where: row_name (str): Name key of the row col_name (str): Name key of the column pos_name (str): Name key of the position row_index (int \| None): Index of the row (auto-assigned if None or omitted) col_index (int \| None): Index of the column (auto-assigned if None or omitted) acq_index (int): Index of the acquisition (defaults to 0 if omitted)	required

Returns:

Type	Description
`list[Position]`	List of created Position node objects

`create_position(row_name, col_name, pos_name, row_index=None, col_index=None, acq_index=0)` ¶

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:

Name	Type	Description	Default
`row_name`	`str`	Name key of the row	required
`col_name`	`str`	Name key of the column	required
`row_index`	`int`	Index of the row, will be set by the sequence of creation if not provided, by default None	`None`
`col_index`	`int`	Index of the column, will be set by the sequence of creation if not provided, by default None	`None`
`acq_index`	`int`	Index of the acquisition, by default 0	`0`

Returns:

Type	Description
`Position`	Position node object

`rows()` ¶

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

Yields:

Type	Description
`tuple[str, Row]`	Name and row object.

`wells()` ¶

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

Yields:

Type	Description
`[str, Well]`	Path and well object.

`positions()` ¶

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

Yields:

Type	Description
`[str, Position]`	Path and position object.

`rename_well(old, new)` ¶

Rename a well.

Parameters:

Name	Type	Description	Default
`old`	`str`	Old name of well, e.g. "A/1"	required
`new`	`str`	New name of well, e.g. "B/2"	required

`ImageArray` ¶

Bases: Array

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

`numpy()` ¶

Return the whole image as an in-RAM NumPy array. self.numpy() is equivalent to self[:].

`dask_array()` ¶

Return as a dask array

`tensorstore(**kwargs)` ¶

Open the zarr array as a TensorStore object. Needs the optional dependency tensorstore.

Parameters:

Name	Type	Description	Default
`**kwargs`	`dict`	Additional keyword arguments to pass to `tensorstore.open()`, by default None	`{}`

Returns:

Type	Description
`TensorStore`	Handle to the Zarr array.

OME-NGFF (OME-Zarr)¶

Convenience¶

open_ome_zarr(store_path, layout='auto', mode='r', channel_names=None, axes=None, version='0.4', disable_path_checking=False, **kwargs) ¶

NGFF Nodes¶

NGFFNode ¶

channel_names cached property ¶

axes cached property ¶

zgroup property ¶

zattrs property ¶

maybe_wrapped_ome_attrs property ¶

version property ¶

__delitem__(key) ¶

group_keys() ¶

array_keys() ¶

is_root() ¶

is_leaf() ¶

print_tree(level=None) ¶

get_channel_index(name) ¶

dump_meta() ¶

close() ¶

Position ¶

channel_names cached property ¶

axes cached property ¶

zgroup property ¶

zattrs property ¶

maybe_wrapped_ome_attrs property ¶

version property ¶

data property ¶

scale property ¶

axis_names property ¶

__delitem__(key) ¶

group_keys() ¶

array_keys() ¶

is_root() ¶

is_leaf() ¶

print_tree(level=None) ¶

get_channel_index(name) ¶

close() ¶

dump_meta() ¶

__getitem__(key) ¶

__setitem__(key, value) ¶

images() ¶

create_image(name, data, chunks=None, shards_ratio=None, transform=None, check_shape=True) ¶

create_zeros(name, shape, dtype, chunks=None, shards_ratio=None, transform=None, check_shape=True) ¶

append_channel(chan_name, resize_arrays=True) ¶

rename_channel(old, new) ¶

update_channel(chan_name, target, data) ¶

initialize_pyramid(levels) ¶

compute_pyramid(levels=None, method='mean') ¶

delete_pyramid() ¶

get_axis_index(axis_name) ¶

get_effective_scale(image) ¶

get_effective_translation(image) ¶

set_transform(image, transform) ¶

set_scale(image, axis_name, new_scale) ¶

set_contrast_limits(channel_name, window) ¶

to_xarray() ¶

write_xarray(data_array, image='0') ¶

TiledPosition ¶

channel_names cached property ¶

axes cached property ¶

zgroup property ¶

zattrs property ¶

maybe_wrapped_ome_attrs property ¶

version property ¶

data property ¶

scale property ¶

axis_names property ¶

__getitem__(key) ¶

__setitem__(key, value) ¶

__delitem__(key) ¶

group_keys() ¶

array_keys() ¶

is_root() ¶

is_leaf() ¶

print_tree(level=None) ¶

get_channel_index(name) ¶

dump_meta() ¶

close() ¶

images() ¶

`open_ome_zarr(store_path, layout='auto', mode='r', channel_names=None, axes=None, version='0.4', disable_path_checking=False, **kwargs)` ¶

`NGFFNode` ¶

`channel_names` `cached` `property` ¶

`axes` `cached` `property` ¶

`zgroup` `property` ¶

`zattrs` `property` ¶

`maybe_wrapped_ome_attrs` `property` ¶

`version` `property` ¶

`delitem(key)` ¶

`group_keys()` ¶

`array_keys()` ¶

`is_root()` ¶

`is_leaf()` ¶

`print_tree(level=None)` ¶

`get_channel_index(name)` ¶

`dump_meta()` ¶

`close()` ¶

`Position` ¶

`channel_names` `cached` `property` ¶

`axes` `cached` `property` ¶

`zgroup` `property` ¶

`zattrs` `property` ¶

`maybe_wrapped_ome_attrs` `property` ¶

`version` `property` ¶

`data` `property` ¶

`scale` `property` ¶

`axis_names` `property` ¶

`delitem(key)` ¶

`group_keys()` ¶

`array_keys()` ¶

`is_root()` ¶

`is_leaf()` ¶

`print_tree(level=None)` ¶

`get_channel_index(name)` ¶

`close()` ¶

`dump_meta()` ¶

`getitem(key)` ¶

`setitem(key, value)` ¶

`images()` ¶

`create_image(name, data, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

`create_zeros(name, shape, dtype, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

`append_channel(chan_name, resize_arrays=True)` ¶

`rename_channel(old, new)` ¶

`update_channel(chan_name, target, data)` ¶

`initialize_pyramid(levels)` ¶

`compute_pyramid(levels=None, method='mean')` ¶

`delete_pyramid()` ¶

`get_axis_index(axis_name)` ¶

`get_effective_scale(image)` ¶

`get_effective_translation(image)` ¶

`set_transform(image, transform)` ¶

`set_scale(image, axis_name, new_scale)` ¶

`set_contrast_limits(channel_name, window)` ¶

`to_xarray()` ¶

`write_xarray(data_array, image='0')` ¶

`TiledPosition` ¶

`channel_names` `cached` `property` ¶

`axes` `cached` `property` ¶

`zgroup` `property` ¶

`zattrs` `property` ¶

`maybe_wrapped_ome_attrs` `property` ¶

`version` `property` ¶

`data` `property` ¶

`scale` `property` ¶

`axis_names` `property` ¶

`getitem(key)` ¶

`setitem(key, value)` ¶

`delitem(key)` ¶

`group_keys()` ¶

`array_keys()` ¶

`is_root()` ¶

`is_leaf()` ¶

`print_tree(level=None)` ¶

`get_channel_index(name)` ¶

`dump_meta()` ¶

`close()` ¶

`images()` ¶

`create_image(name, data, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

`create_zeros(name, shape, dtype, chunks=None, shards_ratio=None, transform=None, check_shape=True)` ¶

`append_channel(chan_name, resize_arrays=True)` ¶