dclab 0.67.0__cp314-cp314t-macosx_11_0_arm64.whl

dclab/features/emodulus/pxcorr.py

@@ -0,0 +1,135 @@
+"""Pixelation correction definitions"""
+
+import numpy as np
+
+
+def corr_deform_with_area_um(area_um, px_um=0.34):
+    """Deformation correction for area_um-deform data
+
+    The contour in RT-DC measurements is computed on a
+    pixelated grid. Due to sampling problems, the measured
+    deformation is overestimated and must be corrected.
+
+    The correction formula is described in :cite:`Herold2017`.
+
+    Parameters
+    ----------
+    area_um: float or ndarray
+        Apparent (2D image) area in µm² of the event(s)
+    px_um: float
+        The detector pixel size in µm.
+
+    Returns
+    -------
+    deform_delta: float or ndarray
+        Error of the deformation of the event(s) that must be
+        subtracted from `deform`.
+        deform_corr = deform -  deform_delta
+    """
+    # A triple-exponential decay can be used to correct for pixelation
+    # for apparent cell areas between 10 and 1250µm².
+    # For 99 different radii between 0.4 μm and 20 μm circular objects were
+    # simulated on a pixel grid with the pixel resolution of 340 nm/pix. At
+    # each radius 1000 random starting points were created and the
+    # obtained contours were analyzed in the same fashion as RT-DC data.
+    # A convex hull on the contour was used to calculate the size (as area)
+    # and the deformation.
+    # The pixel size correction `pxscale` takes into account the pixel size
+    # in the pixelation correction formula.
+    pxscale = (.34 / px_um)**2
+    offs = 0.0012
+    exp1 = 0.020 * np.exp(-area_um * pxscale / 7.1)
+    exp2 = 0.010 * np.exp(-area_um * pxscale / 38.6)
+    exp3 = 0.005 * np.exp(-area_um * pxscale / 296)
+    delta = offs + exp1 + exp2 + exp3
+
+    return delta
+
+
+def corr_deform_with_volume(volume, px_um=0.34):
+    """Deformation correction for volume-deform data
+
+    The contour in RT-DC measurements is computed on a
+    pixelated grid. Due to sampling problems, the measured
+    deformation is overestimated and must be corrected.
+
+    The correction is derived in scripts/pixelation_correction.py.
+
+    Parameters
+    ----------
+    volume: float or ndarray
+        The "volume" feature (rotation of raw contour) [µm³]
+    px_um: float
+        The detector pixel size in µm.
+
+    Returns
+    -------
+    deform_delta: float or ndarray
+        Error of the deformation of the event(s) that must be
+        subtracted from `deform`.
+        deform_corr = deform -  deform_delta
+    """
+    pxscalev = (.34 / px_um)**3
+    offs = 0.0013
+    exp1 = 0.0172 * np.exp(-volume * pxscalev / 40)
+    exp2 = 0.0070 * np.exp(-volume * pxscalev / 450)
+    exp3 = 0.0032 * np.exp(-volume * pxscalev / 6040)
+    delta = offs + exp1 + exp2 + exp3
+    return delta
+
+
+def get_pixelation_delta_pair(feat1, feat2, data1, data2, px_um=0.34):
+    """Convenience function that returns pixelation correction pair"""
+    # determine feature that defines abscissa
+    feat_absc = feat1 if feat1 in ["area_um", "volume"] else feat2
+    data_absc = data1 if feat_absc == feat1 else data2
+    # first compute all the possible pixelation offsets
+    delt1 = get_pixelation_delta(
+        feat_corr=feat1,
+        feat_absc=feat_absc,
+        data_absc=data_absc,
+        px_um=px_um)
+    delt2 = get_pixelation_delta(
+        feat_corr=feat2,
+        feat_absc=feat_absc,
+        data_absc=data_absc,
+        px_um=px_um)
+    return delt1, delt2
+
+
+def get_pixelation_delta(feat_corr, feat_absc, data_absc, px_um=0.34):
+    """Convenience function for obtaining pixelation correction
+
+    Parameters
+    ----------
+    feat_corr: str
+        Feature for which to compute the pixelation correction
+        (e.g. "deform")
+    feat_absc: str
+        Feature with which to compute the correction (e.g. "area_um");
+    data_absc: ndarray or float
+        Corresponding data for `feat_absc`
+    px_um: float
+        Detector pixel size [µm]
+    """
+    if feat_corr == "deform" and feat_absc == "area_um":
+        delt = corr_deform_with_area_um(data_absc, px_um=px_um)
+    elif feat_corr == "circ" and feat_absc == "area_um":
+        delt = -corr_deform_with_area_um(data_absc, px_um=px_um)
+    elif feat_corr == "deform" and feat_absc == "volume":
+        delt = corr_deform_with_volume(data_absc, px_um=px_um)
+    elif feat_corr == "circ" and feat_absc == "volume":
+        delt = -corr_deform_with_volume(data_absc, px_um=px_um)
+    elif feat_corr == "area_um":
+        # no correction for area
+        delt = np.zeros_like(data_absc, dtype=float)
+    elif feat_corr == "volume":
+        # no correction for volume
+        delt = np.zeros_like(data_absc, dtype=float)
+    elif feat_corr == feat_absc:
+        raise ValueError("Input feature names are identical!")
+    else:
+        raise KeyError(
+            "No rule for feature '{}' with abscissa ".format(feat_corr)
+            + "'{}'!".format(feat_absc))
+    return delt

dclab/features/emodulus/scale_linear.py

@@ -0,0 +1,247 @@
+"""Scale conversion applicable to a linear elastic model"""
+
+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
+
+    The conversion formula is described in :cite:`Mietke2015`.
+
+    Parameters
+    ----------
+    area_um: ndarray
+        Convex cell area [µm²]
+    deform: ndarray
+        Deformation
+    channel_width_in: float
+        Original channel width [µm]
+    channel_width_out: float
+        Target channel width [µm]
+    emodulus: ndarray
+        Young's Modulus [kPa]
+    flow_rate_in: float
+        Original flow rate [µL/s]
+    flow_rate_out: float
+        Target flow rate [µL/s]
+    viscosity_in: float
+        Original viscosity [mPa*s]
+    viscosity_out: float or ndarray
+        Target viscosity [mPa*s]; This can be an array
+    inplace: bool
+        If True, override input arrays with corrected data
+
+    Returns
+    -------
+    area_um_corr: ndarray
+        Corrected cell area [µm²]
+    deform_corr: ndarray
+        Deformation (a copy if `inplace` is False)
+    emodulus_corr: ndarray
+        Corrected emodulus [kPa]; only returned if `emodulus` is given.
+
+    Notes
+    -----
+    If only `area_um`, `deform`, `channel_width_in` and
+    `channel_width_out` are given, then only the area is
+    corrected and returned together with the original deform.
+    If all other arguments are not set to None, the emodulus
+    is corrected and returned as well.
+    """
+    warnings.warn("Usage of the `convert` method is deprecated! Please use "
+                  + "the scale_feature method instead.",
+                  DeprecationWarning)
+    copy = not inplace
+
+    deform_corr = np.array(deform, copy=copy)
+
+    if channel_width_in != channel_width_out:
+        area_um_corr = scale_area_um(area_um, channel_width_in,
+                                     channel_width_out, inplace)
+    else:
+        area_um_corr = np.array(area_um, copy=copy)
+
+    if (emodulus is not None
+        and flow_rate_in is not None
+        and flow_rate_out is not None
+        and viscosity_in is not None
+            and viscosity_out is not None):
+        emodulus_corr = scale_emodulus(emodulus, channel_width_in,
+                                       channel_width_out, flow_rate_in,
+                                       flow_rate_out, viscosity_in,
+                                       viscosity_out, inplace)
+
+    if emodulus is None:
+        return area_um_corr, deform_corr
+    else:
+        return area_um_corr, deform_corr, emodulus_corr
+
+
+def scale_area_um(area_um, channel_width_in, channel_width_out, inplace=False,
+                  **kwargs):
+    """Perform scale conversion for area_um (linear elastic model)
+
+    The area scales with the characteristic length
+    "channel radius" L according to (L'/L)².
+
+    The conversion formula is described in :cite:`Mietke2015`.
+
+    .. versionadded: 0.25.0
+
+    Parameters
+    ----------
+    area_um: ndarray
+        Convex area [µm²]
+    channel_width_in: float
+        Original channel width [µm]
+    channel_width_out: float
+        Target channel width [µm]
+    inplace: bool
+        If True, override input arrays with corrected data
+    kwargs:
+        not used
+
+    Returns
+    -------
+    area_um_corr: ndarray
+        Scaled area [µm²]
+    """
+    copy = not inplace
+    if issubclass(area_um.dtype.type, np.integer) and inplace:
+        raise ValueError("Cannot correct integer `area_um` in-place!")
+    area_um_corr = np.array(area_um, copy=copy)
+
+    if channel_width_in != channel_width_out:
+        area_um_corr *= (channel_width_out / channel_width_in)**2
+    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):
+    """Perform scale conversion for area_um (linear elastic model)
+
+    The conversion formula is described in :cite:`Mietke2015`.
+
+    .. versionadded: 0.25.0
+
+    Parameters
+    ----------
+    emodulus: ndarray
+        Young's Modulus [kPa]
+    channel_width_in: float
+        Original channel width [µm]
+    channel_width_out: float
+        Target channel width [µm]
+    flow_rate_in: float
+        Original flow rate [µL/s]
+    flow_rate_out: float
+        Target flow rate [µL/s]
+    viscosity_in: float
+        Original viscosity [mPa*s]
+    viscosity_out: float or ndarray
+        Target viscosity [mPa*s]; This can be an array
+    inplace: bool
+        If True, override input arrays with corrected data
+
+    Returns
+    -------
+    emodulus_corr: ndarray
+        Scaled emodulus [kPa]
+    """
+    copy = not inplace
+
+    emodulus_corr = np.array(emodulus, copy=copy)
+
+    if viscosity_in is not None:
+        if isinstance(viscosity_in, np.ndarray):
+            raise ValueError("`viscosity_in` must not be an array!")
+
+    has_nones = (flow_rate_in is None
+                 or flow_rate_out is None
+                 or viscosity_in is None
+                 or viscosity_out is None
+                 or channel_width_in is None
+                 or channel_width_out is None
+                 )
+    has_changes = (flow_rate_in != flow_rate_out
+                   or channel_width_in != channel_width_out
+                   or (isinstance(viscosity_out, np.ndarray)  # check before
+                       or viscosity_in != viscosity_out)
+                   )
+
+    if not has_nones and has_changes:
+        emodulus_corr *= (flow_rate_out / flow_rate_in) \
+            * (viscosity_out / viscosity_in) \
+            * (channel_width_in / channel_width_out)**3
+
+    return emodulus_corr
+
+
+def scale_feature(feat, data, inplace=False, **scale_kw):
+    """Convenience function for scale conversions (linear elastic model)
+
+    This method wraps around all the other scale_* methods and also
+    supports deform/circ.
+
+    Parameters
+    ----------
+    feat: str
+        Valid scalar feature name
+    data: float or ndarray
+        Feature data
+    inplace: bool
+        If True, override input arrays with corrected data
+    **scale_kw:
+        Scale keyword arguments for the wrapped methods
+    """
+    if feat == "area_um":
+        return scale_area_um(area_um=data, inplace=inplace, **scale_kw)
+    elif feat in ["circ", "deform"]:
+        # no units
+        return np.array(data, copy=not inplace)
+    elif feat == "emodulus":
+        return scale_emodulus(emodulus=data, inplace=inplace, **scale_kw)
+    elif feat == "volume":
+        return scale_volume(volume=data, inplace=inplace, **scale_kw)
+    else:
+        raise KeyError("No recipe to scale feature '{}'!".format(feat))
+
+
+def scale_volume(volume, channel_width_in, channel_width_out, inplace=False,
+                 **kwargs):
+    """Perform scale conversion for volume (linear elastic model)
+
+    The volume scales with the characteristic length
+    "channel radius" L according to (L'/L)³.
+
+    .. versionadded: 0.25.0
+
+    Parameters
+    ----------
+    volume: ndarray
+        Volume [µm³]
+    channel_width_in: float
+        Original channel width [µm]
+    channel_width_out: float
+        Target channel width [µm]
+    inplace: bool
+        If True, override input arrays with corrected data
+    kwargs:
+        not used
+
+    Returns
+    -------
+    volume_corr: ndarray
+        Scaled volume [µm³]
+    """
+    copy = not inplace
+    volume_corr = np.array(volume, copy=copy)
+
+    if channel_width_in != channel_width_out:
+        volume_corr *= (channel_width_out / channel_width_in)**3
+    return volume_corr

dclab/features/emodulus/viscosity.py

@@ -0,0 +1,260 @@
+"""Viscosity computation for various media"""
+from __future__ import annotations
+
+from typing import Literal
+import warnings
+
+import numpy as np
+
+from ...warn import PipelineWarning
+
+
+#: Dictionary with different names for one medium
+SAME_MEDIA = {
+    "0.49% MC-PBS": ["0.49% MC-PBS",
+                     "0.5% MC-PBS",
+                     "0.50% MC-PBS",
+                     "CellCarrier",
+                     ],
+    # 6g MC in 1010g PBS [!sic]
+    "0.59% MC-PBS": ["0.59% MC-PBS",
+                     "0.6% MC-PBS",
+                     "0.60% MC-PBS",
+                     "CellCarrier B",
+                     "CellCarrierB",
+                     ],
+    "0.83% MC-PBS": ["0.83% MC-PBS",
+                     "0.8% MC-PBS",
+                     "0.80% MC-PBS"],
+    "water": ["water"],
+}
+
+#: Many media names are actually shorthand for one medium
+ALIAS_MEDIA = {}
+for key in SAME_MEDIA:
+    for item in SAME_MEDIA[key]:
+        ALIAS_MEDIA[item] = key
+        ALIAS_MEDIA[item.lower()] = key  # also support all-lower case
+
+#: Media for which computation of viscosity is defined (has duplicate entries)
+KNOWN_MEDIA = sorted(ALIAS_MEDIA.keys())
+
+
+class TemperatureOutOfRangeWarning(PipelineWarning):
+    pass
+
+
+def check_temperature(model: str,
+                      temperature: float | np.array,
+                      tmin: float,
+                      tmax: float):
+    """Raise a TemperatureOutOfRangeWarning if applicable"""
+    if np.min(temperature) < tmin or np.max(temperature) > tmax:
+        warnings.warn(
+            f"For the {model} model, the temperature should be "
+            f"in [{tmin}, {tmax}] degC! Got min/max of "
+            f"[{np.min(temperature):.1f}, {np.max(temperature):.1f}] degC.",
+            TemperatureOutOfRangeWarning)
+
+
+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,
+                  model: Literal['herold-2017',
+                                 'herold-2017-fallback',
+                                 'buyukurganci-2022',
+                                 'kestin-1978'] = 'herold-2017-fallback'):
+    """Returns the viscosity for RT-DC-specific media
+
+    Media that are not pure (e.g. ketchup or polymer solutions)
+    often exhibit a non-linear relationship between shear rate
+    (determined by the velocity profile) and shear stress
+    (determined by pressure differences). If the shear stress
+    grows non-linearly with the shear rate resulting in a slope
+    in log-log space that is less than one, then we are talking about
+    shear thinning. The viscosity is not a constant anymore (as it
+    is e.g. for water). At higher flow rates, the viscosity becomes
+    smaller, following a power law. Christoph Herold characterized
+    shear thinning for the CellCarrier media :cite:`Herold2017`.
+    The resulting formulae for computing the viscosities of these
+    media at different channel widths, flow rates, and temperatures,
+    are implemented here.
+
+    Parameters
+    ----------
+    medium: str
+        The medium to compute the viscosity for; Valid values
+        are defined in :const:`KNOWN_MEDIA`.
+    channel_width: float
+        The channel width in µm
+    flow_rate: float
+        Flow rate in µL/s
+    temperature: float or ndarray
+        Temperature in °C
+    model: str
+        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,
+        there are the 'herold-2017' model :cite:`Herold2017` and the
+        'buyukurganci-2022' model :cite:`Buyukurganci2022`.
+
+    Returns
+    -------
+    viscosity: float or ndarray
+        Viscosity in mPa*s
+
+    Notes
+    -----
+    - CellCarrier (0.49% MC-PBS) and CellCarrier B (0.59% MC-PBS) are
+      media designed for RT-DC experiments.
+    - A :class:`TemperatureOutOfRangeWarning` is issued if the
+      input temperature range exceeds the temperature ranges of
+      the models.
+    """
+    # also support lower-case media and a space before the "B"
+    if medium not in KNOWN_MEDIA:
+        raise ValueError(f"Invalid medium: {medium}")
+    medium = ALIAS_MEDIA[medium]
+
+    if medium == "water":
+        # We ignore the `model`, because it's user convenient.
+        eta = get_viscosity_water_kestin_1978(temperature=temperature)
+    elif not flow_rate:
+        # When flow rate is zero, we cannot compute the viscosity for
+        # anything other than water above.
+        eta = np.nan
+    elif medium in ["0.49% MC-PBS", "0.59% MC-PBS", "0.83% MC-PBS"]:
+        kwargs = {"medium": medium,
+                  "temperature": temperature,
+                  "flow_rate": flow_rate,
+                  "channel_width": channel_width}
+
+        # Let the user know that we have a new model in town.
+        if model == "herold-2017-fallback":
+            warnings.warn(
+                "dclab 0.48.0 introduced a more accurate model for computing "
+                "the MC-PBS viscosity. You are now using the old model "
+                "'herold-2017'. Unless you are reproducing an old analysis "
+                "pipeline, you should consider passing 'buyukurganci-2022' "
+                "as a viscosity model!",
+                DeprecationWarning)
+            model = "herold-2017"
+
+        if model == "herold-2017":
+            eta = get_viscosity_mc_pbs_herold_2017(**kwargs)
+        elif model == "buyukurganci-2022":
+            eta = get_viscosity_mc_pbs_buyukurganci_2022(**kwargs)
+        else:
+            raise NotImplementedError(f"Unknown model '{model}' for MC-PBS!")
+    else:
+        raise NotImplementedError(f"Unknown medium '{medium}'!")
+    return eta
+
+
+def shear_rate_square_channel(flow_rate, channel_width, flow_index):
+    """Returns The wall shear rate of a power law liquid in a squared channel.
+
+    Parameters
+    ----------
+    flow_rate: float
+        Flow rate in µL/s
+    channel_width: float
+        The channel width in µm
+    flow_index: float
+        Flow behavior index aka the power law exponent of the shear thinning
+
+    Returns
+    -------
+    shear_rate: float
+        Shear rate in 1/s.
+    """
+    # convert channel width to mm
+    channel_width = channel_width * 1e-3
+    return 8*flow_rate/(channel_width**3) * (0.6671 + 0.2121/flow_index)
+
+
+def get_viscosity_mc_pbs_buyukurganci_2022(
+        medium: Literal["0.49% MC-PBS",
+                        "0.59% MC-PBS",
+                        "0.83% MC-PBS"] = "0.49% MC-PBS",
+        channel_width: float = 20.0,
+        flow_rate: float = 0.16,
+        temperature: float = 23.0):
+    """Compute viscosity of MC-PBS according to :cite:`Buyukurganci2022`
+
+    This viscosity model was derived in :cite:`Buyukurganci2022`
+    and adapted for RT-DC in :cite:`Reichel2023`.
+    """
+    check_temperature("'buyukurganci-2022' MC-PBS", temperature, 22, 37)
+    # material constants for temperature behavior of MC dissolved in PBS:
+    alpha = 0.00223
+    lambd = 3379.7
+    kelvin = temperature + 273.15
+
+    if medium == "0.49% MC-PBS":
+        a = 2.30e-6  # previously 2.23e-6, changed in Reichel2023 rev 2
+        beta = -0.0056
+    elif medium == "0.59% MC-PBS":
+        a = 5.70e-6
+        beta = -0.0744
+    elif medium == "0.83% MC-PBS":
+        a = 16.52e-6
+        beta = -0.1455
+    else:
+        raise NotImplementedError(
+            f"Medium {medium} not supported for model `buyukurganci-2022`!")
+
+    k = a * np.exp(lambd / kelvin)
+    n = alpha * kelvin + beta
+    shear_rate = shear_rate_square_channel(flow_rate, channel_width, n)
+    return k * shear_rate**(n - 1) * 1e3
+
+
+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):
+    r"""Compute viscosity of MC-PBS according to :cite:`Herold2017`
+
+    Note that all the factors in equation 5.2 in :cite:`Herold2017`
+    compute to 8, which is essentially what is implemented in
+    :func:`shear_rate_square_channel`:
+
+    .. math::
+
+        1.1856 \cdot 6 \cdot \frac{2}{3} \cdot \frac{1}{0.5928} = 8
+    """
+    # see figure (9) in Herold arXiv:1704.00572 (2017)
+    check_temperature("'herold-2017' MC-PBS", temperature, 18, 26)
+    # convert flow_rate from µL/s to m³/s
+    # convert channel_width from µm to m
+    term1 = 1.1856 * 6 * flow_rate * 1e-9 / (channel_width * 1e-6)**3 * 2 / 3
+
+    if medium == "0.49% MC-PBS":
+        temp_corr = (temperature / 23.2)**-0.866
+        term2 = 0.6771 / 0.5928 + 0.2121 / (0.5928 * 0.677)
+        eta = 0.179 * (term1 * term2)**(0.677 - 1) * temp_corr * 1e3
+    elif medium == "0.59% MC-PBS":
+        temp_corr = (temperature / 23.6)**-0.866
+        term2 = 0.6771 / 0.5928 + 0.2121 / (0.5928 * 0.634)
+        eta = 0.360 * (term1 * term2)**(0.634 - 1) * temp_corr * 1e3
+    else:
+        raise NotImplementedError(
+            f"Medium {medium} not supported for model `herold-2017`!")
+    return eta
+
+
+def get_viscosity_water_kestin_1978(temperature: float = 23.0):
+    """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)
+    eta0 = 1.002  # [mPa s]
+    right = (20-temperature) / (temperature + 96) \
+        * (+ 1.2364
+           - 1.37e-3 * (20 - temperature)
+           + 5.7e-6 * (20 - temperature)**2
+           )
+    eta = eta0 * 10**right
+    return eta