dclab 0.64.0__tar.gz → 0.64.1__tar.gz

{dclab-0.64.0 → dclab-0.64.1}/CHANGELOG

@@ -1,3 +1,8 @@
+0.64.1
+ - enh: introduce `KernelDensityEstimator.get_at`
+ - enh: add 10th, 25th, 75th, and 90th percentile statistics methods
+ - enh: new `ret_dict` arg in `get_statistics` returns dict instead of tuple
+ - setup: fix finding packages in pyproject.toml
 0.64.0
  - feat: introduce concept of perishable (e.g. temporally expiring) basins
  - feat: add `PerishableRecord` to presigned URLs for DCOR basins (#244)

{dclab-0.64.0 → dclab-0.64.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: dclab
-Version: 0.64.0
+Version: 0.64.1
 Summary: Library for real-time deformability cytometry (RT-DC)
 Author: Benedikt Hartmann, Eoghan O'Connell, Maik Herbig, Maximilian Schlögel, Nadia Sbaa, Paul Müller, Philipp Rosendahl, Raghava Alajangi
 Maintainer-email: Paul Müller <dev@craban.de>
-License: GPL-2.0-or-later
+License-Expression: GPL-2.0-or-later
 Project-URL: source, https://github.com/DC-Analysis/dclab
 Project-URL: tracker, https://github.com/DC-Analysis/dclab/issues
 Project-URL: documentation, https://dclab.readthedocs.io/en/stable/

{dclab-0.64.0 → dclab-0.64.1}/dclab/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.64.0'
-__version_tuple__ = version_tuple = (0, 64, 0)
+__version__ = version = '0.64.1'
+__version_tuple__ = version_tuple = (0, 64, 1)

{dclab-0.64.0 → dclab-0.64.1}/dclab/kde/base.py

@@ -1,6 +1,7 @@
 import warnings
 
 import numpy as np
+from scipy.interpolate import RegularGridInterpolator as RGI
 
 from .methods import bin_width_doane_div5, get_bad_vals, methods
 from .contours import find_contours_level, get_quantile_levels
@@ -316,6 +317,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
@@ -332,7 +335,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`.
@@ -374,3 +377,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-0.64.0 → dclab-0.64.1}/dclab/statistics.py

@@ -86,7 +86,7 @@ def flow_rate(ds):
         return np.nan
 
 
-def get_statistics(ds, methods=None, features=None):
+def get_statistics(ds, methods=None, features=None, ret_dict=False):
     """Compute statistics for an RT-DC dataset
 
     Parameters
@@ -96,13 +96,16 @@ def get_statistics(ds, methods=None, features=None):
     methods: list of str or None
         The methods wih which to compute the statistics.
         The list of available methods is given with
-        `dclab.statistics.Statistics.available_methods.keys()`
+        :func:`.available_methods.keys`
         If set to `None`, statistics for all methods are computed.
     features: list of str
         Feature name identifiers are defined by
-        `dclab.definitions.feature_exists`.
+        :func:`dclab.definitions.feature_exists`.
         If set to `None`, statistics for all scalar features
         available are computed.
+    ret_dict: bool
+        Instead of returning ``(header, values)``, return a dictionary
+        with headers as keys.
 
     Returns
     -------
@@ -148,7 +151,10 @@ def get_statistics(ds, methods=None, features=None):
                 label = dfn.get_feature_label(ft, rtdc_ds=ds)
                 header.append(" ".join([mt, label]))
 
-    return header, values
+    if ret_dict:
+        return dict(zip(header, values))
+    else:
+        return header, values
 
 
 def mode(data):
@@ -191,7 +197,24 @@ def mode(data):
 # Register all the methods
 # Methods that require an axis
 Statistics(name="Mean",   req_feature=True, method=np.average)
+# Premature-Optimization warning: `np.percentile` also accepts an array
+# of percentiles as the `q` argument, which I would expect to yield better
+# performance than computing percentiles individually. Implementing this
+# would break the way we are defining statistical methods here (One
+# `Statistics` instance per method) and thus requires a considerable
+# amount of work (much more work than writing this text here). It would
+# also make understanding the code more difficult. In addition, computing
+# statistics is not done often and is extremely fast anyway for a few
+# millions of events. Don't optimize this!
+Statistics(name="10th Percentile", req_feature=True,
+           method=lambda data: np.percentile(data, 10))
+Statistics(name="25th Percentile", req_feature=True,
+           method=lambda data: np.percentile(data, 25))
 Statistics(name="Median", req_feature=True, method=np.median)
+Statistics(name="75th Percentile", req_feature=True,
+           method=lambda data: np.percentile(data, 75))
+Statistics(name="90th Percentile", req_feature=True,
+           method=lambda data: np.percentile(data, 90))
 Statistics(name="Mode",   req_feature=True, method=mode)
 Statistics(name="SD",     req_feature=True, method=np.std)
 # Methods that work on RTDCBase

{dclab-0.64.0 → dclab-0.64.1}/dclab.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: dclab
-Version: 0.64.0
+Version: 0.64.1
 Summary: Library for real-time deformability cytometry (RT-DC)
 Author: Benedikt Hartmann, Eoghan O'Connell, Maik Herbig, Maximilian Schlögel, Nadia Sbaa, Paul Müller, Philipp Rosendahl, Raghava Alajangi
 Maintainer-email: Paul Müller <dev@craban.de>
-License: GPL-2.0-or-later
+License-Expression: GPL-2.0-or-later
 Project-URL: source, https://github.com/DC-Analysis/dclab
 Project-URL: tracker, https://github.com/DC-Analysis/dclab/issues
 Project-URL: documentation, https://dclab.readthedocs.io/en/stable/

{dclab-0.64.0 → dclab-0.64.1}/pyproject.toml

@@ -34,7 +34,7 @@ classifiers = [
     'Topic :: Scientific/Engineering :: Visualization',
     'Intended Audience :: Science/Research',
 ]
-license = {text = "GPL-2.0-or-later"}
+license = "GPL-2.0-or-later"
 # This is not supported in Python 3.8
 # license = "GPL-2.0-or-later"
 dependencies = [
@@ -75,8 +75,8 @@ changelog = "https://dclab.readthedocs.io/en/stable/sec_changelog.html"
 # We need the following, because automatic package discovery does not work
 # when running cibuildwheel on GitHub Actions (there will be a "wheelhouse"
 # directory).
-[tool.setuptools]
-packages = ["dclab"]
+[tool.setuptools.packages.find]
+include = ["dclab"]
 
 [tool.setuptools_scm]
 write_to = "dclab/_version.py"

{dclab-0.64.0 → dclab-0.64.1}/tests/test_kde.py

@@ -5,6 +5,8 @@ from dclab.external import skimage
 from dclab.kde import KernelDensityEstimator
 from dclab import polygon_filter
 
+from helper_methods import example_data_dict
+
 
 def test_contour_lines():
     np.random.seed(47)
@@ -99,3 +101,71 @@ def test_contour_lines_data_with_too_much_space():
                                               yscale="linear",
                                               quantiles=[0.5])
     assert not contours, "there should be no contours with too much space"
+
+
+def test_kde_log_get_at():
+    ddict = example_data_dict(size=300, keys=["area_um", "deform"])
+    ddict["deform"][:20] = .1
+    ddict["area_um"][:20] = .5
+    ds = dclab.new_dataset(ddict)
+    kde_instance = KernelDensityEstimator(ds)
+    a = kde_instance.get_at(xax="area_um", yax="deform", yscale="log")
+    assert np.all(a[:20] == a[0])
+
+
+def test_kde_log_get_at_points():
+    ddict = example_data_dict(size=300, keys=["area_um", "tilt"])
+    ds = dclab.new_dataset(ddict)
+    kde_instance = KernelDensityEstimator(ds)
+    a = kde_instance.get_at(yscale="log", xax="area_um", yax="tilt")
+    b = kde_instance.get_at(yscale="log", xax="area_um", yax="tilt")
+
+    assert np.all(a == b)
+
+
+def test_kde_log_get_at_invalid():
+    ddict = example_data_dict(size=300, keys=["area_um", "deform"])
+    ddict["deform"][:20] = .1
+    ddict["area_um"][:20] = .5
+    ddict["deform"][21] = np.nan
+    ddict["deform"][22] = np.inf
+    ddict["deform"][23] = -.1
+    ds = dclab.new_dataset(ddict)
+    kde_instance = KernelDensityEstimator(ds)
+    a = kde_instance.get_at(xax="area_um", yax="deform", yscale="log")
+    assert np.all(a[:20] == a[0])
+    assert np.isnan(a[21])
+    assert np.isnan(a[22])
+    assert np.isnan(a[23])
+
+
+def test_kde_get_at_positions():
+    ddict = example_data_dict()
+    ds = dclab.new_dataset(ddict)
+
+    kde_instance = KernelDensityEstimator(ds)
+
+    ds.config["filtering"]["enable filters"] = False
+    sc = kde_instance.get_at(xax="area_um", yax="deform")
+    sc2 = kde_instance.get_at(xax="area_um", yax="deform",
+                              positions=(ds["area_um"], ds["deform"]))
+    assert np.all(sc == sc2)
+
+
+def test_kde_log_get_at_out_of_bounds():
+    ddict = example_data_dict(size=300, keys=["area_um", "deform"])
+    ds = dclab.new_dataset(ddict)
+    kde_instance = KernelDensityEstimator(ds)
+
+    # Define a positions that has values outside the typical data range
+    # `area_um` ([0.0, 400]) and `deform` ([0.0, 0.02])
+    positions = ([410, 300, 300, 300],
+                 [-1, -2, 0.01, 0.015])
+
+    # Get the density at the out-of-bounds position
+    a = kde_instance.get_at(xax="area_um", yax="deform",
+                            positions=positions, yscale="log")
+    assert np.isnan(a[0])
+    assert np.isnan(a[1])
+    assert np.isfinite(a[2])
+    assert np.isfinite(a[3])

{dclab-0.64.0 → dclab-0.64.1}/tests/test_statistics.py

@@ -99,6 +99,21 @@ def test_false_method():
             break
 
 
+def test_percentiles():
+    ddict = example_data_dict(size=1_000, keys=["area_um", "deform"])
+    np.random.seed(42)
+    ddict["userdef1"] = np.random.random(1_000)
+    ds = dclab.new_dataset(ddict)
+    stats = dclab.statistics.get_statistics(ds, ret_dict=True)
+    for pp in [10, 25, 75, 90]:
+        # We have one thousand events in the userdef1 feature that are
+        # evenly distributed between 0 and 1. We allow an error of 5%
+        # relative to 1, which should be sufficient to capture the
+        # randomness.
+        assert np.allclose(stats[f"{pp}th Percentile User-defined 1"], pp/100,
+                           rtol=0, atol=0.05)
+
+
 def test_stats_without_features():
     ddict = example_data_dict(size=5085, keys=["area_um", "deform"])
     ds = dclab.new_dataset(ddict)