dclab 0.62.17__cp39-cp39-macosx_11_0_arm64.whl → 0.67.3__cp39-cp39-macosx_11_0_arm64.whl

dclab/features/volume.py

@@ -1,8 +1,16 @@
 """Volume computation based on contour revolution"""
+from __future__ import annotations
+
 import numpy as np
+import numpy.typing as npt
 
 
-def get_volume(cont, pos_x, pos_y, pix, fix_orientation=False):
+def get_volume(
+        cont: npt.NDArray | list[npt.NDArray],
+        pos_x: float | npt.NDArray,
+        pos_y: float | npt.NDArray,
+        pix: float,
+        fix_orientation: bool = False) -> float | npt.NDArray:
     """Calculate the volume of a polygon revolved around an axis
 
     The volume estimation assumes rotational symmetry.
@@ -20,10 +28,10 @@ def get_volume(cont, pos_x, pos_y, pix, fix_orientation=False):
     pos_y: float or ndarray of length N
         The y coordinate(s) of the centroid of the event(s) [µm]
         e.g. obtained using `mm.pos_y`
-    pix: float
+    pix
         The detector pixel size in µm.
         e.g. obtained using: `mm.config["imaging"]["pixel size"]`
-    fix_orientation: bool
+    fix_orientation
         If set to True, make sure that the orientation of the
         contour is counter-clockwise in the r-z plane
         (see :func:`vol_revolve`). This is False by default, because
@@ -34,7 +42,7 @@ def get_volume(cont, pos_x, pos_y, pix, fix_orientation=False):
 
     Returns
     -------
-    volume: float or ndarray
+    volume
         volume in um^3
 
     Notes
@@ -43,7 +51,7 @@ def get_volume(cont, pos_x, pos_y, pix, fix_orientation=False):
     upper and the lower halves of the contour from which the
     average is then used.
 
-    The volume is computed radially from the the center position
+    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
@@ -125,7 +133,7 @@ def get_volume(cont, pos_x, pos_y, pix, fix_orientation=False):
     return v_avg
 
 
-def counter_clockwise(cx, cy):
+def counter_clockwise(cx: npt.NDArray, cy: npt.NDArray) -> tuple[float, float]:
     """Put contour coordinates into counter-clockwise order
 
     Parameters
@@ -135,7 +143,7 @@ def counter_clockwise(cx, cy):
 
     Returns
     -------
-    cx_cc, cy_cc:
+    cx_cc, cy_cc
         The x- and y-coordinates of the contour in
         counter-clockwise orientation.
 
@@ -152,7 +160,9 @@ def counter_clockwise(cx, cy):
         return cx, cy
 
 
-def vol_revolve(r, z, point_scale=1.):
+def vol_revolve(r: npt.NDArray,
+                z: npt.NDArray,
+                point_scale: float = 1.) -> float | npt.NDArray:
     r"""Calculate the volume of a polygon revolved around the Z-axis
 
     This implementation yields the same results as the volRevolve
@@ -183,11 +193,11 @@ def vol_revolve(r, z, point_scale=1.):
 
     Parameters
     ----------
-    r: 1d np.ndarray
+    r: 1d ndarray
         radial coordinates (perpendicular to the z axis)
-    z: 1d np.ndarray
+    z: 1d ndarray
         coordinate along the axis of rotation
-    point_scale: float
+    point_scale
         point size in your preferred units; The volume is multiplied
         by a factor of `point_scale**3`.
 
@@ -222,9 +232,9 @@ def vol_revolve(r, z, point_scale=1.):
     # 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
+    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

dclab/http_utils.py

@@ -254,7 +254,7 @@ class ResoluteRequestsSession(requests.Session):
                 break
         else:
             raise requests.exceptions.ReadTimeout(
-                f"Resolut sesion failed for {args} and {kwargs}!")
+                f"Resolute session failed for {args} and {kwargs}!")
         return resp
 
 

dclab/kde/base.py

@@ -1,8 +1,14 @@
 import warnings
 
 import numpy as np
+from scipy.interpolate import RegularGridInterpolator as RGI
 
-from .methods import bin_width_doane, get_bad_vals, methods
+from .methods import bin_width_doane_div5, get_bad_vals, methods
+from .contours import find_contours_level, get_quantile_levels
+
+
+class ContourSpacingTooLarge(UserWarning):
+    pass
 
 
 class KernelDensityEstimator:
@@ -107,6 +113,139 @@ class KernelDensityEstimator:
         yscale: str
             See `xscale`.
 
+        Returns
+        -------
+        X, Y, Z : coordinates
+            The kernel density Z evaluated on a rectangular grid (X,Y).
+        """
+        warnings.warn("`get_contour` is deprecated; please use "
+                      "`get_raster` instead", DeprecationWarning)
+        return self.get_raster(
+            xax=xax, yax=yax, xacc=xacc, yacc=yacc,
+            kde_type=kde_type, kde_kwargs=kde_kwargs,
+            xscale=xscale, yscale=yscale
+        )
+
+    def get_contour_lines(self, quantiles=None, xax="area_um", yax="deform",
+                          xacc=None, yacc=None, kde_type="histogram",
+                          kde_kwargs=None, xscale="linear", yscale="linear",
+                          ret_levels=False):
+        """Compute contour lines for a given kernel kensity estimate.
+
+        Parameters
+        ----------
+        quantiles: list or array of floats
+            KDE Quantiles for which contour levels are computed. The
+            values must be between 0 and 1. If set to None, use
+            [0.5, 0.95] as default.
+        xax: str
+            Identifier for X axis (e.g. "area_um", "aspect", "deform")
+        yax: str
+            Identifier for Y axis
+        xacc: float
+            Contour accuracy in x direction
+            if set to None, will use :func:`bin_width_doane_div5`
+        yacc: float
+            Contour accuracy in y direction
+            if set to None, will use :func:`bin_width_doane_div5`
+        kde_type: str
+            The KDE method to use
+        kde_kwargs: dict
+            Additional keyword arguments to the KDE method
+        xscale: str
+            If set to "log", take the logarithm of the x-values before
+            computing the KDE. This is useful when data are
+            displayed on a log-scale. Defaults to "linear".
+        yscale: str
+            See `xscale`
+        ret_levels: bool
+            If set to True, return the levels of the contours
+            (default: False)
+
+        Returns
+        -------
+        contour_lines: list of lists (of lists)
+            For every number in `quantiles`, this list contains a list of
+            corresponding contour lines. Each contour line is a 2D
+            array of shape (N, 2), where N is the number of points in the
+            contour line.
+        levels: list of floats
+            The density levels corresponding to each number in `quantiles`.
+            Only returned if `ret_levels` is set to True.
+        """
+        if not quantiles:
+            quantiles = [0.5, 0.95]
+        try:
+            x, y, density = self.get_raster(
+                xax=xax,
+                yax=yax,
+                xacc=xacc,
+                yacc=yacc,
+                xscale=xscale,
+                yscale=yscale,
+                kde_type=kde_type,
+                kde_kwargs=kde_kwargs,
+            )
+        except ValueError:
+            # most-likely there is nothing to compute a contour for
+            return []
+        if density.shape[0] < 3 or density.shape[1] < 3:
+            warnings.warn("Contour not possible; spacing may be too large!",
+                          ContourSpacingTooLarge)
+            return []
+        levels = get_quantile_levels(
+            density=density,
+            x=x,
+            y=y,
+            xp=self.rtdc_ds[xax][self.rtdc_ds.filter.all],
+            yp=self.rtdc_ds[yax][self.rtdc_ds.filter.all],
+            q=np.array(quantiles),
+            normalize=False)
+        contours = []
+        # Normalize levels to [0, 1]
+        nlevels = np.array(levels) / density.max()
+        for nlev in nlevels:
+            # make sure that the contour levels are not at the boundaries
+            if not (np.allclose(nlev, 0, atol=1e-12, rtol=0)
+                    or np.allclose(nlev, 1, atol=1e-12, rtol=0)):
+                cc = find_contours_level(
+                    density, x=x, y=y, level=nlev)
+                contours.append(cc)
+            else:
+                contours.append([])
+        if ret_levels:
+            return contours, levels
+        else:
+            return contours
+
+    def get_raster(self, xax="area_um", yax="deform", xacc=None, yacc=None,
+                   kde_type="histogram", kde_kwargs=None, xscale="linear",
+                   yscale="linear"):
+        """Evaluate the kernel density estimate on a grid
+
+        Parameters
+        ----------
+        xax: str
+            Identifier for X axis (e.g. "area_um", "aspect", "deform")
+        yax: str
+            Identifier for Y axis
+        xacc: float
+            Contour accuracy in x direction
+            if set to None, will use :func:`bin_width_doane_div5`
+        yacc: float
+            Contour accuracy in y direction
+            if set to None, will use :func:`bin_width_doane_div5`
+        kde_type: str
+            The KDE method to use
+        kde_kwargs: dict
+            Additional keyword arguments to the KDE method
+        xscale: str
+            If set to "log", take the logarithm of the x-values before
+            computing the KDE. This is useful when data are
+            displayed on a log-scale. Defaults to "linear".
+        yscale: str
+            See `xscale`.
+
         Returns
         -------
         X, Y, Z : coordinates
@@ -128,42 +267,45 @@ class KernelDensityEstimator:
             a=x,
             feat=xax,
             scale=xscale,
-            method=bin_width_doane,
+            method=bin_width_doane_div5,
             ret_scaled=True)
 
         yacc_sc, ys = self.get_spacing(
             a=y,
             feat=yax,
             scale=yscale,
-            method=bin_width_doane,
+            method=bin_width_doane_div5,
             ret_scaled=True)
 
         if xacc is None or xacc == 0:
-            xacc = xacc_sc / 5
+            xacc = xacc_sc
 
         if yacc is None or yacc == 0:
-            yacc = yacc_sc / 5
+            yacc = yacc_sc
 
         # Ignore infs and nans
         bad = get_bad_vals(xs, ys)
         xc = xs[~bad]
         yc = ys[~bad]
 
-        xnum = int(np.ceil((xc.max() - xc.min()) / xacc))
-        ynum = int(np.ceil((yc.max() - yc.min()) / yacc))
+        if xc.size:
+            # Compute the mesh for rastering
+            xnum = int(np.ceil((xc.max() - xc.min()) / xacc))
+            ynum = int(np.ceil((yc.max() - yc.min()) / yacc))
 
-        xlin = np.linspace(xc.min(), xc.max(), xnum, endpoint=True)
-        ylin = np.linspace(yc.min(), yc.max(), ynum, endpoint=True)
+            xlin = np.linspace(xc.min(), xc.max(), xnum, endpoint=True)
+            ylin = np.linspace(yc.min(), yc.max(), ynum, endpoint=True)
 
-        xmesh, ymesh = np.meshgrid(xlin, ylin, indexing="ij")
+            xmesh, ymesh = np.meshgrid(xlin, ylin, indexing="ij")
 
-        kde_fct = methods[kde_type]
-        if len(x):
+            # Compute the KDE for each point on the mesh
+            kde_fct = methods[kde_type]
             density = kde_fct(events_x=xs, events_y=ys,
                               xout=xmesh, yout=ymesh,
                               **kde_kwargs)
         else:
-            density = np.array([])
+            xmesh, ymesh = np.meshgrid([0, 1], [0, 1], indexing="ij")
+            density = np.array(np.nan * xmesh)
 
         # Convert mesh back to linear scale if applicable
         if xscale == "log":
@@ -178,6 +320,8 @@ class KernelDensityEstimator:
                     yscale="linear"):
         """Evaluate the kernel density estimate for scatter plots
 
+        The KDE is evaluated with the `kde_type` function for every point.
+
         Parameters
         ----------
         xax: str
@@ -194,7 +338,7 @@ class KernelDensityEstimator:
             Additional keyword arguments to the KDE method
         xscale: str
             If set to "log", take the logarithm of the x-values before
-            computing the KDE. This is useful when data are are
+            computing the KDE. This is useful when data are
             displayed on a log-scale. Defaults to "linear".
         yscale: str
             See `xscale`.
@@ -236,3 +380,83 @@ class KernelDensityEstimator:
             density = np.array([])
 
         return density
+
+    def get_at(self, xax="area_um", yax="deform", positions=None,
+               kde_type="histogram", kde_kwargs=None, xscale="linear",
+               yscale="linear"):
+        """Evaluate the kernel density estimate for specific events
+
+        The KDE is computed via linear interpolation from the output
+        of `get_raster`.
+
+        Parameters
+        ----------
+        xax: str
+            Identifier for X axis (e.g. "area_um", "aspect", "deform")
+        yax: str
+            Identifier for Y axis
+        positions: list of two 1d ndarrays or ndarray of shape (2, N)
+            The positions where the KDE will be computed. Note that
+            the KDE estimate is computed from the points that
+            are set in `self.rtdc_ds.filter.all`.
+        kde_type: str
+            The KDE method to use, see :const:`.kde_methods.methods`
+        kde_kwargs: dict
+            Additional keyword arguments to the KDE method
+        xscale: str
+            If set to "log", take the logarithm of the x-values before
+            computing the KDE. This is useful when data are
+            displayed on a log-scale. Defaults to "linear".
+        yscale: str
+            See `xscale`.
+
+        Returns
+        -------
+        density : 1d ndarray
+            The kernel density evaluated for the filtered events.
+        """
+        if kde_kwargs is None:
+            kde_kwargs = {}
+        xax = xax.lower()
+        yax = yax.lower()
+        kde_type = kde_type.lower()
+        if kde_type not in methods:
+            raise ValueError(f"Not a valid kde type: {kde_type}!")
+
+        # Get data
+        x = self.rtdc_ds[xax][self.rtdc_ds.filter.all]
+        y = self.rtdc_ds[yax][self.rtdc_ds.filter.all]
+
+        # Apply scale (no change for linear scale)
+        xs = self.apply_scale(x, xscale, xax)
+        ys = self.apply_scale(y, yscale, yax)
+
+        if positions:
+            xs = self.apply_scale(positions[0], xscale, xax)
+            ys = self.apply_scale(positions[1], yscale, yax)
+
+        if len(x):
+            xr, yr, density_grid = self.get_raster(xax=xax,
+                                                   yax=yax,
+                                                   kde_type=kde_type,
+                                                   kde_kwargs=kde_kwargs,
+                                                   xscale=xscale,
+                                                   yscale=yscale)
+
+            # Apply scale (no change for linear scale)
+            xrs = self.apply_scale(xr, xscale, xax)
+            yrs = self.apply_scale(yr, yscale, yax)
+
+            # 'scipy.interp2d' has been removed in SciPy 1.14.0
+            # https://scipy.github.io/devdocs/tutorial/interpolate/interp_transition_guide.html
+            interp_func = RGI((xrs[:, 0], yrs[0, :]),
+                              density_grid,
+                              method="linear",
+                              bounds_error=False,
+                              fill_value=np.nan)
+            density = interp_func((xs, ys))
+
+        else:
+            density = np.array([])
+
+        return density

dclab/kde/methods.py

@@ -1,4 +1,5 @@
 """Kernel Density Estimation methods"""
+import warnings
 
 import numpy as np
 from scipy.interpolate import RectBivariateSpline
@@ -8,6 +9,10 @@ from ..cached import Cache
 from ..external.statsmodels.nonparametric.kernel_density import KDEMultivariate
 
 
+class KernelDensityEstimationForEmtpyArrayWarning(UserWarning):
+    """Used when user attempts to compute KDE for an empty array"""
+
+
 def bin_num_doane(a):
     """Compute number of bins based on Doane's formula
 
@@ -49,13 +54,28 @@ def bin_width_doane(a):
     bad = np.isnan(a) | np.isinf(a)
     data = a[~bad]
     n = data.size
-    g1 = skew(data)
-    sigma_g1 = np.sqrt(6 * (n - 2) / ((n + 1) * (n + 3)))
-    k = 1 + np.log2(n) + np.log2(1 + np.abs(g1) / sigma_g1)
-    acc = (data.max() - data.min()) / k
+    if n > 0:
+        g1 = skew(data)
+        sigma_g1 = np.sqrt(6 * (n - 2) / ((n + 1) * (n + 3)))
+        k = 1 + np.log2(n) + np.log2(1 + np.abs(g1) / sigma_g1)
+        acc = (data.max() - data.min()) / k
+    else:
+        warnings.warn("KDE encountered an empty array",
+                      KernelDensityEstimationForEmtpyArrayWarning)
+        acc = 1
     return acc
 
 
+def bin_width_doane_div5(a):
+    """Compute contour spacing based on Doane's formula divided by five
+
+    See Also
+    --------
+    bin_width_doane: method used to compute the bin width
+    """
+    return bin_width_doane(a) / 5
+
+
 def bin_width_percentile(a):
     """Compute contour spacing based on data percentiles
 
@@ -84,12 +104,12 @@ def get_bad_vals(x, y):
 
 
 def ignore_nan_inf(kde_method):
-    """Ignores nans and infs from the input data
+    """Decorator that computes the KDE only for valid values
 
     Invalid positions in the resulting density are set to nan.
     """
-    def new_kde_method(events_x, events_y, xout=None, yout=None,
-                       *args, **kwargs):
+    def kde_wrapper(events_x, events_y, xout=None, yout=None,
+                    *args, **kwargs):
         bad_in = get_bad_vals(events_x, events_y)
         if xout is None:
             density = np.zeros_like(events_x, dtype=np.float64)
@@ -103,18 +123,19 @@ def ignore_nan_inf(kde_method):
         # Filter events
         ev_x = events_x[~bad_in]
         ev_y = events_y[~bad_in]
-        density[~bad_out] = kde_method(ev_x, ev_y,
-                                       xo, yo,
-                                       *args, **kwargs)
+        if ev_x.size:
+            density[~bad_out] = kde_method(ev_x, ev_y,
+                                           xo, yo,
+                                           *args, **kwargs)
         density[bad_out] = np.nan
         return density
 
     doc_add = "\n    Notes\n" +\
               "    -----\n" +\
               "    This is a wrapped version that ignores nan and inf values."
-    new_kde_method.__doc__ = kde_method.__doc__ + doc_add
+    kde_wrapper.__doc__ = kde_method.__doc__ + doc_add
 
-    return new_kde_method
+    return kde_wrapper
 
 
 @ignore_nan_inf

dclab/rtdc_dataset/config.py

@@ -437,7 +437,7 @@ def load_from_file(cfg_file):
                 convfunc = dfn.get_config_value_func(sec, var)
                 val = convfunc(val)
             else:
-                # unknown parameter (e.g. plotting in Shape-Out), guess type
+                # unknown parameter (e.g. plotting in DCscope), guess type
                 var, val = keyval_str2typ(var, val)
             if len(var) != 0 and len(str(val)) != 0:
                 cfg[sec][var] = val

dclab/rtdc_dataset/core.py

@@ -307,6 +307,9 @@ class RTDCBase(abc.ABC):
                         data = bn.get_feature_data(feat)
                         # The data are available, we may abort the search.
                         break
+                except feat_basin.BasinIdentifierMismatchError:
+                    # Likely a basin identifier mismatch
+                    warnings.warn(traceback.format_exc())
                 except (KeyError, OSError, PermissionError):
                     # Basin data not available
                     pass
@@ -635,7 +638,7 @@ class RTDCBase(abc.ABC):
             The kernel density Z evaluated on a rectangular grid (X,Y).
         """
         kde_instance = KernelDensityEstimator(rtdc_ds=self)
-        xmesh, ymesh, density = kde_instance.get_contour(
+        xmesh, ymesh, density = kde_instance.get_raster(
             xax=xax, yax=yax, xacc=xacc, yacc=yacc, kde_type=kde_type,
             kde_kwargs=kde_kwargs, xscale=xscale, yscale=yscale
         )
@@ -741,11 +744,15 @@ class RTDCBase(abc.ABC):
                 # need the referring dataset.
                 "mapping_referrer": self,
                 # Make sure the measurement identifier is checked.
-                "measurement_identifier": self.get_measurement_identifier(),
+                "referrer_identifier": self.get_measurement_identifier(),
+                # Make sure the basin identifier is checked.
+                "basin_identifier": bdict.get("identifier"),
                 # allow to ignore basins
                 "ignored_basins": bd_keys,
                 # basin key
                 "key": bdict["key"],
+                # whether the basin is perishable or not
+                "perishable": bdict.get("perishable", False),
             }
 
             # Check whether this basin is supported and exists
@@ -783,12 +790,19 @@ class RTDCBase(abc.ABC):
                     b_cls = bc[bdict["format"]]
                     # Try absolute path
                     bna = b_cls(pp, **kwargs)
-                    if bna.verify_basin():
-                        basins.append(bna)
-                        break
+
+                    try:
+                        absolute_exists = bna.verify_basin()
+                    except BaseException:
+                        pass
+                    else:
+                        if absolute_exists:
+                            basins.append(bna)
+                            break
                     # Try relative path
                     this_path = pathlib.Path(self.path)
                     if this_path.exists():
+
                         # Insert relative path
                         bnr = b_cls(this_path.parent / pp, **kwargs)
                         if bnr.verify_basin():
@@ -826,9 +840,9 @@ class RTDCBase(abc.ABC):
         identifier = self.config.get("experiment", {}).get("run identifier",
                                                            None)
         if identifier is None:
-            time = self.config.get("experiment", {}).get("time", None)
-            date = self.config.get("experiment", {}).get("date", None)
-            sid = self.config.get("setup", {}).get("identifier", None)
+            time = self.config.get("experiment", {}).get("time", None) or None
+            date = self.config.get("experiment", {}).get("date", None) or None
+            sid = self.config.get("setup", {}).get("identifier", None) or None
             if None not in [time, date, sid]:
                 # only compute an identifier if all of the above are defined.
                 hasher = hashlib.md5(f"{time}_{date}_{sid}".encode("utf-8"))