3.2. "bioformats2raw.layout" (transitional)

[dstansby]

3.2.2. Attributes

The top-level .zattrs file must contain the bioformats2raw.layout key:

{
  "bioformats2raw.layout" : 3
}

If the top-level group represents a plate, the bioformats2raw.layout metadata will be present but the "plate" key MUST also be present, takes precedence and parsing of such datasets should follow § 3.8 "plate" metadata. It is not possible to mix collections of images with plates at present.

{
  "bioformats2raw.layout" : 3,
  "plate" : {
    "columns" : [ {
      "name" : "1"
    } ],
    "name" : "Plate Name 0",
    "wells" : [ {
      "path" : "A/1",
      "rowIndex" : 0,
      "columnIndex" : 0
    } ],
    "field_count" : 1,
    "rows" : [ {
      "name" : "A"
    } ],
    "acquisitions" : [ {
      "id" : 0
    } ],
    "version" : "0.4"
  }
}

The .zattrs file within the OME group may contain the "series" key:

{
  "series" : [ "0", "1" ]
}

3.2.3. Details

Conforming groups:

MUST have the value "3" for the "bioformats2raw.layout" key in their .zattrs metadata at the top of the hierarchy;

SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:

    MUST adhere to the OME-XML specification but

    MUST use <MetadataOnly/> elements as opposed to <BinData/>, <BinaryOnly/> or <TiffData/>;

    MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).

Additionally, the logic for finding the Zarr group for each image follows the following logic:

If "plate" metadata is present, images MUST be located at the defined location.

    Matching "series" metadata (as described next) SHOULD be provided for tools that are unaware of the "plate" specification.

If the "OME" Zarr group exists, it:

    MAY contain a "series" attribute. If so:

        "series" MUST be a list of string objects, each of which is a path to an image group.

        The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml" if provided.

If the "series" attribute does not exist and no "plate" is present:

    separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).

Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.

Conforming readers:

SHOULD make users aware of the presence of more than one image (i.e. SHOULD NOT default to only opening the first image);

MAY use the "series" attribute in the "OME" group to determine a list of valid groups to display;

MAY choose to show all images within the collection or offer the user a choice of images, as with HCS plates;

MAY ignore other groups or arrays under the root of the hierarchy.

https://ngff.openmicroscopy.org/0.4/index.html#bf2raw

[dstansby]

Looks like we're going to have to parse XML:

SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:

• MUST adhere to the OME-XML specification but
• MUST use elements as opposed to , or ;

[d-v-b]

more precisely, it looks like we will have to do all of OME-XML. i think we either deem that out of scope, or we use something like ome-types (cc @tlambert03), or we do something halfway and make the OME validation optional, thereby making ome-types and optional dep?

[dstansby]

Given it's transitional, I'm open to saying "we don't implement this part of the spec because it's complicated and transitional. PRs welcome if you want to implement it"

[tlambert03]

And do reach out here if you need to implement it. It would be a shame to have two python wrappers around the same model.

[dstansby]

If it's easy enough to implement using ome-types then that seems like the way to go. And if it's a lightweight dependency, I see no reason not to include it as a non-optional dependency?