refactor `ez_zarr`

[mbstadler]

... in order to support additional flavors of OME-Zarr filesets.

Ideas:

• [x] new class ez_zarr.ome_zarr.Image representing an image: what we currently have in fractal_out.zarr/B/03/0 (contains .zgroup and pyramid level folders 0, 1, 2, ... each containing .zarray)
• [x] new class ez_zarr.ome_zarr.Plate: similar to current FractalZarr, using Image internally (either creating them upon construction, or on the fly when needed) and with additional changes (see below)
• [x] make ez_zarr.ome_zarr.Plate work with Fractal and FAIM outputs
• [x] check for missing .zgroups in column folder of Fractal plate output
• [x] collect example data in /we/know/where/Data/ZarrExampleData
• [ ] Edit ez_zarr.ome_zarr.Plate methods:
  • [ ] calc_average_FOV: add smoothing capability (e.g. Gaussian kernel at the end)
  • [x] get_image_ROI -> use ez_zarr.ome_zarr.Image internally, rename to get_array_by_coordinate, get_subarray, get_pyramid, get_array_pyramid
  • [ ] accordingly: get_image_grid_ROIs -> get_xxx_grid_parts
  • [ ] accordingly: get_image_table_idx -> get_xxx_by_table_index
  • [x] get_label_ROI -> get_array_by_coordinate (intensity or label?) -> no separate getlabel functions, can use the new getimage functions with additional argument: label_name = None -> intensity image, or label_name = "nuclei" -> label image
  • [x] get_label_names -> make it a ez_zarr.ome_zarr.Image method, the Plate method could default to the first image or accept a list of images/wells
  • [x] get_label_table_idx -> use corresponding get_xxx_by_table_index function (as for getlabel functions above): obsolete (using a single getarray function now for both intensity and label image retreaval)
• [x] utility function describe("path/to/zarr") -> similar to zarr.hierarchy.Group.tree()
• [x] possible additional classes representing an array (folder containing .zarray), a list of arrays (initialised by a folder, populates list with all arrays found within), any other specific zarr filesets
• [x] plot the label values in Image.plot()
• [x] add support for 2D arrays (y,x) in plotting.plot_image (just add a dummy channel axis using np.newaxis())
• [x] add table of content to getting started guides
• [x] instead of row_label and column_label in the layout, use a single label column

Small addition to consider (identified by using ez_zarr on feature extraction 3D):

• [x] expose _get_bounding_box_for_label_value as public function
• [x] transform the label_name argument of get_array_pair_by_coordinate to a label_list --> very useful for extracting together with the intensity image arrays, also paired nuclei, cells, and potentially organoids masks
• [x] extract region of interest with get_array_pair_by_coordinate by label_id (object) and not only by coordinates (this is done already when we plot by object_id) --> implemented by exposing get_bounding_box_for_label_value with ability to specify output coordinate space
• [x] related to the above: plot object (defined by label1) and show label2 --> same as above (use get_bounding_box_for_label_value to get coordinates, then use these in plot)

[jluethi]

Super interesting to follow along, thanks for documenting this @mbstadler & for sending me a link @silvbarb !

A few small comments from me:

new class ez_zarr.ome_zarr.Image representing an image: what we currently have in fractal_out.zarr/B/03/0 (contains .zgroup and pyramid level folders 0, 1, 2, ... each containing .zarray)

Core is also that it contains a .zattrs with multiscales metadata following the NGFF spec

possible additional classes representing an array (folder containing .zarray), a list of arrays (initialised by a folder, populates list with all arrays found within), any other specific zarr filesets

Intuitively, I see this as a function of the Image class: Provide the different resolution level arrays, based on available resolution levels. Or provide some Zarr subgroups like labels & tables.

---

Also, in case it's relevant, I started playing around with an OME-Zarr image class here: https://github.com/fractal-analytics-platform/napari-ome-zarr-navigator/blob/roi_loader/src/napari_ome_zarr_navigator/ome_zarr_image.py Would be interesting to figure out if we have matching needs for the OMEZarrImage class! I think there should be quite some overlap given your description above and what I've been needing so far. Happy to then contribute to ez_zarr if that's relevant / evaluate whether depending on the fractal_tasks_core roi & NGFF metadata functionality in my case is relevant :)

[mbstadler]

Reopening the issue (image-level tasks are done and included in #10, but plate-level tasks remain to be done).