phasorpy 0.6__cp312-cp312-win_amd64.whl → 0.8__cp312-cp312-win_amd64.whl

phasorpy/__init__.py

@@ -5,5 +5,5 @@ from __future__ import annotations
 __all__ = ['__version__']
 
 
-__version__ = '0.6'
+__version__ = '0.8'
 """PhasorPy version string."""

phasorpy/_phasorpy.pyx

@@ -6,7 +6,13 @@
 # cython: nonecheck = False
 # cython: freethreading_compatible = True
 
-"""Cython implementation of low-level functions for the PhasorPy library."""
+"""Private functions implemented in Cython for performance.
+
+.. note::
+    This module and its functions are not part of the public interface.
+    They are intended to facilitate the development of the PhasorPy library.
+
+"""
 
 cimport cython
 
@@ -488,10 +494,10 @@ cdef (double, double) _phasor_from_fret_donor(
         return 1.0, 0.0
 
     # phasor of pure donor at frequency
-    real, imag = phasor_from_lifetime(donor_lifetime, omega)
+    real, imag = phasor_from_single_lifetime(donor_lifetime, omega)
 
     # phasor of quenched donor
-    quenched_real, quenched_imag = phasor_from_lifetime(
+    quenched_real, quenched_imag = phasor_from_single_lifetime(
         donor_lifetime * (1.0 - fret_efficiency), omega
     )
 
@@ -555,14 +561,14 @@ cdef (double, double) _phasor_from_fret_acceptor(
         acceptor_background = 0.0
 
     # phasor of pure donor at frequency
-    donor_real, donor_imag = phasor_from_lifetime(donor_lifetime, omega)
+    donor_real, donor_imag = phasor_from_single_lifetime(donor_lifetime, omega)
 
     if fret_efficiency == 0.0:
         quenched_real = donor_real
         quenched_imag = donor_imag
     else:
         # phasor of quenched donor
-        quenched_real, quenched_imag = phasor_from_lifetime(
+        quenched_real, quenched_imag = phasor_from_single_lifetime(
             donor_lifetime * (1.0 - fret_efficiency), omega
         )
 
@@ -580,7 +586,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
         )
 
     # phasor of acceptor at frequency
-    acceptor_real, acceptor_imag = phasor_from_lifetime(
+    acceptor_real, acceptor_imag = phasor_from_single_lifetime(
         acceptor_lifetime, omega
     )
 
@@ -646,9 +652,9 @@ cdef inline (double, double) linear_combination(
     )
 
 
-cdef inline (float_t, float_t) phasor_from_lifetime(
-    float_t lifetime,
-    float_t omega,
+cdef inline (double, double) phasor_from_single_lifetime(
+    const double lifetime,
+    const double omega,
 ) noexcept nogil:
     """Return phasor coordinates from single lifetime component."""
     cdef:
@@ -656,7 +662,7 @@ cdef inline (float_t, float_t) phasor_from_lifetime(
         double mod = 1.0 / sqrt(1.0 + t * t)
         double phi = atan(t)
 
-    return <float_t> (mod * cos(phi)), <float_t> (mod * sin(phi))
+    return mod * cos(phi), mod * sin(phi)
 
 
 ###############################################################################
@@ -1005,6 +1011,38 @@ cdef (float_t, float_t) _phasor_divide(
     )
 
 
+@cython.ufunc
+cdef (float_t, float_t, float_t) _phasor_combine(
+    float_t int0,
+    float_t real0,
+    float_t imag0,
+    float_t int1,
+    float_t real1,
+    float_t imag1,
+    float_t fraction0,
+    float_t fraction1,
+) noexcept nogil:
+    """Return linear combination of two phasor coordinates."""
+    cdef:
+        float_t intensity
+
+    fraction1 += fraction0
+    if fraction1 == 0.0:
+        return <float_t> 0.0, <float_t> NAN, <float_t> NAN
+    fraction0 /= fraction1
+
+    int0 *= fraction0
+    int1 *= <float_t> 1.0 - fraction0
+    intensity = int0 + int1
+
+    if intensity == 0.0:
+        return <float_t> 0.0, <float_t> NAN, <float_t> NAN
+
+    int0 /= intensity
+    int1 /= intensity
+    return intensity, int0 * real0 + int1 * real1, int0 * imag0 + int1 * imag1
+
+
 ###############################################################################
 # Geometry ufuncs
 
@@ -1706,6 +1744,164 @@ cdef (float_t, float_t, float_t, float_t) _intersect_semicircle_line(
     return x0, y0, x1, y1
 
 
+###############################################################################
+# Search functions
+
+
+def _lifetime_search_2(
+    float_t[:, ::] lifetime,  # (num_components, pixels)
+    float_t[:, ::] fraction,  # (num_components, pixels)
+    const float_t[:, ::] real,  # (num_components, pixels)
+    const float_t[:, ::] imag,  # (num_components, pixels)
+    const double[::] candidate,  # real coordinates to scan
+    const double omega_sqr,
+    const int num_threads
+):
+    """Find two lifetime components and fractions in harmonic coordinates.
+
+    https://doi.org/10.1021/acs.jpcb.0c06946
+
+    """
+    cdef:
+        ssize_t i, u
+        double re1, im1, re2, im2
+        double g0, g1, g0h1, s0h1, g1h1, s1h1, g0h2, s0h2, g1h2, s1h2
+        double x, y, dx, dy, dr, dd, rdd
+        double dmin, d, f, t
+
+    if lifetime.shape[0] != 2 or lifetime.shape[1] != real.shape[1]:
+        raise ValueError('lifetime shape invalid')
+    if fraction.shape[0] != 2 or fraction.shape[1] != real.shape[1]:
+        raise ValueError('fraction shape invalid')
+    if real.shape[0] != imag.shape[0] != 2:
+        raise ValueError('phasor harmonics invalid')
+    if real.shape[1] != imag.shape[1]:
+        raise ValueError('phasor size invalid')
+    if candidate.shape[0] < 1:
+        raise ValueError('candidate size < 1')
+
+    with nogil, parallel(num_threads=num_threads):
+
+        for u in prange(real.shape[1]):
+            # loop over phasor coordinates
+            re1 = real[0, u]
+            re2 = real[1, u]
+            im1 = imag[0, u]
+            im2 = imag[1, u]
+
+            if (
+                isnan(re1)
+                or isnan(im1)
+                or isnan(re2)
+                or isnan(im2)
+                # outside semicircle?
+                or re1 < 0.0
+                or re2 < 0.0
+                or re1 > 1.0
+                or re2 > 1.0
+                or im1 < 0.0
+                or im2 < 0.0
+                or im1 * im1 > re1 - re1 * re1 + 1e-9
+                or im2 * im2 > re2 - re2 * re2 + 1e-9
+            ):
+                lifetime[0, u] = NAN
+                lifetime[1, u] = NAN
+                fraction[0, u] = NAN
+                fraction[1, u] = NAN
+                continue
+
+            dmin = INFINITY
+            g0 = NAN
+            g1 = NAN
+            f = NAN
+
+            for i in range(candidate.shape[0]):
+                # scan first component
+                g0h1 = candidate[i]
+                s0h1 = sqrt(g0h1 - g0h1 * g0h1)
+
+                # second component is intersection of semicircle with line
+                # between first component and phasor coordinate
+                dx = re1 - g0h1
+                dy = im1 - s0h1
+                dr = dx * dx + dy * dy
+                dd = (g0h1 - 0.5) * im1 - (re1 - 0.5) * s0h1
+                rdd = 0.25 * dr - dd * dd  # discriminant
+                if rdd < 0.0 or dr <= 0.0:
+                    # no intersection
+                    g0 = g0h1
+                    g1 = g0h1  # NAN?
+                    f = 1.0
+                    break
+                rdd = sqrt(rdd)
+                g0h1 = (dd * dy - copysign(1.0, dy) * dx * rdd) / dr + 0.5
+                s0h1 = (-dd * dx - fabs(dy) * rdd) / dr
+                g1h1 = (dd * dy + copysign(1.0, dy) * dx * rdd) / dr + 0.5
+                s1h1 = (-dd * dx + fabs(dy) * rdd) / dr
+
+                # this check is numerically unstable if candidate=1.0
+                if s0h1 < 0.0 or s1h1 < 0.0:
+                    # no other intersection with semicircle
+                    continue
+
+                if g0h1 < g1h1:
+                    t = g0h1
+                    g0h1 = g1h1
+                    g1h1 = t
+                    t = s0h1
+                    s0h1 = s1h1
+                    s1h1 = t
+
+                # second harmonic component coordinates on semicircle
+                g0h2 = g0h1 / (4.0 - 3.0 * g0h1)
+                s0h2 = sqrt(g0h2 - g0h2 * g0h2)
+                g1h2 = g1h1 / (4.0 - 3.0 * g1h1)
+                s1h2 = sqrt(g1h2 - g1h2 * g1h2)
+
+                # distance of phasor coordinates to line between
+                # components at second harmonic
+                # normalize line coordinates
+                dx = g1h2 - g0h2
+                dy = s1h2 - s0h2
+                x = re2 - g0h2
+                y = im2 - s0h2
+                # square of line length
+                t = dx * dx + dy * dy
+                if t == 0.0:
+                    continue
+                # projection of point on line using dot product
+                t = (x * dx + y * dy) / t
+                # square of distance of point to line
+                dx = x - t * dx
+                dy = y - t * dy
+                d = dx * dx + dy * dy
+
+                if d < dmin:
+                    dmin = d
+                    g0 = g0h1
+                    g1 = g1h1
+                    f = t
+
+            lifetime[0, u] = <float_t> phasor_to_single_lifetime(g0, omega_sqr)
+            lifetime[1, u] = <float_t> phasor_to_single_lifetime(g1, omega_sqr)
+            fraction[0, u] = <float_t> (1.0 - f)
+            fraction[1, u] = <float_t> f
+
+
+cdef inline double phasor_to_single_lifetime(
+    const double real,
+    const double omega_sqr,
+) noexcept nogil:
+    """Return single exponential lifetime from real coordinate."""
+    cdef:
+        double t
+
+    if isnan(real) or real < 0.0 or real > 1.0:
+        return NAN
+    t = real * omega_sqr
+    return sqrt((1.0 - real) / t) if t > 0.0 else INFINITY
+
+
 def _nearest_neighbor_2d(
     int_t[::1] indices,
     const float_t[::1] x0,
@@ -1755,6 +1951,120 @@ def _nearest_neighbor_2d(
             indices[i] = -1 if dmin > distance_max_squared else <int_t> index
 
 
+###############################################################################
+# Interpolation functions
+
+
+def _mean_value_coordinates(
+    float_t[:, ::1] fraction,  # vertices, points
+    const ssize_t[::1] order,
+    const float_t[::1] px,  # points
+    const float_t[::1] py,
+    const float_t[::1] vx,  # polygon vertices
+    const float_t[::1] vy,
+    const int num_threads
+):
+    """Calculate mean value coordinates of points in polygon.
+
+    https://doi.org/10.1016/j.cagd.2024.102310
+
+    """
+    cdef:
+        ssize_t i, j, k, p, nv
+        double x, y, alpha, weight, weight_sum
+        double* weights = NULL
+        double* sigma = NULL
+        double* length = NULL
+
+    if px.shape[0] != py.shape[0]:
+        raise ValueError('px and py shape mismatch')
+    if vx.shape[0] != vy.shape[0]:
+        raise ValueError('vx and vy shape mismatch')
+    if fraction.shape[0] != vx.shape[0] or fraction.shape[1] != px.shape[0]:
+        raise ValueError('fraction, vx or px shape mismatch')
+    if fraction.shape[0] != order.shape[0]:
+        raise ValueError('fraction and order shape mismatch')
+    if fraction.shape[0] < 3:
+        raise ValueError('not a polygon')
+
+    nv = fraction.shape[0]
+
+    with nogil, parallel(num_threads=num_threads):
+        weights = <double *> malloc(3 * nv * sizeof(double))
+        if weights == NULL:
+            with gil:
+                raise MemoryError('failed to allocate thread-local buffer')
+        sigma = &weights[nv]
+        length = &weights[nv * 2]
+
+        for p in prange(px.shape[0]):
+            x = px[p]
+            y = py[p]
+
+            if isnan(x) or isnan(y):
+                for i in range(nv):
+                    fraction[i, p] = <float_t> NAN
+                continue
+
+            for i in range(nv):
+                j = (i + 1) % nv  # next vertex, wrapped around
+                sigma[i] = (
+                    angle(vx[j], vy[j], vx[i], vy[i], x, y)  # beta
+                    - angle(vx[i], vy[i], vx[j], vy[j], x, y)  # gamma
+                )
+                length[i] = hypot(vx[i] - x, vy[i] - y)
+
+            weight_sum = 0.0
+            for i in range(nv):
+                j = (i + 1) % nv  # next vertex, wrapped around
+                k = (i - 1 + nv) % nv  # previous vertex, wrapped around
+
+                alpha = angle(vx[k], vy[k], x, y, vx[j], vy[j])
+                if sign(alpha) != sign(
+                    M_PI * (sign(sigma[k]) + sign(sigma[i]))
+                    - sigma[k] - sigma[i]
+                ):
+                    alpha = -alpha
+                weight = length[k] * sin(alpha * 0.5)
+                for j in range(nv):
+                    if j != k and j != i:
+                        weight = weight * length[j] * sin(fabs(sigma[j]) * 0.5)
+                weight_sum = weight_sum + weight
+                weights[i] = weight
+
+            if fabs(weight_sum) > 1e-12:
+                for i in range(nv):
+                    fraction[order[i], p] = <float_t> (weights[i] / weight_sum)
+            else:
+                for i in range(nv):
+                    fraction[i, p] = <float_t> NAN
+
+        free(weights)
+
+
+cdef inline int sign(const double x) noexcept nogil:
+    """Return sign of x."""
+    return 0 if fabs(x) < 1e-12 else (1 if x > 0.0 else -1)
+
+
+cdef inline double angle(
+    const double x0,
+    const double y0,
+    const double x1,
+    const double y1,
+    const double x2,
+    const double y2,
+) noexcept nogil:
+    """Return angle at (x1, y1)."""
+    cdef:
+        double ax = x0 - x1
+        double ay = y0 - y1
+        double bx = x2 - x1
+        double by = y2 - y1
+
+    return atan2(ax * by - ay * bx, ax * bx + ay * by)
+
+
 ###############################################################################
 # Blend ufuncs
 

phasorpy/_utils.py

@@ -1,4 +1,10 @@
-"""Private auxiliary and convenience functions."""
+"""Private auxiliary and convenience functions.
+
+.. note::
+    This module and its functions are not part of the public interface.
+    They are intended to facilitate the development of the PhasorPy library.
+
+"""
 
 from __future__ import annotations
 
@@ -52,6 +58,23 @@ def parse_kwargs(
 
     If `_del` is true (default), existing keys are deleted from `kwargs`.
 
+    Parameters
+    ----------
+    kwargs : dict
+        Source dictionary to extract keys from.
+    *keys : str
+        Keys to extract from kwargs if present.
+    _del : bool, default: True
+        If True, remove extracted keys from kwargs.
+    **keyvalues : Any
+        Key-value pairs. If key exists in kwargs, use kwargs value,
+        otherwise use provided default value.
+
+    Returns
+    -------
+    dict
+        Dictionary containing extracted keys and values.
+
     >>> kwargs = {'one': 1, 'two': 2, 'four': 4}
     >>> kwargs2 = parse_kwargs(kwargs, 'two', 'three', four=None, five=5)
     >>> kwargs == {'one': 1}
@@ -105,19 +128,19 @@ def scale_matrix(factor: float, origin: Sequence[float]) -> NDArray[Any]:
 
     Parameters
     ----------
-    factor: float
+    factor : float
         Scale factor.
-    origin: (float, float)
+    origin : (float, float)
         Coordinates of point around which to scale.
 
     Returns
     -------
-    matrix: ndarray
+    matrix : ndarray
         A 3x3 homogeneous transformation matrix.
 
     Examples
     --------
-    >>> scale_matrix(1.1, (0.0, 0.5))
+    >>> scale_matrix(1.1, [0.0, 0.5])
     array([[1.1, 0, -0],
            [0, 1.1, -0.05],
            [0, 0, 1]])
@@ -133,7 +156,7 @@ def sort_coordinates(
     real: ArrayLike,
     imag: ArrayLike,
     /,
-    origin: tuple[float, float] | None = None,
+    origin: ArrayLike | None = None,
 ) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any]]:
     """Return cartesian coordinates sorted counterclockwise around origin.
 
@@ -141,15 +164,19 @@ def sort_coordinates(
     ----------
     real, imag : array_like
         Coordinates to be sorted.
-    origin : (float, float)
+    origin : array_like, optional
         Coordinates around which to sort by angle.
+        By default, sort around the mean of `real` and `imag`.
 
     Returns
     -------
-    real, imag : ndarray
-        Coordinates sorted by angle.
+    real : ndarray
+        Sorted real coordinates.
+    imag : ndarray
+        Sorted imaginary coordinates.
     indices : ndarray
         Indices used to reorder coordinates.
+        Use ``indices.argsort()`` to get original order.
 
     Examples
     --------
@@ -160,11 +187,15 @@ def sort_coordinates(
     x, y = numpy.atleast_1d(real, imag)
     if x.ndim != 1 or x.shape != y.shape:
         raise ValueError(f'invalid {x.shape=} or {y.shape=}')
-    if x.size < 4:
+    if x.size < 3:
         return x, y, numpy.arange(x.size)
     if origin is None:
-        origin = x.mean(), y.mean()
-    indices = numpy.argsort(numpy.arctan2(y - origin[1], x - origin[0]))
+        ox, oy = x.mean(), y.mean()
+    else:
+        origin = numpy.asarray(origin, dtype=numpy.float64)
+        ox = origin[0]
+        oy = origin[1]
+    indices = numpy.argsort(numpy.arctan2(y - oy, x - ox))
     return x[indices], y[indices], indices
 
 
@@ -185,8 +216,10 @@ def dilate_coordinates(
 
     Returns
     -------
-    real, imag : ndarray
-        Coordinates dilated by offset.
+    real : ndarray
+        Dilated real coordinates.
+    imag : ndarray
+        Dilated imaginary coordinates.
 
     Examples
     --------
@@ -225,8 +258,28 @@ def phasor_to_polar_scalar(
 ) -> tuple[float, float]:
     """Return polar from scalar phasor coordinates.
 
-    >>> phasor_to_polar_scalar(1.0, 0.0, degree=True, percent=True)
-    (0.0, 100.0)
+    Parameters
+    ----------
+    real : float
+        Real component of phasor coordinate.
+    imag : float
+        Imaginary component of phasor coordinate.
+    degree : bool, optional
+        If true, return phase in degrees instead of radians.
+    percent : bool, optional
+        If true, return modulation as percentage instead of fraction.
+
+    Returns
+    -------
+    phase : float
+        Phase angle in radians (or degrees if degree=True).
+    modulation : float
+        Modulation depth as fraction (or percentage if percent=True).
+
+    Examples
+    --------
+    >>> phasor_to_polar_scalar(0.0, 1.0, degree=True, percent=True)
+    (90.0, 100.0)
 
     """
     phi = math.atan2(imag, real)
@@ -248,6 +301,26 @@ def phasor_from_polar_scalar(
 ) -> tuple[float, float]:
     """Return phasor from scalar polar coordinates.
 
+    Parameters
+    ----------
+    phase : float
+        Phase angle in radians (or degrees if degree=True).
+    modulation : float
+        Modulation depth as fraction (or percentage if percent=True).
+    degree : bool, optional
+        If true, phase is in degrees instead of radians.
+    percent : bool, optional
+        If true, modulation is as percentage instead of fraction.
+
+    Returns
+    -------
+    real : float
+        Real component of phasor coordinate.
+    imag : float
+        Imaginary component of phasor coordinate.
+
+    Examples
+    --------
     >>> phasor_from_polar_scalar(0.0, 100.0, degree=True, percent=True)
     (1.0, 0.0)
 
@@ -273,23 +346,27 @@ def parse_signal_axis(
     Parameters
     ----------
     signal : array_like
-        Image stack.
-    axis : int or str, optional
-        Axis over which phasor coordinates are computed.
-        By default, the 'H' or 'C' axes if `signal` contains such
-        dimension names, else the last axis (-1).
+        Signal array.
+        Axis names are used if it has a `dims` attribute.
+    axis : int, str, or None, default: None
+        Axis over which to compute phasor coordinates.
+        If None, automatically selects 'H' or 'C' axis if available,
+        otherwise uses the last axis (-1).
+        If int, specifies axis index.
+        If str, specifies axis name (requires `signal.dims`).
 
     Returns
     -------
     axis : int
-        Axis over which phasor coordinates are computed.
+        Index of axis over which phasor coordinates are computed.
     axis_label : str
-        Axis label from `signal.dims` if any.
+        Label of axis from `signal.dims` if available, empty string otherwise.
 
     Raises
     ------
     ValueError
-        Axis not found in signal.dims or invalid for signal type.
+        If axis string is not found in signal.dims.
+        If axis string is provided but signal has no dims attribute.
 
     Examples
     --------
@@ -356,15 +433,17 @@ def parse_skip_axis(
 
     Raises
     ------
+    ValueError
+        If ndim is negative.
     IndexError
         If any `skip_axis` value is out of bounds of `ndim`.
 
     Examples
     --------
-    >>> parse_skip_axis((1, -2), 5)
+    >>> parse_skip_axis([1, -2], 5)
     ((1, 3), (0, 2, 4))
 
-    >>> parse_skip_axis((1, -2), 5, True)
+    >>> parse_skip_axis([1, -2], 5, True)
     ((0, 2, 4), (1, 3, 5))
 
     """
@@ -401,7 +480,7 @@ def parse_harmonic(
     harmonic : int, sequence of int, 'all', or None
         Harmonic parameter to parse.
     harmonic_max : int, optional
-        Maximum value allowed in `hamonic`. Must be one or greater.
+        Maximum value allowed in `harmonic`. Must be one or greater.
         To verify against known number of signal samples,
         pass ``samples // 2``.
         If `harmonic='all'`, a range of harmonics from one to `harmonic_max`
@@ -487,11 +566,11 @@ def chunk_iter(
     pattern : str, optional
         String to format chunk indices.
         If None, use ``_[{dims[index]}{chunk_index[index]}]`` for each axis.
-    squeeze : bool
+    squeeze : bool, optional
         If true, do not include length-1 chunked dimensions in label
         unless dimensions are part of `chunk_shape`.
         Applies only if `pattern` is None.
-    use_index : bool
+    use_index : bool, optional
         If true, use indices of chunks in `shape` instead of chunk indices to
         format pattern.
 
@@ -594,7 +673,7 @@ def chunk_iter(
 
 
 def init_module(globs: dict[str, Any], /) -> None:
-    """Add names in module to ``__all__`` and set ``__module__`` attributes.
+    """Add names in module to ``__all__`` attribute.
 
     Parameters
     ----------
@@ -617,9 +696,11 @@ def init_module(globs: dict[str, Any], /) -> None:
         }:
             continue
         names.append(name)
-        obj = getattr(module, name)
-        if hasattr(obj, '__module__'):
-            obj.__module__ = module_name
+        # do not change __module__ attributes because that may interfere
+        # with introspection and pickling
+        # obj = getattr(module, name)
+        # if hasattr(obj, '__module__'):
+        #     obj.__module__ = module_name
     globs['__all__'] = sorted(set(names))