dcnum 0.24.0__tar.gz → 0.25.0__tar.gz

{dcnum-0.24.0 → dcnum-0.25.0}/CHANGELOG

@@ -1,3 +1,7 @@
+0.25.0
+ - feat: identify flickering in raw data via dcnum.read.detect_flickering
+ - fix: handle out-of-bounds slice indexing for BaseImageChunkCache
+ - fix: np.bool_ and np.floating not recognized in PPID parsing
 0.24.0
  - feat: add support for internal basins
  - feat: "image_bg" as internal basin for "sparsemed" background computer

{dcnum-0.24.0 → dcnum-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dcnum
-Version: 0.24.0
+Version: 0.25.0
 Summary: numerics toolbox for imaging deformability cytometry
 Author: Maximilian Schlögel, Paul Müller, Raghava Alajangi
 Maintainer-email: Paul Müller <dev@craban.de>

{dcnum-0.24.0 → dcnum-0.25.0}/src/dcnum/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.24.0'
-__version_tuple__ = version_tuple = (0, 24, 0)
+__version__ = version = '0.25.0'
+__version_tuple__ = version_tuple = (0, 25, 0)

{dcnum-0.24.0 → dcnum-0.25.0}/src/dcnum/feat/feat_background/bg_sparse_median.py

@@ -59,7 +59,7 @@ class BackgroundSparseMed(Background):
         offset_correction: bool
             The sparse median background correction produces one median
             image for multiple input frames (BTW this also leads to very
-            efficient data storage with HDF5 data compression filters). In
+            efficient data storage with internal HDF5 basins). In
             case the input frames are subject to frame-by-frame brightness
             variations (e.g. flickering of the illumination source), it
             is useful to have an offset value per frame that can then be
@@ -226,7 +226,7 @@ class BackgroundSparseMed(Background):
         offset_correction: bool
             The sparse median background correction produces one median
             image for multiple input frames (BTW this also leads to very
-            efficient data storage with HDF5 data compression filters). In
+            efficient data storage with internal HDF5 basins). In
             case the input frames are subject to frame-by-frame brightness
             variations (e.g. flickering of the illumination source), it
             is useful to have an offset value per frame that can then be

{dcnum-0.24.0 → dcnum-0.25.0}/src/dcnum/meta/ppid.py

@@ -7,6 +7,7 @@ import pathlib
 from typing import Dict, List, Protocol
 import warnings
 
+import numpy as np
 
 #: Increment this string if there are breaking changes that make
 #: previous pipelines unreproducible.
@@ -140,9 +141,9 @@ def kwargs_to_ppid(cls: ClassWithPPIDCapabilities,
                 path = pathlib.Path(val)
                 if path.exists():
                     val = path.name
-            if isinstance(val, bool):
+            if isinstance(val, (bool, np.bool_)):
                 val = int(val)  # do not print e.g. "True"
-            elif isinstance(val, float):
+            elif isinstance(val, (float, np.floating)):
                 if val == int(val):
                     val = int(val)  # omit the ".0" at the end
             concat_strings.append(f"{abr}={val}")

{dcnum-0.24.0 → dcnum-0.25.0}/src/dcnum/read/__init__.py

@@ -1,5 +1,6 @@
 # flake8: noqa: F401
 from .cache import md5sum
 from .const import PROTECTED_FEATURES
+from .detect_flicker import detect_flickering
 from .hdf5_data import HDF5Data, HDF5ImageCache, concatenated_hdf5_data
 from .mapped import get_mapping_indices, get_mapped_object

{dcnum-0.24.0 → dcnum-0.25.0}/src/dcnum/read/cache.py

@@ -36,9 +36,10 @@ class BaseImageChunkCache(abc.ABC):
     def __getitem__(self, index):
         if isinstance(index, (slice, list, np.ndarray)):
             if isinstance(index, slice):
-                indices = np.arange(index.start or 0,
-                                    index.stop or len(self),
-                                    index.step)
+                indices = np.arange(
+                    index.start or 0,
+                    min(index.stop, len(self)) if index.stop else len(self),
+                    index.step)
             else:
                 indices = index
             array_out = np.empty((len(indices),) + self.image_shape,

dcnum-0.25.0/src/dcnum/read/detect_flicker.py

@@ -0,0 +1,44 @@
+import numpy as np
+
+from .hdf5_data import HDF5Data
+
+
+def detect_flickering(image_data: np.ndarray | HDF5Data,
+                      roi_height: int = 10,
+                      brightness_threshold: float = 2.5,
+                      count_threshold: int = 5,
+                      max_frames: int = 1000):
+    """Determine whether an image series experiences flickering
+
+    Flickering is an unwelcome phenomenon due to a faulty data
+    acquisition device. For instance, if there is random voltage noise in
+    the electronics managing the LED power, then the brightness of the
+    LED will vary randomly when the noise signal overlaps with the flash
+    triggering signal.
+
+    If flickering is detected, you should use the "sparsemed" background
+    computation with `offset_correction` set to True.
+
+    Parameters
+    ----------
+    image_data:
+        sliceable object (e.g. numpy array or HDF5Data) containing
+        image data.
+    roi_height: int
+        height of the ROI in pixels for which to search for flickering;
+        the entire width of the image is used
+    brightness_threshold: float
+        brightness difference between individual ROIs median and median
+        of all ROI medians leading to a positive flickering event
+    count_threshold: int
+        minimum number of flickering events that would lead to a positive
+        flickering decision
+    max_frames: int
+        maximum number of frames to include in the flickering analysis
+    """
+    # slice event axis first in case we have and HDF5Data instance
+    roi_data = image_data[:max_frames][:, :roi_height, :]
+    roi_median = np.median(roi_data, axis=(1, 2))
+    roi_offset = roi_median - np.median(roi_median)
+    flickering_events = np.sum(np.abs(roi_offset) >= abs(brightness_threshold))
+    return flickering_events >= count_threshold

{dcnum-0.24.0 → dcnum-0.25.0}/src/dcnum.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dcnum
-Version: 0.24.0
+Version: 0.25.0
 Summary: numerics toolbox for imaging deformability cytometry
 Author: Maximilian Schlögel, Paul Müller, Raghava Alajangi
 Maintainer-email: Paul Müller <dev@craban.de>

{dcnum-0.24.0 → dcnum-0.25.0}/src/dcnum.egg-info/SOURCES.txt

@@ -46,6 +46,7 @@ src/dcnum/meta/ppid.py
 src/dcnum/read/__init__.py
 src/dcnum/read/cache.py
 src/dcnum/read/const.py
+src/dcnum/read/detect_flicker.py
 src/dcnum/read/hdf5_data.py
 src/dcnum/read/mapped.py
 src/dcnum/segm/__init__.py
@@ -93,6 +94,7 @@ tests/test_meta_ppid_gate.py
 tests/test_meta_ppid_segm.py
 tests/test_read_basin.py
 tests/test_read_concat_hdf5.py
+tests/test_read_detect_flicker.py
 tests/test_read_hdf5.py
 tests/test_read_hdf5_basins.py
 tests/test_read_hdf5_index_mapping.py

{dcnum-0.24.0 → dcnum-0.25.0}/tests/test_meta_ppid_base.py

@@ -1,5 +1,7 @@
 import inspect
 
+import numpy as np
+
 import pytest
 
 from dcnum.meta import ppid
@@ -80,8 +82,14 @@ def test_unique_prefix_unordered(in_list, out_list):
      "tem=90^te=a^o=0^wit=1^a=1000^win=red^tes=1"),
     ({"temperature": 10.1},
      "tem=10.1^te=a^o=0^wit=1^a=1000^win=red^tes=1"),
+    ({"temperature": 10.0},
+     "tem=10^te=a^o=0^wit=1^a=1000^win=red^tes=1"),
+    ({"temperature": np.float16(9.0)},
+     "tem=9^te=a^o=0^wit=1^a=1000^win=red^tes=1"),
     ({"with_water": False, "wine_type": "blue"},
      "tem=90^te=a^o=0^wit=0^a=1000^win=blue^tes=1"),
+    ({"with_water": np.bool_(1), "wine_type": "blue"},
+     "tem=90^te=a^o=0^wit=1^a=1000^win=blue^tes=1"),
 ])
 def test_kwargs_to_ppid(kwargs, pid):
     ptest = ppid.kwargs_to_ppid(ExampleClass, "cook", kwargs)

dcnum-0.25.0/tests/test_read_detect_flicker.py

@@ -0,0 +1,87 @@
+import numpy as np
+
+from dcnum.read import concatenated_hdf5_data, detect_flickering
+
+from helper_methods import retrieve_data
+
+
+def test_detect_flicker_basic():
+    image_data = np.full((500, 80, 320), 145)
+    flicker_indices = [4, 9, 10, 23, 439]
+    for idx in flicker_indices:
+        image_data[idx] += 5
+    assert detect_flickering(image_data,
+                             roi_height=10,
+                             brightness_threshold=5,
+                             count_threshold=5,
+                             max_frames=500,
+                             )
+
+    assert not detect_flickering(image_data,
+                                 roi_height=10,
+                                 brightness_threshold=5,
+                                 count_threshold=6,  # threshold too low
+                                 max_frames=500,
+                                 )
+
+    assert not detect_flickering(image_data,
+                                 roi_height=10,
+                                 brightness_threshold=6,  # threshold too low
+                                 count_threshold=5,
+                                 max_frames=500,
+                                 )
+
+    assert not detect_flickering(image_data,
+                                 roi_height=10,
+                                 brightness_threshold=5,
+                                 count_threshold=5,
+                                 max_frames=400,  # too few frames
+                                 )
+
+
+def test_detect_flicker_hdf5data_instance():
+    path = retrieve_data("fmt-hdf5_cytoshot_full-features_2023.zip")
+    path_out = path.with_name("input.rtdc")
+    # create simple concatenated dataset, repeating a file
+    with concatenated_hdf5_data([path]*25, path_out=path_out) as hd:
+        assert len(hd) == 1000
+        assert not detect_flickering(hd.image)
+        assert detect_flickering(hd.image, brightness_threshold=1)
+
+
+def test_detect_flicker_none():
+    image_data = np.full((500, 80, 320), 145)
+    assert not detect_flickering(image_data,
+                                 roi_height=10,
+                                 brightness_threshold=5,
+                                 count_threshold=5,
+                                 max_frames=500,
+                                 )
+
+
+def test_detect_flicker_not_outside_roi():
+    image_data = np.full((500, 80, 320), 145)
+    flicker_indices = [4, 9, 10, 23, 439]
+    for idx in flicker_indices:
+        # only modify data outside the ROI
+        image_data[idx, 11:, :] += 5
+    assert not detect_flickering(image_data,
+                                 roi_height=10,
+                                 brightness_threshold=5,
+                                 count_threshold=5,
+                                 max_frames=500,
+                                 )
+
+
+def test_detect_flicker_only_inside_roi():
+    image_data = np.full((500, 80, 320), 145)
+    flicker_indices = [4, 9, 10, 23, 439]
+    for idx in flicker_indices:
+        # only modify data inside the ROI
+        image_data[idx, :10, :] += 5
+    assert detect_flickering(image_data,
+                             roi_height=10,
+                             brightness_threshold=5,
+                             count_threshold=5,
+                             max_frames=500,
+                             )

{dcnum-0.24.0 → dcnum-0.25.0}/tests/test_read_hdf5.py

@@ -106,6 +106,19 @@ def test_image_cache(tmp_path):
         assert 2 in hic.cache
 
 
+def test_image_cache_slice_out_of_bounds(tmp_path):
+    path = tmp_path / "test.hdf5"
+    with h5py.File(path, "w") as hw:
+        hw["events/image"] = np.random.rand(210, 80, 180)
+
+    with h5py.File(path, "r") as h5:
+        hic = read.HDF5ImageCache(h5["events/image"],
+                                  chunk_size=100,
+                                  cache_size=2)
+        assert len(hic) == 210
+        assert len(hic[:300]) == 210
+
+
 def test_image_cache_index_out_of_range(tmp_path):
     path = tmp_path / "test.hdf5"
     size = 20