dcnum 0.17.0__py3-none-any.whl → 0.23.2__py3-none-any.whl

dcnum/feat/feat_contour/volume.py

@@ -0,0 +1,174 @@
+from typing import List
+
+import numpy as np
+
+
+def volume_from_contours(
+        contour: List[np.ndarray],
+        pos_x: np.ndarray,
+        pos_y: np.ndarray,
+        pixel_size: float):
+    """Calculate the volume of a polygon revolved around an axis
+
+    The volume estimation assumes rotational symmetry.
+
+    Parameters
+    ----------
+    contour: list of ndarrays of shape (N,2)
+        One entry is a 2D array that holds the contour of an event
+    pos_x: float ndarray of length N
+        The x coordinate(s) of the centroid of the event(s) [µm]
+    pos_y: float ndarray of length N
+        The y coordinate(s) of the centroid of the event(s) [µm]
+    pixel_size: float
+        The detector pixel size in µm.
+
+    Returns
+    -------
+    volume: float ndarray
+        volume in um^3
+
+    Notes
+    -----
+    The computation of the volume is based on a full rotation of the
+    upper and the lower halves of the contour from which the
+    average is then used.
+
+    The volume is computed radially from the center position
+    given by (`pos_x`, `pos_y`). For sufficiently smooth contours,
+    such as densely sampled ellipses, the center position does not
+    play an important role. For contours that are given on a coarse
+    grid, as is the case for deformability cytometry, the center position
+    must be given.
+
+    References
+    ----------
+    - https://de.wikipedia.org/wiki/Kegelstumpf#Formeln
+    - Yields identical results to the Matlab script by Geoff Olynyk
+      <https://de.mathworks.com/matlabcentral/fileexchange/36525-volrevolve>`_
+    """
+    # results are stored in a separate array initialized with nans
+    v_avg = np.zeros_like(pos_x, dtype=np.float64) * np.nan
+
+    for ii in range(pos_x.shape[0]):
+        # If the contour has less than 4 pixels, the computation will fail.
+        # In that case, the value np.nan is already assigned.
+        cc = contour[ii]
+        if cc is not None and cc.shape[0] >= 4:
+            # Center contour coordinates with given centroid
+            contour_x = cc[:, 0] - pos_x[ii] / pixel_size
+            contour_y = cc[:, 1] - pos_y[ii] / pixel_size
+            # Switch to r and z to follow notation of vol_revolve
+            # (In RT-DC the axis of rotation is x, but for vol_revolve
+            # we need the axis vertically)
+            contour_r = contour_y
+            contour_z = contour_x
+
+            # Compute right volume
+            # Which points are at negative r-values (r<0)?
+            inx_neg = np.where(contour_r < 0)
+            # These points will be shifted up to r=0 directly on the z-axis
+            contour_right = np.copy(contour_r)
+            contour_right[inx_neg] = 0
+            vol_right = vol_revolve(r=contour_right,
+                                    z=contour_z,
+                                    point_scale=pixel_size)
+
+            # Compute left volume
+            # Which points are at positive r-values? (r>0)?
+            idx_pos = np.where(contour_r > 0)
+            # These points will be shifted down to y=0 to build an x-axis
+            contour_left = np.copy(contour_r)
+            contour_left[idx_pos] = 0
+            # Now we still have negative r values, but vol_revolve needs
+            # positive values, so we flip the sign...
+            contour_left[:] *= -1
+            # ... but in doing so, we have switched to clockwise rotation,
+            # and we need to pass the array in reverse order
+            vol_left = vol_revolve(r=contour_left[::-1],
+                                   z=contour_z[::-1],
+                                   point_scale=pixel_size)
+
+            # Compute the average
+            v_avg[ii] = (vol_right + vol_left) / 2
+
+    return {"volume": v_avg}
+
+
+def vol_revolve(r, z, point_scale=1.):
+    r"""Calculate the volume of a polygon revolved around the Z-axis
+
+    This implementation yields the same results as the volRevolve
+    Matlab function by Geoff Olynyk (from 2012-05-03)
+    https://de.mathworks.com/matlabcentral/fileexchange/36525-volrevolve.
+
+    The difference here is that the volume is computed using (a much
+    more approachable) implementation using the volume of a truncated
+    cone (https://de.wikipedia.org/wiki/Kegelstumpf).
+
+    .. math::
+
+      V = \frac{h \cdot \pi}{3} \cdot (R^2 + R \cdot r + r^2)
+
+    Where :math:`h` is the height of the cone and :math:`r` and
+    `R` are the smaller and larger radii of the truncated cone.
+
+    Each line segment of the contour resembles one truncated cone. If
+    the z-step is positive (counter-clockwise contour), then the
+    truncated cone volume is added to the total volume. If the z-step
+    is negative (e.g. inclusion), then the truncated cone volume is
+    removed from the total volume.
+
+    Parameters
+    ----------
+    r: 1d np.ndarray
+        radial coordinates (perpendicular to the z axis)
+    z: 1d np.ndarray
+        coordinate along the axis of rotation
+    point_scale: float
+        point size in your preferred units; The volume is multiplied
+        by a factor of `point_scale**3`.
+
+    Notes
+    -----
+    The coordinates must be given in counter-clockwise order,
+    otherwise the volume will be negative.
+    """
+    r = np.atleast_1d(r)
+    z = np.atleast_1d(z)
+
+    # make sure we have a closed contour
+    if (r[-1] != r[0]) or (z[-1] != z[0]):
+        # We have an open contour - close it.
+        r = np.resize(r, len(r) + 1)
+        z = np.resize(z, len(z) + 1)
+
+    rp = r[:-1]
+
+    # array of radii differences: R - r
+    dr = np.diff(r)
+    # array of height differences: h
+    dz = np.diff(z)
+
+    # If we expand the function in the doc string with
+    # dr = R - r and dz = h, then we get three terms for the volume
+    # (as opposed to four terms in Olynyk's script). Those three terms
+    # all resemble area slices multiplied by the z-distance dz.
+    a1 = 3 * rp ** 2
+    a2 = 3 * rp * dr
+    a3 = dr ** 2
+
+    # Note that the formula for computing the volume is symmetric
+    # with respect to r and R. This means that it does not matter
+    # which sign dr has (R and r are always positive). Since this
+    # algorithm assumes that the contour is ordered counter-clockwise,
+    # positive dz means adding to the contour while negative dz means
+    # subtracting from the contour (see test functions for more details).
+    # Conveniently so, dz only appears one time in this formula, so
+    # we can take the sign of dz as it is (Otherwise, we would have
+    # to take the absolute value of every truncated cone volume and
+    # multiply it by np.sign(dz)).
+    v = np.pi / 3 * dz * np.abs(a1 + a2 + a3)
+    vol = np.sum(v) * point_scale ** 3
+
+    return vol

dcnum/feat/feat_texture/tex_all.py

@@ -6,6 +6,34 @@ from .common import haralick_names
 
 def haralick_texture_features(
         mask, image=None, image_bg=None, image_corr=None):
+    """Compute Haralick texture features
+
+    The following texture features are excluded
+
+    - feature 6 "Sum Average", which is equivalent to `2 * bright_bc_avg`
+      since dclab 0.44.0
+    - feature 10 "Difference Variance", because it has a functional
+      dependency on the offset value and since we do background correction,
+      we are not interested in it
+    - feature 14, because nobody is using it, it is not understood by
+      everyone what it actually is, and it is computationally expensive.
+
+    This leaves us with the following 11 texture features (22 if you count
+    avg and ptp):
+    https://earlglynn.github.io/RNotes/package/EBImage/Haralick-Textural-Features.html
+
+    - 1. `tex_asm`: (1) Angular Second Moment
+    - 2. `tex_con`: (2) Contrast
+    - 3. `tex_cor`: (3) Correlation
+    - 4. `tex_var`: (4) Variance
+    - 5. `tex_idm`: (5) Inverse Difference Moment
+    - 6. `tex_sva`: (7) Sum Variance
+    - 7. `tex_sen`: (8) Sum Entropy
+    - 8. `tex_ent`: (9) Entropy
+    - 9. `tex_den`: (11) Difference Entropy
+    - 10. `tex_f12`: (12) Information Measure of Correlation 1
+    - 11. `tex_f13`: (13) Information Measure of Correlation 2
+    """
     # make sure we have a boolean array
     mask = np.array(mask, dtype=bool)
     size = mask.shape[0]
@@ -22,7 +50,6 @@ def haralick_texture_features(
 
     for ii in range(size):
         # Haralick texture features
-        # https://gitlab.gwdg.de/blood_data_analysis/dcevent/-/issues/20
         # Preprocessing:
         # - create a copy of the array (don't edit `image_corr`)
         # - add grayscale values (negative values not supported)

dcnum/feat/gate.py

@@ -20,7 +20,7 @@ class Gate:
         Parameters
         ----------
         data: .HDF5Data
-            dcevent data instance
+            dcnum data instance
         online_gates: bool
             set to True to enable gating with "online" gates stored
             in the input file; online gates are applied in real-time
@@ -95,7 +95,7 @@ class Gate:
         """Return a unique gating pipeline identifier
 
         The pipeline identifier is universally applicable and must
-        be backwards-compatible (future versions of dcevent will
+        be backwards-compatible (future versions of dcnum will
         correctly acknowledge the ID).
 
         The gating pipeline ID is defined as::

dcnum/feat/queue_event_extractor.py

@@ -14,7 +14,7 @@ from ..meta.ppid import kwargs_to_ppid, ppid_to_kwargs
 from ..read import HDF5Data
 
 from .feat_brightness import brightness_features
-from .feat_moments import moments_based_features
+from .feat_contour import moments_based_features, volume_from_contours
 from .feat_texture import haralick_texture_features
 from .gate import Gate
 
@@ -36,7 +36,7 @@ class QueueEventExtractor:
                  finalize_extraction: mp.Value,
                  invalid_mask_counter: mp.Value,
                  worker_monitor: mp.RawArray,
-                 log_level: int = logging.INFO,
+                 log_level: int = None,
                  extract_kwargs: dict = None,
                  worker_index: int = None,
                  *args, **kwargs):
@@ -103,7 +103,7 @@ class QueueEventExtractor:
         # it looks like we have the same PID as the parent process. We
         # are setting up logging in `run`.
         self.logger = None
-        self.log_level = log_level
+        self.log_level = log_level or logging.getLogger("dcnum").level
         #: Shared array of length `len(data)` into which the number of
         #: events per frame is written.
         self.feat_nevents = feat_nevents
@@ -124,7 +124,7 @@ class QueueEventExtractor:
                         gate: Gate,
                         num_extractors: int,
                         log_queue: mp.Queue,
-                        log_level: int = logging.INFO,
+                        log_level: int = None,
                         ):
         """Get initialization arguments for :cass:`.QueueEventExtractor`
 
@@ -172,31 +172,52 @@ class QueueEventExtractor:
         args["finalize_extraction"] = mp_spawn.Value("b", False)
         args["invalid_mask_counter"] = mp_spawn.Value("L", 0)
         args["worker_monitor"] = mp_spawn.RawArray("L", num_extractors)
-        args["log_level"] = log_level
+        args["log_level"] = log_level or logging.getLogger("dcnum").level
         return args
 
     def get_events_from_masks(self, masks, data_index, *,
                               brightness: bool = True,
                               haralick: bool = True,
+                              volume: bool = True,
                               ):
         """Get events dictionary, performing event-based gating"""
         events = {"mask": masks}
         image = self.data.image[data_index][np.newaxis]
         image_bg = self.data.image_bg[data_index][np.newaxis]
         image_corr = self.data.image_corr[data_index][np.newaxis]
+        if "bg_off" in self.data:
+            bg_off = self.data["bg_off"][data_index]
+        else:
+            bg_off = None
 
         events.update(
             moments_based_features(
                 masks,
-                pixel_size=self.data.pixel_size))
+                pixel_size=self.data.pixel_size,
+                ret_contour=volume,
+                ))
+
         if brightness:
             events.update(brightness_features(
-                mask=masks, image=image, image_bg=image_bg,
+                mask=masks,
+                image=image,
+                image_bg=image_bg,
+                bg_off=bg_off,
                 image_corr=image_corr
             ))
         if haralick:
             events.update(haralick_texture_features(
-                mask=masks, image=image, image_corr=image_corr
+                mask=masks,
+                image=image,
+                image_corr=image_corr,
+            ))
+
+        if volume:
+            events.update(volume_from_contours(
+                contour=events.pop("contour"),  # remove contour from events!
+                pos_x=events["pos_x"],
+                pos_y=events["pos_y"],
+                pixel_size=self.data.pixel_size,
             ))
 
         # gating on feature arrays
@@ -245,7 +266,7 @@ class QueueEventExtractor:
         """Return a unique feature extractor pipeline identifier
 
         The pipeline identifier is universally applicable and must
-        be backwards-compatible (future versions of dcevent will
+        be backwards-compatible (future versions of dcnum will
         correctly acknowledge the ID).
 
         The feature extractor pipeline ID is defined as::