Allow HCS objects without existing well groups (#214)

* Allow HCS objects without existing well groups

* Fix row/col indexing

* Fix well group gettingb

* Add a breaking changelog entry

Author: dstansby

docs/changelog.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.10
+
+### Bug fixes
+
+- Creating a `HCS` group with well paths that do not point to existing well Zarr groups
+  no longer errors.
+
+### Breaking changes
+
+- `HCS.well_groups` will now only return well groups that exist, instead of erroring out if a well group is defined in the HCS metadata but does not exist as a Zarr group.
+
 ## 0.1.9
 
 ### Bug fixes

src/ome_zarr_models/common/well.py

@@ -8,3 +8,9 @@ class WellAttrs(BaseAttrs):
     """
 
     well: WellMeta
+
+
+class WellGroupNotFoundError(RuntimeError):
+    """
+    Raised if a well Zarr group is not found.
+    """

src/ome_zarr_models/v04/hcs.py

@@ -4,6 +4,7 @@
 from pydantic import model_validator
 
 from ome_zarr_models.base import BaseAttrs
+from ome_zarr_models.common.well import WellGroupNotFoundError
 from ome_zarr_models.v04.base import BaseGroupv04
 from ome_zarr_models.v04.plate import Plate
 from ome_zarr_models.v04.well import Well
@@ -60,9 +61,18 @@ def n_wells(self) -> int:
     def well_groups(self) -> Generator[Well, None, None]:
         """
         Well groups within this HCS group.
+
+        Notes
+        -----
+        Only well groups that exist are returned. This can be less than the number
+        of wells defined in the HCS metadata if some of the well Zarr groups don't
+        exist.
         """
         for i in range(self.n_wells):
-            yield self.get_well_group(i)
+            try:
+                yield self.get_well_group(i)
+            except WellGroupNotFoundError:
+                continue
 
     def get_well_group(self, i: int) -> Well:
         """
@@ -72,12 +82,25 @@ def get_well_group(self, i: int) -> Well:
         ----------
         i :
             Index of well group.
+
+        Raises
+        ------
+        WellGroupNotFoundError :
+            If no Zarr group is found at the well path.
         """
         well = self.attributes.plate.wells[i]
         well_path = well.path
         well_path_parts = well_path.split("/")
-        group = self
-        for part in well_path_parts:
-            group = group.members[part]
-
+        if len(well_path_parts) != 2:
+            raise RuntimeError(f"Well path '{well_path_parts}' does not have two parts")
+        row, col = well_path_parts
+        if row not in self.members:
+            raise WellGroupNotFoundError(
+                f"Row '{row}' not found in group members: {self.members}"
+            )
+        if col not in self.members[row].members:
+            raise WellGroupNotFoundError(
+                f"Column '{col}' not found in row group members: {self.members[row]}"
+            )
+        group = self.members[row].members[col]
         return Well(attributes=group.attributes, members=group.members)

tests/v04/test_hcs.py

@@ -14,7 +14,7 @@
 
 def test_example_hcs() -> None:
     group = zarr.open(Path(__file__).parent / "data" / "hcs_example.ome.zarr", mode="r")
-    hcs = HCS.from_zarr(group)
+    hcs: HCS = HCS.from_zarr(group)
     assert hcs.attributes == HCSAttrs(
         plate=Plate(
             acquisitions=[
@@ -38,7 +38,7 @@ def test_example_hcs() -> None:
 
     well_groups = list(hcs.well_groups)
     assert len(well_groups) == 1
-    well_group = well_groups[0]
+    well_group = hcs.get_well_group(0)
     assert well_group.attributes.well == WellMeta(
         images=[WellImage(path="0", acquisition=None)], version="0.4"
     )
@@ -108,3 +108,25 @@ def test_example_hcs() -> None:
             version="0.4",
         ),
     )
+
+
+def test_non_existent_wells() -> None:
+    """
+    Make sure it's possible to create a HCS that has well paths that don't exist
+    as Zarr groups.
+
+    The relevant part of the OME-Zarr specification (https://ngff.openmicroscopy.org/0.4/index.html#plate-md)
+    does not specify explicitly that the Zarr groups have to exist.
+    """
+    HCS(
+        attributes={
+            "plate": {
+                "acquisitions": [{"id": 1}, {"id": 2}, {"id": 3}],
+                "columns": [{"name": "1"}],
+                "field_count": 10,
+                "rows": [{"name": "A"}],
+                "version": "0.4",
+                "wells": [{"columnIndex": 0, "path": "A/1", "rowIndex": 0}],
+            }
+        }
+    )