abczarr.ome.base

The version-independent OME-Zarr metadata model.

OME-Zarr, the NGFF specification, is a metadata convention for bioimaging data stored in Zarr. It describes multiscale image pyramids, high-content screening plates, segmentation labels, and rendering settings, all as JSON attached to a Zarr group. abczarr models that metadata as typed classes under abczarr.ome. One package exists per NGFF version, v0_1 through v0_5, plus the 0.6 pre-release previews v0_6dev1 through v0_6dev4 and v0_6rc0.

The examples below target 0.5, the latest stable version. The Reference documents every version.

Describing a multiscale image

A multiscale image is a pyramid of resolution levels, each a Zarr array, described by Multiscale. It is built from a plain dict shaped like the JSON the spec defines:

>>> from abczarr.ome import v0_5
>>> multiscale = v0_5.Multiscale.from_json({
...     "name": "nucleus-stain",
...     "type": "gaussian",
...     "axes": [
...         {"name": "c", "type": "channel"},
...         {"name": "y", "type": "space", "unit": "micrometer"},
...         {"name": "x", "type": "space", "unit": "micrometer"},
...     ],
...     "datasets": [
...         {
...             "path": "0",
...             "coordinateTransformations": [
...                 {"type": "scale", "scale": [1.0, 0.325, 0.325]}
...             ],
...         },
...         {
...             "path": "1",
...             "coordinateTransformations": [
...                 {"type": "scale", "scale": [1.0, 0.65, 0.65]}
...             ],
...         },
...     ],
... })
>>> [axis.name for axis in multiscale.axes]
['c', 'y', 'x']
>>> [dataset.path for dataset in multiscale.datasets]
['0', '1']

Each axis in axes becomes an Axis, matched by its type field. The y and x axes in this example become SpaceAxis objects, since each carries type="space". Each entry in datasets becomes a Dataset. A dataset names an array and carries the Scale that places it in physical space, one value per axis, in that axis's unit.

A Multiscale describes the pyramid, not the whole group. Wrapping it in OMEImage produces the metadata an image group actually carries, optionally alongside Omero rendering settings:

from abczarr.ome import v0_5

image = v0_5.OMEImage(
    version="0.5",
    multiscales=[multiscale],
    omero=v0_5.Omero.from_json({
        "channels": [
            {
                "color": "00FF00",
                "window": {"start": 0, "end": 1500, "min": 0, "max": 65535},
            },
        ],
    }),
)

The same shape covers the other kinds of OME-Zarr group: ImageLabel for a segmentation, and Plate / Well for a high-content screen, wrapped in OMEImageLabel, OMEPlate and OMEWell.

Reading and writing OME metadata on a group

OME-Zarr metadata lives in a group's user attributes, the same attrs mapping any Zarr group exposes. NGFF 0.5 nests it all under one "ome" key, so an object round-trips through to_json and from_json like this:

group.attrs["ome"] = image.to_json()

loaded = v0_5.OMEImage.from_json(group.attrs["ome"])
loaded.multiscales[0].axes[0].name  # "c"

Earlier NGFF versions, 0.4 and before, write the same fields directly at the top level of attrs instead of nesting them under "ome": group.attrs.update(image.to_json()).

Converting between NGFF versions

OMEMetadata.to_version converts a piece of OME metadata, built against one NGFF version, to another. It works on the top-level container and on any nested piece of metadata alike:

>>> from abczarr.ome import v0_4
>>> old = v0_4.Multiscale.from_json({
...     "version": "0.4",
...     "axes": [
...         {"name": "y", "type": "space"},
...         {"name": "x", "type": "space"},
...     ],
...     "datasets": [
...         {
...             "path": "0",
...             "coordinateTransformations": [
...                 {"type": "scale", "scale": [1.0, 1.0]}
...             ],
...         }
...     ],
... })
>>> new = old.to_version("0.5")
>>> type(new).__module__
'abczarr.ome.v0_5.images'
>>> new.to_version("0.4") == old
True

Fields both versions share carry over unchanged. Converting forward, a field only the newer version has gets a reasonable default. Axes, for example, gained a type field in NGFF 0.4, defaulted from the axis's name. Converting back, that field is dropped. Converting to a version that would need information the source does not carry raises ValueError rather than guessing.

>>> from abczarr.ome import v0_2
>>> untyped = v0_2.Multiscale.from_json({
...     "version": "0.2",
...     "name": "x",
...     "datasets": [{"path": "0"}],
... })
>>> untyped.to_version("0.3")
Traceback (most recent call last):
    ...
ValueError: cannot convert Multiscale from OME 0.2 to 0.3:
the target requires information OME 0.2 does not carry

OMEMetadata(*, extra_items: Iterable[tuple[str | bytes, Real | floating | bool | bool | int | str | bytes | Iterable[()] | None]] | Mapping[str | bytes, Real | floating | bool | bool | int | str | bytes | Iterable[()] | None] = FrozenDict({}))

to_version(version: str, policy: ConversionPolicy = 'warn') -> Self

OME(version: str | bytes = '', *, extra_items: Iterable[tuple[str | bytes, Real | floating | bool | bool | int | str | bytes | Iterable[()] | None]] | Mapping[str | bytes, Real | floating | bool | bool | int | str | bytes | Iterable[()] | None] = FrozenDict({}))

version: str = field(factory=False)

from_json(data: Any) -> Self