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

dclab/features/emodulus/pxcorr.py

@@ -1,9 +1,12 @@
 """Pixelation correction definitions"""
+from __future__ import annotations
 
 import numpy as np
+import numpy.typing as npt
 
 
-def corr_deform_with_area_um(area_um, px_um=0.34):
+def corr_deform_with_area_um(area_um: float | npt.NDArray,
+                             px_um: float = 0.34) -> float | npt.NDArray:
     """Deformation correction for area_um-deform data
 
     The contour in RT-DC measurements is computed on a
@@ -14,14 +17,14 @@ def corr_deform_with_area_um(area_um, px_um=0.34):
 
     Parameters
     ----------
-    area_um: float or ndarray
-        Apparent (2D image) area in µm² of the event(s)
-    px_um: float
+    area_um
+        Area of the event(s) in µm²
+    px_um
         The detector pixel size in µm.
 
     Returns
     -------
-    deform_delta: float or ndarray
+    deform_delta
         Error of the deformation of the event(s) that must be
         subtracted from `deform`.
         deform_corr = deform -  deform_delta
@@ -46,7 +49,8 @@ def corr_deform_with_area_um(area_um, px_um=0.34):
     return delta
 
 
-def corr_deform_with_volume(volume, px_um=0.34):
+def corr_deform_with_volume(volume: float | npt.NDArray,
+                            px_um: float = 0.34) -> float | npt.NDArray:
     """Deformation correction for volume-deform data
 
     The contour in RT-DC measurements is computed on a
@@ -57,14 +61,14 @@ def corr_deform_with_volume(volume, px_um=0.34):
 
     Parameters
     ----------
-    volume: float or ndarray
+    volume
         The "volume" feature (rotation of raw contour) [µm³]
-    px_um: float
+    px_um
         The detector pixel size in µm.
 
     Returns
     -------
-    deform_delta: float or ndarray
+    deform_delta
         Error of the deformation of the event(s) that must be
         subtracted from `deform`.
         deform_corr = deform -  deform_delta
@@ -78,7 +82,13 @@ def corr_deform_with_volume(volume, px_um=0.34):
     return delta
 
 
-def get_pixelation_delta_pair(feat1, feat2, data1, data2, px_um=0.34):
+def get_pixelation_delta_pair(
+        feat1: str,
+        feat2: str,
+        data1: float | npt.NDArray,
+        data2: float | npt.NDArray,
+        px_um: float = 0.34) -> (tuple[float, float] |
+                                 tuple[npt.NDArray, npt.NDArray]):
     """Convenience function that returns pixelation correction pair"""
     # determine feature that defines abscissa
     feat_absc = feat1 if feat1 in ["area_um", "volume"] else feat2
@@ -97,20 +107,28 @@ def get_pixelation_delta_pair(feat1, feat2, data1, data2, px_um=0.34):
     return delt1, delt2
 
 
-def get_pixelation_delta(feat_corr, feat_absc, data_absc, px_um=0.34):
+def get_pixelation_delta(feat_corr: str,
+                         feat_absc: str,
+                         data_absc: float | npt.NDArray,
+                         px_um: float = 0.34) -> float | npt.NDArray:
     """Convenience function for obtaining pixelation correction
 
     Parameters
     ----------
-    feat_corr: str
+    feat_corr
         Feature for which to compute the pixelation correction
         (e.g. "deform")
-    feat_absc: str
+    feat_absc
         Feature with which to compute the correction (e.g. "area_um");
-    data_absc: ndarray or float
+    data_absc
         Corresponding data for `feat_absc`
-    px_um: float
+    px_um
         Detector pixel size [µm]
+
+    Returns
+    -------
+    For details see :func:`corr_deform_with_area_um` and
+    :func:`corr_deform_with_volume`.
     """
     if feat_corr == "deform" and feat_absc == "area_um":
         delt = corr_deform_with_area_um(data_absc, px_um=px_um)

dclab/features/emodulus/scale_linear.py

@@ -1,47 +1,60 @@
 """Scale conversion applicable to a linear elastic model"""
+from __future__ import annotations
 
 import warnings
 
 import numpy as np
-
-
-def convert(area_um, deform, channel_width_in, channel_width_out,
-            emodulus=None, flow_rate_in=None, flow_rate_out=None,
-            viscosity_in=None, viscosity_out=None, inplace=False):
-    """convert area-deformation-emodulus triplet
+import numpy.typing as npt
+
+
+def convert(area_um: npt.NDArray,
+            deform: npt.NDArray,
+            channel_width_in: float,
+            channel_width_out: float,
+            emodulus: npt.NDArray = None,
+            flow_rate_in: float = None,
+            flow_rate_out: float = None,
+            viscosity_in: float = None,
+            viscosity_out: float | npt.NDArray = None,
+            inplace: bool = False
+            ) -> (
+        tuple[npt.NDArray, npt.NDArray] |
+        tuple[npt.NDArray, npt.NDArray, npt.NDArray]
+):
+    """Convert area-deformation-emodulus triplet
 
     The conversion formula is described in :cite:`Mietke2015`.
 
     Parameters
     ----------
-    area_um: ndarray
+    area_um
         Convex cell area [µm²]
-    deform: ndarray
+    deform
         Deformation
-    channel_width_in: float
+    channel_width_in
         Original channel width [µm]
-    channel_width_out: float
+    channel_width_out
         Target channel width [µm]
-    emodulus: ndarray
+    emodulus
         Young's Modulus [kPa]
-    flow_rate_in: float
+    flow_rate_in
         Original flow rate [µL/s]
-    flow_rate_out: float
+    flow_rate_out
         Target flow rate [µL/s]
-    viscosity_in: float
+    viscosity_in
         Original viscosity [mPa*s]
-    viscosity_out: float or ndarray
+    viscosity_out
         Target viscosity [mPa*s]; This can be an array
-    inplace: bool
+    inplace
         If True, override input arrays with corrected data
 
     Returns
     -------
-    area_um_corr: ndarray
+    area_um_corr
         Corrected cell area [µm²]
-    deform_corr: ndarray
+    deform_corr
         Deformation (a copy if `inplace` is False)
-    emodulus_corr: ndarray
+    emodulus_corr
         Corrected emodulus [kPa]; only returned if `emodulus` is given.
 
     Notes
@@ -81,8 +94,11 @@ def convert(area_um, deform, channel_width_in, channel_width_out,
         return area_um_corr, deform_corr, emodulus_corr
 
 
-def scale_area_um(area_um, channel_width_in, channel_width_out, inplace=False,
-                  **kwargs):
+def scale_area_um(area_um: npt.NDArray,
+                  channel_width_in: float,
+                  channel_width_out: float,
+                  inplace: bool = False,
+                  **kwargs) -> npt.NDArray:
     """Perform scale conversion for area_um (linear elastic model)
 
     The area scales with the characteristic length
@@ -94,20 +110,20 @@ def scale_area_um(area_um, channel_width_in, channel_width_out, inplace=False,
 
     Parameters
     ----------
-    area_um: ndarray
+    area_um
         Convex area [µm²]
-    channel_width_in: float
+    channel_width_in
         Original channel width [µm]
-    channel_width_out: float
+    channel_width_out
         Target channel width [µm]
-    inplace: bool
+    inplace
         If True, override input arrays with corrected data
-    kwargs:
+    kwargs
         not used
 
     Returns
     -------
-    area_um_corr: ndarray
+    area_um_corr
         Scaled area [µm²]
     """
     copy = not inplace
@@ -120,9 +136,14 @@ def scale_area_um(area_um, channel_width_in, channel_width_out, inplace=False,
     return area_um_corr
 
 
-def scale_emodulus(emodulus, channel_width_in, channel_width_out,
-                   flow_rate_in, flow_rate_out, viscosity_in,
-                   viscosity_out, inplace=False):
+def scale_emodulus(emodulus: npt.NDArray,
+                   channel_width_in: float,
+                   channel_width_out: float,
+                   flow_rate_in: float,
+                   flow_rate_out: float,
+                   viscosity_in: float,
+                   viscosity_out: float | npt.NDArray,
+                   inplace: bool = False) -> npt.NDArray:
     """Perform scale conversion for area_um (linear elastic model)
 
     The conversion formula is described in :cite:`Mietke2015`.
@@ -131,26 +152,26 @@ def scale_emodulus(emodulus, channel_width_in, channel_width_out,
 
     Parameters
     ----------
-    emodulus: ndarray
+    emodulus
         Young's Modulus [kPa]
-    channel_width_in: float
+    channel_width_in
         Original channel width [µm]
-    channel_width_out: float
+    channel_width_out
         Target channel width [µm]
-    flow_rate_in: float
+    flow_rate_in
         Original flow rate [µL/s]
-    flow_rate_out: float
+    flow_rate_out
         Target flow rate [µL/s]
-    viscosity_in: float
+    viscosity_in
         Original viscosity [mPa*s]
-    viscosity_out: float or ndarray
+    viscosity_out
         Target viscosity [mPa*s]; This can be an array
-    inplace: bool
+    inplace
         If True, override input arrays with corrected data
 
     Returns
     -------
-    emodulus_corr: ndarray
+    emodulus_corr
         Scaled emodulus [kPa]
     """
     copy = not inplace
@@ -182,7 +203,10 @@ def scale_emodulus(emodulus, channel_width_in, channel_width_out,
     return emodulus_corr
 
 
-def scale_feature(feat, data, inplace=False, **scale_kw):
+def scale_feature(feat: str,
+                  data: float | npt.NDArray,
+                  inplace: bool = False,
+                  **scale_kw) -> npt.NDArray:
     """Convenience function for scale conversions (linear elastic model)
 
     This method wraps around all the other scale_* methods and also
@@ -190,13 +214,13 @@ def scale_feature(feat, data, inplace=False, **scale_kw):
 
     Parameters
     ----------
-    feat: str
+    feat
         Valid scalar feature name
-    data: float or ndarray
+    data
         Feature data
-    inplace: bool
+    inplace
         If True, override input arrays with corrected data
-    **scale_kw:
+    **scale_kw
         Scale keyword arguments for the wrapped methods
     """
     if feat == "area_um":
@@ -212,8 +236,11 @@ def scale_feature(feat, data, inplace=False, **scale_kw):
         raise KeyError("No recipe to scale feature '{}'!".format(feat))
 
 
-def scale_volume(volume, channel_width_in, channel_width_out, inplace=False,
-                 **kwargs):
+def scale_volume(volume: npt.NDArray,
+                 channel_width_in: float,
+                 channel_width_out: float,
+                 inplace: bool = False,
+                 **kwargs) -> npt.NDArray:
     """Perform scale conversion for volume (linear elastic model)
 
     The volume scales with the characteristic length
@@ -223,20 +250,20 @@ def scale_volume(volume, channel_width_in, channel_width_out, inplace=False,
 
     Parameters
     ----------
-    volume: ndarray
+    volume
         Volume [µm³]
-    channel_width_in: float
+    channel_width_in
         Original channel width [µm]
-    channel_width_out: float
+    channel_width_out
         Target channel width [µm]
-    inplace: bool
+    inplace
         If True, override input arrays with corrected data
-    kwargs:
+    kwargs
         not used
 
     Returns
     -------
-    volume_corr: ndarray
+    volume_corr
         Scaled volume [µm³]
     """
     copy = not inplace

dclab/features/emodulus/viscosity.py

@@ -5,6 +5,7 @@ from typing import Literal
 import warnings
 
 import numpy as np
+import numpy.typing as npt
 
 from ...warn import PipelineWarning
 
@@ -45,10 +46,17 @@ class TemperatureOutOfRangeWarning(PipelineWarning):
 
 
 def check_temperature(model: str,
-                      temperature: float | np.array,
+                      temperature: float | npt.NDArray,
                       tmin: float,
-                      tmax: float):
-    """Raise a TemperatureOutOfRangeWarning if applicable"""
+                      tmax: float) -> None:
+    """Raise a TemperatureOutOfRangeWarning if applicable
+
+    Raises
+    ------
+    TemperatureOutOfRangeWarning
+        If the given temperature is out of the given range.
+
+    """
     if np.min(temperature) < tmin or np.max(temperature) > tmax:
         warnings.warn(
             f"For the {model} model, the temperature should be "
@@ -60,11 +68,12 @@ def check_temperature(model: str,
 def get_viscosity(medium: str = "0.49% MC-PBS",
                   channel_width: float = 20.0,
                   flow_rate: float = 0.16,
-                  temperature: float | np.ndarray = 23.0,
+                  temperature: float | npt.NDArray = 23.0,
                   model: Literal['herold-2017',
                                  'herold-2017-fallback',
                                  'buyukurganci-2022',
-                                 'kestin-1978'] = 'herold-2017-fallback'):
+                                 'kestin-1978'] = 'herold-2017-fallback'
+                  ) -> float | npt.NDArray:
     """Returns the viscosity for RT-DC-specific media
 
     Media that are not pure (e.g. ketchup or polymer solutions)
@@ -83,16 +92,16 @@ def get_viscosity(medium: str = "0.49% MC-PBS",
 
     Parameters
     ----------
-    medium: str
+    medium
         The medium to compute the viscosity for; Valid values
         are defined in :const:`KNOWN_MEDIA`.
-    channel_width: float
+    channel_width
         The channel width in µm
-    flow_rate: float
+    flow_rate
         Flow rate in µL/s
-    temperature: float or ndarray
+    temperature
         Temperature in °C
-    model: str
+    model
         The model name to use for computing the medium viscosity.
         For water, this value is ignored, as there is only the
         'kestin-1978' model :cite:`Kestin_1978`. For MC-PBS media,
@@ -101,7 +110,7 @@ def get_viscosity(medium: str = "0.49% MC-PBS",
 
     Returns
     -------
-    viscosity: float or ndarray
+    viscosity
         Viscosity in mPa*s
 
     Notes
@@ -152,21 +161,23 @@ def get_viscosity(medium: str = "0.49% MC-PBS",
     return eta
 
 
-def shear_rate_square_channel(flow_rate, channel_width, flow_index):
+def shear_rate_square_channel(flow_rate: float,
+                              channel_width: float,
+                              flow_index: float) -> float:
     """Returns The wall shear rate of a power law liquid in a squared channel.
 
     Parameters
     ----------
-    flow_rate: float
+    flow_rate
         Flow rate in µL/s
-    channel_width: float
+    channel_width
         The channel width in µm
-    flow_index: float
+    flow_index
         Flow behavior index aka the power law exponent of the shear thinning
 
     Returns
     -------
-    shear_rate: float
+    shear_rate
         Shear rate in 1/s.
     """
     # convert channel width to mm
@@ -180,7 +191,7 @@ def get_viscosity_mc_pbs_buyukurganci_2022(
                         "0.83% MC-PBS"] = "0.49% MC-PBS",
         channel_width: float = 20.0,
         flow_rate: float = 0.16,
-        temperature: float = 23.0):
+        temperature: float = 23.0) -> float | npt.NDArray:
     """Compute viscosity of MC-PBS according to :cite:`Buyukurganci2022`
 
     This viscosity model was derived in :cite:`Buyukurganci2022`
@@ -215,7 +226,7 @@ def get_viscosity_mc_pbs_herold_2017(
         medium: Literal["0.49% MC-PBS", "0.59% MC-PBS"] = "0.49% MC-PBS",
         channel_width: float = 20.0,
         flow_rate: float = 0.16,
-        temperature: float = 23.0):
+        temperature: float = 23.0) -> float | npt.NDArray:
     r"""Compute viscosity of MC-PBS according to :cite:`Herold2017`
 
     Note that all the factors in equation 5.2 in :cite:`Herold2017`
@@ -246,7 +257,8 @@ def get_viscosity_mc_pbs_herold_2017(
     return eta
 
 
-def get_viscosity_water_kestin_1978(temperature: float = 23.0):
+def get_viscosity_water_kestin_1978(
+        temperature: float | npt.NDArray = 23.0) -> float | npt.NDArray:
     """Compute the viscosity of water according to :cite:`Kestin_1978`"""
     # see equation (15) in Kestin et al, J. Phys. Chem. 7(3) 1978
     check_temperature("'kestin-1978' water", temperature, 0, 40)

dclab/features/fl_crosstalk.py

@@ -1,9 +1,13 @@
 """Crosstalk-correction for fluorescence data"""
+from __future__ import annotations
 
 import numpy as np
+import numpy.typing as npt
 
 
-def get_compensation_matrix(ct21, ct31, ct12, ct32, ct13, ct23):
+def get_compensation_matrix(
+        ct21: float, ct31: float, ct12: float,
+        ct32: float, ct13: float, ct23: float) -> npt.NDArray:
     """Compute crosstalk inversion matrix
 
     The spillover matrix is
@@ -18,12 +22,12 @@ def get_compensation_matrix(ct21, ct31, ct12, ct32, ct13, ct23):
 
     Parameters
     ----------
-    cij: float
+    cij
         Spill from channel i to channel j
 
     Returns
     -------
-    inv: np.ndarray
+    inv
         Compensation matrix (inverted spillover matrix)
     """
     ct11 = 1
@@ -55,18 +59,23 @@ def get_compensation_matrix(ct21, ct31, ct12, ct32, ct13, ct23):
     return np.linalg.inv(crosstalk)
 
 
-def correct_crosstalk(fl1, fl2, fl3, fl_channel,
-                      ct21=0, ct31=0, ct12=0, ct32=0, ct13=0, ct23=0):
+def correct_crosstalk(
+        fl1: int | float | npt.NDArray,
+        fl2: int | float | npt.NDArray,
+        fl3: int | float | npt.NDArray,
+        fl_channel: int,
+        ct21: float = 0, ct31: float = 0, ct12: float = 0,
+        ct32: float = 0, ct13: float = 0, ct23: float = 0) -> npt.NDArray:
     """Perform crosstalk correction
 
     Parameters
     ----------
-    fli: int, float, or np.ndarray
+    fli
         Measured fluorescence signals
-    fl_channel: int (1, 2, or 3)
-        The channel number for which the crosstalk-corrected signal
-        should be computed
-    cij: float
+    fl_channel
+        The channel number (1, 2, or 3) for which the crosstalk-corrected
+        signal should be computed
+    cij
         Spill (crosstalk or bleed-through) from channel i to channel j
         This spill is computed from the fluorescence signal of e.g.
         single-stained positive control cells; It is defined by the

dclab/features/inert_ratio.py

@@ -1,11 +1,14 @@
 """Computation of inertia ratio from contour data"""
+from __future__ import annotations
+
 import numpy as np
+import numpy.typing as npt
 import scipy.spatial as ssp
 
 
-def cont_moments_cv(cont,
-                    flt_epsilon=1.19209e-07,
-                    dbl_epsilon=2.2204460492503131e-16):
+def cont_moments_cv(cont: npt.NDArray,
+                    flt_epsilon: float = 1.19209e-07,
+                    dbl_epsilon: float = 2.2204460492503131e-16) -> dict:
     """Compute the moments of a contour
 
     The moments are computed in the same way as they are computed
@@ -13,11 +16,11 @@ def cont_moments_cv(cont,
 
     Parameters
     ----------
-    cont: array of shape (N,2)
+    cont: ndarray of shape (N,2)
         The contour for which to compute the moments.
-    flt_epsilon: float
+    flt_epsilon
         The value of ``FLT_EPSILON`` in OpenCV/gcc.
-    dbl_epsilon: float
+    dbl_epsilon
         The value of ``DBL_EPSILON`` in OpenCV/gcc.
 
     .. versionchanged:: 0.48.2
@@ -28,7 +31,7 @@ def cont_moments_cv(cont,
 
     Returns
     -------
-    moments: dict
+    moments
         A dictionary of moments. If the moment `m00` is smaller
         than half of `flt_epsilon`, `None` is returned.
     """
@@ -120,7 +123,8 @@ def cont_moments_cv(cont,
         return None
 
 
-def get_inert_ratio_cvx(cont):
+def get_inert_ratio_cvx(
+        cont: npt.NDArray | list[npt.NDArray]) -> float | npt.NDArray:
     """Compute the inertia ratio of the convex hull of a contour
 
     The inertia ratio is computed from the central second order of moments
@@ -190,7 +194,8 @@ def get_inert_ratio_cvx(cont):
     return inert_ratio_cvx
 
 
-def get_inert_ratio_prnc(cont):
+def get_inert_ratio_prnc(
+        cont: npt.NDArray | list[npt.NDArray]) -> float | npt.NDArray:
     """Compute principal inertia ratio of a contour
 
     The principal inertia ratio is rotation-invariant, which
@@ -256,7 +261,8 @@ def get_inert_ratio_prnc(cont):
     return inert_ratio_prnc
 
 
-def get_inert_ratio_raw(cont):
+def get_inert_ratio_raw(
+        cont: npt.NDArray | list[npt.NDArray]) -> float | npt.NDArray:
     """Compute the inertia ratio of a contour
 
     The inertia ratio is computed from the central second order of moments
@@ -321,7 +327,8 @@ def get_inert_ratio_raw(cont):
     return inert_ratio_raw
 
 
-def get_tilt(cont):
+def get_tilt(
+        cont: npt.NDArray | list[npt.NDArray]) -> float | npt.NDArray:
     """Compute tilt of raw contour relative to channel axis
 
     Parameters