test, docs: ensure get_bright_perc returns expected types

dclab/features/bright_perc.py

@@ -3,9 +3,14 @@
 RT-DC event image mask with background-correction taken into account.
 """
 import numpy as np
+import numpy.typing as npt
 
 
-def get_bright_perc(mask, image, image_bg, bg_off=None):
+def get_bright_perc(mask: npt.NDArray[bool] | list[npt.NDArray[bool]],
+                    image: npt.NDArray | list[npt.NDArray],
+                    image_bg: npt.NDArray | list[npt.NDArray],
+                    bg_off: float | npt.NDArray = None) -> \
+        tuple[float, float] | tuple[npt.NDArray, npt.NDArray]:
     """Compute 10th and 90th percentile of the bg-corrected event brightness
 
     The background-corrected event brightness is defined by the
@@ -29,7 +34,7 @@ def get_bright_perc(mask, image, image_bg, bg_off=None):
     -------
     bright_perc_10: float or ndarray of size N
         10th percentile of brightness
-    bright_perc_10: float or ndarray of size N
+    bright_perc_90: float or ndarray of size N
         90th percentile of brightness
     """
     if isinstance(mask, np.ndarray) and len(mask.shape) == 2:

tests/test_feat_bright_perc.py

@@ -65,11 +65,35 @@ def test_af_brightness_bc_single():
         p10 = np.percentile(image_corr[mask], 10)
         p90 = np.percentile(image_corr[mask], 90)
         assert np.max(np.abs(image_corr)) < 50, "sanity check"
-        assert dclab.features.bright_perc.get_bright_perc(
+
+        p10_calc, p90_calc = dclab.features.bright_perc.get_bright_perc(
             ds["mask"][ii],
             ds["image"][ii],
             ds["image_bg"][ii],
-        ) == (p10, p90)
+        )
+        assert (p10_calc, p90_calc) == (p10, p90)
+
+
+@pytest.mark.filterwarnings(
+    "ignore::dclab.rtdc_dataset.config.WrongConfigurationTypeWarning")
+def test_af_brightness_bc_list():
+    path = retrieve_data("fmt-hdf5_image-bg_2020.zip")
+    ds = dclab.new_dataset(path)
+    # sanity checks
+    assert "bright_perc_10" not in ds.features_innate
+    assert "bright_perc_90" not in ds.features_innate
+    # ignore first event (no image data)
+    mask = list(ds["mask"][1:6])
+    image = list(ds["image"][1:6])
+    image_bg = list(ds["image_bg"][1:6])
+
+    p10_calc, p90_calc = dclab.features.bright_perc.get_bright_perc(
+        mask, image, image_bg,
+    )
+    assert isinstance(p10_calc, np.ndarray)
+    assert isinstance(p90_calc, np.ndarray)
+    assert p10_calc.shape == (4,)
+    assert p90_calc.shape == (4,)
 
 
 @pytest.mark.filterwarnings(