ref: implement __array__ method for H5MaskEvent

CHANGELOG

@@ -10,6 +10,7 @@
    (minor speedup since previously a chunk size of 100 events was used
    for images and scalar features were written in one big chunk)
  - ref: implement `__array__` methods for hierarchy event classes
+ - ref: implement `__array__` method for `H5MaskEvent`
  - ref: new submodule for hierarchy format
 0.56.3
  - fix: regression missing check for basin availability

dclab/rtdc_dataset/fmt_hdf5/events.py

@@ -1,6 +1,8 @@
 """RT-DC hdf5 format"""
 from __future__ import annotations
 
+import warnings
+
 import numbers
 import numpy as np
 
@@ -138,6 +140,16 @@ def __init__(self, h5dataset):
         self.identifier = (self.h5dataset.file.filename, self.h5dataset.name)
         self.dtype = np.dtype(bool)
 
+    def __array__(self, dtype=np.bool_):
+        if dtype is not np.uint8:
+            warnings.warn("Please avoid calling the `__array__` method of the "
+                          "`H5MaskEvent`. It may consume a lot of memory.",
+                          UserWarning)
+        # One of the reasons why we implement __array__ is such that
+        # the data exporter knows this object is sliceable
+        # (see yield_filtered_array_stacks).
+        return self.h5dataset.__array__(dtype=dtype)
+
     def __getitem__(self, idx):
         return np.asarray(self.h5dataset[idx], dtype=bool)
 

tests/test_rtdc_fmt_hdf5.py

@@ -303,6 +303,12 @@ def test_defective_feature_volume():
         assert np.allclose(ds2["volume"], wrong_volume)
 
 
+def test_discouraged_array_dunder_childndarray():
+    ds = new_dataset(retrieve_data("fmt-hdf5_fl_wide-channel_2023.zip"))
+    with pytest.warns(UserWarning, match="It may consume a lot of memory"):
+        maskbool = ds["mask"].__array__()
+
+
 @pytest.mark.filterwarnings(
     "ignore::dclab.rtdc_dataset.config.WrongConfigurationTypeWarning")
 @pytest.mark.filterwarnings(