Skip to content

OME-Zarr metadata — NGFF 0.3

Changes from NGFF 0.2

  • Multiscale gains a required axes field. A pyramid's dimensions are now listed explicitly and in order, instead of being left implicit in the array shape. The axis names are still bare string literals (x, y, z, t, c); typed axis objects arrive in 0.4.
  • version is promoted from recommended to required on every carrier that records it: Multiscale, ImageLabel, Omero, Plate and Well.

abczarr.ome.v0_3.ome

abczarr.ome.v0_3.ome

The top-level metadata attached to an OME-Zarr group.

OME and its subclasses each describe what kind of group carries them, an image, a plate, a well, a collection of labels, and so on.

Classes

OME 

OME(*, 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: Literal['0.3'] = '0.3')

Bases: OME

OME-Zarr metadata attached to a Zarr group.

An image, a plate, a well, and a set of labels are each represented by a different subclass that adds the fields for what it holds. See OMEImage, OMEPlate, and OMEWell for examples.

Attributes
version class-attribute instance-attribute 
version: Required[Version] = field(kw_only=True)

The OME-NGFF version the metadata is written against.

Methods:

OMESeries 

OMESeries(series: Iterable[str | bytes] | None = None, *, 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: Literal['0.3'] = '0.3')

Bases: OME

Metadata for a bioformats2raw dataset's set of image series.

Attributes
series class-attribute instance-attribute 
series: list[str] | None = None

The path of each series' subgroup, in the same order as the corresponding series in the accompanying OME-XML document. Optional.

Methods:

OMEImage 

OMEImage(multiscales: Iterable[Multiscale | JsonDict | list[Literal['x', 'y', 'z'] | Literal['t'] | Literal['c']]], omero: Omero | JsonDict | list[Channel] = MISSING, *, 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: Literal['0.3'] = '0.3')

Bases: OME

Metadata for an image group.

The group holds one or more multiscale pyramids and, optionally, settings for how the image should be rendered.

Attributes
multiscales instance-attribute 
multiscales: Required[list[Multiscale]]

The group's resolution pyramids, each a Multiscale object. An image almost always has exactly one.

omero instance-attribute 
omero: Optional[Omero]

Rendering settings suggesting how a viewer should display the image's channels. See Omero for the fields it carries. Optional.

Methods:

OMEImageLabel 

OMEImageLabel(multiscales: Iterable[Multiscale | JsonDict | list[Literal['x', 'y', 'z'] | Literal['t'] | Literal['c']]], omero: Omero | JsonDict | list[Channel] = MISSING, image_label: ImageLabel | JsonDict | list[Color], *, 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: Literal['0.3'] = '0.3')

Bases: OMEImage

Metadata for a label image.

A label image is an OMEImage whose pixel values name segments.

Attributes
image_label class-attribute instance-attribute 
image_label: Required[ImageLabel] = field(json='image-label')

The ImageLabel metadata describing those segments, including their display colors and any per-label properties.

Methods:

OMELabels 

OMELabels(labels: Iterable[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: Literal['0.3'] = '0.3')

Bases: OME

Metadata for a group that collects a set of label images.

Attributes
labels instance-attribute 
labels: Required[list[str]]

The path of each subgroup that holds a label image. Each such subgroup is in turn represented by an OMEImageLabel object.

Methods:

OMEPlate 

OMEPlate(plate: Plate | JsonDict | list[Acquisition], *, 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: Literal['0.3'] = '0.3')

Bases: OME

Metadata for a high-content screening plate group.

Attributes
plate instance-attribute 
plate: Required[Plate]

The Plate metadata describing the plate's rows, columns, wells, and imaging runs.

Methods:

OMEWell 

OMEWell(well: Well | JsonDict | list[Image], *, 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: Literal['0.3'] = '0.3')

Bases: OME

Metadata for a well group.

A well group holds the images captured at one position of a plate.

Attributes
well instance-attribute 
well: Required[Well]

The Well metadata describing the group's fields of view. For each field of view, that metadata also names the acquisition run it belongs to.

Methods:

OMEBioformats2Raw 

OMEBioformats2Raw(bioformats2raw_layout: Literal[3] = 3, plate: Plate | JsonDict | list[Acquisition], *, 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: Literal['0.3'] = '0.3')

Bases: OME

Metadata for the root group of a bioformats2raw-converted dataset.

Attributes
bioformats2raw_layout class-attribute instance-attribute 
bioformats2raw_layout: Required[Literal[3]] = field(json='bioformats2raw.layout')

Marks the group as following the bioformats2raw layout. Its value is always 3.

plate instance-attribute 
plate: Required[Plate]

The Plate metadata, present when the converted dataset describes a screening plate. This field is optional in OME-NGFF 0.1, and required from 0.2 on.

Methods:

abczarr.ome.v0_3.images

abczarr.ome.v0_3.images

The multiscale image pyramid.

Multiscale describes a pyramid of progressively downsampled resolution levels. Each level is a Dataset, naming a Zarr array and how it is positioned relative to the others.

Classes

Dataset 

Dataset(path: 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({}))

Bases: OMEMetadata

One resolution level of a multiscale pyramid.

Attributes
path class-attribute instance-attribute 
path: Required[str] = field(factory=False)

The name of the Zarr array holding this level, relative to the image group.

Methods:

Multiscale 

Multiscale(axes: Iterable[Literal['x', 'y', 'z'] | Literal['t'] | Literal['c']], datasets: Iterable[Dataset | JsonDict | str], name: str | bytes = MISSING, type: str | bytes = MISSING, metadata: Metadata | JsonDict | str = MISSING, version: Literal['0.3'] = '0.3', *, 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({}))

Bases: OMEMetadata

A multiscale image pyramid: its axes and resolution levels.

Attributes
axes instance-attribute 
axes: Required[list[Axis]]

The pyramid's dimensions, named and ordered as t, c, z, y, x, in whatever subset and order the image uses.

datasets instance-attribute 
datasets: Required[list[Dataset]]

The pyramid's resolution levels, from full resolution down. Each entry is a Dataset.

name instance-attribute 
name: Recommended[str]

A name for the multiscale image. Recommended.

type instance-attribute 
type: Recommended[str]

The method used to generate the lower resolutions, such as "gaussian". Recommended.

metadata instance-attribute 
metadata: Recommended[Metadata]

Further, free-form detail about how the lower resolutions were generated. Recommended.

version instance-attribute 
version: Required[Version]

The OME-NGFF version the metadata is written against.

Classes
Metadata 
Metadata(method: str | bytes = MISSING, version: str | bytes = MISSING, args: Any = MISSING, kwargs: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = MISSING, *, 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({}))

Bases: OMEMetadata

Free-form detail about how a pyramid's lower resolutions were generated.

Attributes
method instance-attribute 
method: Optional[str]

The name of the downsampling function. Optional.

version instance-attribute 
version: Optional[str]

The version of the software that ran method. Optional.

args instance-attribute 
args: Optional[Json]

The positional arguments method was called with. The upstream corpus writes this as a bare string as well as a list, so it is read as any JSON value rather than coerced into a list. Optional.

kwargs instance-attribute 
kwargs: Optional[dict[str, Json]]

The keyword arguments method was called with. Optional.

Methods:
Methods:

abczarr.ome.v0_3.plates

abczarr.ome.v0_3.plates

A high-content screening plate: its rows, columns, wells, and acquisitions.

Classes

Plate 

Plate(acquisitions: Iterable[Acquisition | JsonDict | int] = MISSING, columns: Iterable[Column | JsonDict | str], field_count: Integral | integer | bool = MISSING, name: str | bytes = MISSING, rows: Iterable[Row | JsonDict | str], wells: Iterable[Well | JsonDict | str], version: Literal['0.3'] = '0.3', *, 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({}))

Bases: OMEMetadata

A high-content screening plate.

rows and columns name the plate's grid, such as "A", "B", and so on for rows, and "1", "2", and so on for columns.

Attributes
acquisitions instance-attribute 
acquisitions: Optional[list[Acquisition]]

The imaging runs the wells' images belong to, when the screen ran more than one. Optional.

columns instance-attribute 
columns: Required[list[Column]]

The plate's columns, in grid order.

field_count instance-attribute 
field_count: Recommended[NonNegativeInt]

The largest number of fields of view acquired for any well of the plate. Recommended.

name instance-attribute 
name: Recommended[str]

A name for the plate. Recommended.

rows instance-attribute 
rows: Required[list[Row]]

The plate's rows, in grid order.

wells instance-attribute 
wells: Required[list[Well]]

Every well of the plate, each placed in the grid and pointing at the group holding its images.

version instance-attribute 
version: Required[Version]

The OME-NGFF version the metadata is written against. Recommended in OME-NGFF 0.1 and 0.2, and required from 0.3 on.

Classes
Acquisition 
Acquisition(id: Integral | integer | bool, name: str | bytes = MISSING, maximumfieldcount: Integral | integer | bool = MISSING, description: str | bytes = MISSING, starttime: Integral | integer | bool = MISSING, endtime: Integral | integer | bool = MISSING, *, 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({}))

Bases: OMEMetadata

One imaging run over some or all of the plate's wells.

Attributes
id class-attribute instance-attribute 
id: Required[NonNegativeInt] = field(factory=False)

A non-negative integer identifying the acquisition. A Well.Image refers to this run by this value.

name instance-attribute 
name: Recommended[str]

A name for the acquisition. Recommended.

maximumfieldcount instance-attribute 
maximumfieldcount: Recommended[NonNegativeInt]

The largest number of fields of view acquired for any well in this run. Recommended.

description instance-attribute 
description: Optional[str]

A description of the acquisition. Optional.

starttime instance-attribute 
starttime: Optional[int]

The time the acquisition started, in Unix epoch milliseconds. Optional.

endtime instance-attribute 
endtime: Optional[int]

The time the acquisition ended, in Unix epoch milliseconds. Optional.

Methods:
Column 
Column(name: 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({}))

Bases: OMEMetadata

One column of the plate's grid, named as it is labeled.

Attributes
name class-attribute instance-attribute 
name: Required[AlphaNumeric] = field(factory=False)

The column's label, made of letters and digits only.

Methods:
Row 
Row(name: 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({}))

Bases: OMEMetadata

One row of the plate's grid, named as it is labeled.

Attributes
name class-attribute instance-attribute 
name: Required[AlphaNumeric] = field(factory=False)

The row's label, made of letters and digits only.

Methods:
Well 
Well(path: str | bytes, rowIndex: Integral | integer | bool, columnIndex: Integral | integer | bool, *, 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({}))

Bases: OMEMetadata

One well's position in the plate, and the group holding it.

Attributes
path class-attribute instance-attribute 
path: Required[WellPath] = field(factory=False)

The well's group, relative to the plate group, spelled as "<row>/<column>".

rowIndex instance-attribute 
rowIndex: Required[NonNegativeInt]

The well's row, as an index into Plate.rows.

columnIndex instance-attribute 
columnIndex: Required[NonNegativeInt]

The well's column, as an index into Plate.columns.

Methods:
Methods:

abczarr.ome.v0_3.wells

abczarr.ome.v0_3.wells

A well: the images acquired at one position of a screening plate.

Classes

Well 

Well(images: Iterable[Image | JsonDict | str], version: Literal['0.3'] = '0.3', *, 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({}))

Bases: OMEMetadata

A well's images: one field of view per acquisition run.

A well group holds one subgroup per field of view.

Attributes
images instance-attribute 
images: Required[list[Image]]

The well's fields of view, each naming its subgroup and, when the plate ran more than one acquisition, which acquisition it belongs to.

version instance-attribute 
version: Required[Version]

The OME-NGFF version the metadata is written against. Recommended in OME-NGFF 0.1 and 0.2, and required from 0.3 on.

Classes
Image 
Image(path: str | bytes, acquisition: Integral | integer | bool = MISSING, *, 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({}))

Bases: OMEMetadata

One field of view within a well.

Attributes
path class-attribute instance-attribute 
path: Required[str] = field(factory=False)

The image's group, relative to the well group.

acquisition instance-attribute 
acquisition: Recommended[int]

The id of the Plate.Acquisition this field of view was captured in, when the plate ran more than one. Recommended.

Methods:
Methods:

abczarr.ome.v0_3.labels

abczarr.ome.v0_3.labels

A segmentation label image: display colors and per-label properties.

Classes

ImageLabel 

ImageLabel(colors: Iterable[Color | JsonDict | int] = MISSING, properties: Iterable[Property | JsonDict | int] = MISSING, source: Source | JsonDict | str = MISSING, version: Literal['0.3'] = '0.3', *, 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({}))

Bases: OMEMetadata

Metadata for a label image: an array whose integer values name segments.

Attach one of these to a label image group alongside its own Multiscale.

Attributes
colors instance-attribute 
colors: Recommended[list[Color]]

The display color for each labeled integer value. Recommended.

properties instance-attribute 
properties: Optional[list[Property]]

Further, application-defined attributes for each labeled value. Optional.

source instance-attribute 
source: Optional[Source]

Where the label image was derived from. Optional.

version instance-attribute 
version: Required[Version]

The OME-NGFF version the metadata is written against. Recommended in OME-NGFF 0.1 and 0.2, and required from 0.3 on.

Classes
Color 
Color(label_value: Integral | integer | bool, rgba: tuple[Integral | integer | bool, Integral | integer | bool, Integral | integer | bool, Integral | integer | bool] = MISSING, *, 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({}))

Bases: OMEMetadata

The display color for one label value.

Attributes
label_value class-attribute instance-attribute 
label_value: Required[int] = field(json='label-value')

The integer value this color applies to.

rgba instance-attribute 
rgba: Optional[tuple[UInt8, UInt8, UInt8, UInt8]]

The color as red, green, blue, and alpha components, each from 0 to 255. Optional.

Methods:
Property 
Property(label_value: Integral | integer | bool, *, 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({}))

Bases: OMEMetadata

Extra, application-defined attributes for one label value.

Any key beyond label_value is carried through as extra data. See OMEMetadata.

Attributes
label_value class-attribute instance-attribute 
label_value: Required[int] = field(json='label-value')

The integer value these properties apply to.

Methods:
Source 
Source(image: str | bytes = None, *, 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({}))

Bases: OMEMetadata

Where a label image was derived from.

Attributes
image class-attribute instance-attribute 
image: Optional[str] = None

The path of the intensity image this label was derived from, relative to the label image group. Optional.

Methods:
Methods:

abczarr.ome.v0_3.omero

abczarr.ome.v0_3.omero

Rendering settings: how to display an image's channels.

Classes

Channel 

Channel(color: str | bytes, window: Window | JsonDict | float, *, 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({}))

Bases: OMEMetadata

How to render one channel of a multi-channel image.

Attributes
color instance-attribute 
color: Required[str]

The channel's display color, as a hex RGB string such as "FF0000" for red.

window instance-attribute 
window: Required[Window]

The intensity range mapped onto that color.

Classes
Window 
Window(min: Real | floating | bool, max: Real | floating | bool, start: Real | floating | bool, end: Real | floating | bool, *, 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({}))

Bases: OMEMetadata

The intensity range a channel's color is mapped over.

Attributes
min instance-attribute 
min: Required[float]

The lowest value the channel's data can take.

max instance-attribute 
max: Required[float]

The highest value the channel's data can take.

start instance-attribute 
start: Required[float]

The value a viewer should render at zero intensity. This may narrow the range min and max bound.

end instance-attribute 
end: Required[float]

The value a viewer should render at full intensity. This may narrow the range min and max bound.

Methods:
Methods:

Omero 

Omero(channels: Iterable[Channel | JsonDict | str], version: Literal['0.3'] = '0.3', *, 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({}))

Bases: OMEMetadata

Rendering settings for an image: one entry per channel.

Attach one of these to an image group, alongside its Multiscale, to suggest how a viewer should display it.

Attributes
channels instance-attribute 
channels: Required[list[Channel]]

A Channel for each channel of the image, in the image's channel order.

version instance-attribute 
version: Required[Version]

The OME-NGFF version the metadata is written against. Recommended in OME-NGFF 0.1 and 0.2, and required from 0.3 on.

Methods:

abczarr.ome.v0_3.version

abczarr.ome.v0_3.version

Attributes

Version module-attribute 

Version = tx.Literal['0.3']

VERSION module-attribute 

VERSION = '0.3'