ENH: Validate data objects' attributes at instantiation

Validate data objects' attributes at instantiation: ensures that the
attributes are present and match the expected dimensionalities.

Author: jhlegarreta

src/nifreeze/data/base.py

@@ -44,6 +44,21 @@
 
 ImageGrid = namedtuple("ImageGrid", ("shape", "affine"))
 
+DATAOBJ_ABSENCE_ERROR_MSG = "BaseDataset 'dataobj' may not be None"
+"""BaseDataset initialization dataobj absence error message."""
+
+DATAOBJ_NDIM_ERROR_MSG = "BaseDataset 'dataobj' must be a 4-D numpy array"
+"""BaseDataset initialization dataobj dimensionality error message."""
+
+AFFINE_ABSENCE_ERROR_MSG = "BaseDataset 'affine' may not be None"
+"""BaseDataset initialization affine absence error message."""
+
+AFFINE_SHAPE_ERROR_MSG = "BaseDataset 'affine' must be a 2-D numpy array (4 x 4)"
+"""BaseDataset initialization affine shape error message."""
+
+BRAINMASK_SHAPE_MISMATCH_ERROR_MSG = "BaseDataset brainmask shape ({brainmask_shape}) does not match dataset volumes ({data_shape})."
+"""BaseDataset brainmask shape mismatch error message."""
+
 
 def _data_repr(value: np.ndarray | None) -> str:
     if value is None:
@@ -58,6 +73,20 @@ def _cmp(lh: Any, rh: Any) -> bool:
     return lh == rh
 
 
+def _dataobj_validator(inst, attr, value) -> None:
+    if value is None:
+        raise ValueError(DATAOBJ_ABSENCE_ERROR_MSG)
+    if not isinstance(value, np.ndarray) or value.ndim != 4:
+        raise ValueError(DATAOBJ_NDIM_ERROR_MSG)
+
+
+def _affine_validator(inst, attr, value) -> None:
+    if value is None:
+        raise ValueError(AFFINE_ABSENCE_ERROR_MSG)
+    if not isinstance(value, np.ndarray) or value.shape != (4, 4):
+        raise ValueError(AFFINE_SHAPE_ERROR_MSG)
+
+
 @attrs.define(slots=True)
 class BaseDataset(Generic[Unpack[Ts]]):
     """
@@ -75,9 +104,13 @@ class BaseDataset(Generic[Unpack[Ts]]):
 
     """
 
-    dataobj: np.ndarray = attrs.field(default=None, repr=_data_repr, eq=attrs.cmp_using(eq=_cmp))
+    dataobj: np.ndarray = attrs.field(
+        default=None, repr=_data_repr, eq=attrs.cmp_using(eq=_cmp), validator=_dataobj_validator
+    )
     """A :obj:`~numpy.ndarray` object for the data array."""
-    affine: np.ndarray = attrs.field(default=None, repr=_data_repr, eq=attrs.cmp_using(eq=_cmp))
+    affine: np.ndarray = attrs.field(
+        default=None, repr=_data_repr, eq=attrs.cmp_using(eq=_cmp), validator=_affine_validator
+    )
     """Best affine for RAS-to-voxel conversion of coordinates (NIfTI header)."""
     brainmask: np.ndarray | None = attrs.field(
         default=None, repr=_data_repr, eq=attrs.cmp_using(eq=_cmp)
@@ -95,6 +128,22 @@ class BaseDataset(Generic[Unpack[Ts]]):
     )
     """A path to an HDF5 file to store the whole dataset."""
 
+    def __attrs_post_init__(self) -> None:
+        """Enforce basic consistency of base dataset fields at instantiation
+        time.
+
+        Specifically, the brainmask (if present) must match spatial shape of
+        dataobj.
+        """
+
+        if self.brainmask is not None:
+            if self.brainmask.shape != tuple(self.dataobj.shape[:3]):
+                raise ValueError(
+                    BRAINMASK_SHAPE_MISMATCH_ERROR_MSG.format(
+                        brainmask_shape=self.brainmask.shape, data_shape=self.dataobj.shape[:3]
+                    )
+                )
+
     def __len__(self) -> int:
         """Obtain the number of volumes/frames in the dataset."""
         return self.dataobj.shape[-1]