phasorpy 0.4__cp313-cp313-win_arm64.whl → 0.5__cp313-cp313-win_arm64.whl

phasorpy/_phasorpy.pyx

@@ -4,15 +4,10 @@
 # cython: wraparound = False
 # cython: cdivision = True
 # cython: nonecheck = False
+# cython: freethreading_compatible = True
 
 """Cython implementation of low-level functions for the PhasorPy library."""
 
-# TODO: replace short with unsigned char when Cython supports it
-# https://github.com/cython/cython/pull/6196#issuecomment-2209509572
-
-# TODO: use fused return types for functions returning more than two items
-# https://github.com/cython/cython/issues/6328
-
 cimport cython
 
 from cython.parallel import parallel, prange
@@ -451,7 +446,7 @@ cdef (double, double) _phasor_from_fret_donor(
     double omega,
     double donor_lifetime,
     double fret_efficiency,
-    double donor_freting,
+    double donor_fretting,
     double donor_background,
     double background_real,
     double background_imag,
@@ -471,16 +466,16 @@ cdef (double, double) _phasor_from_fret_donor(
     elif fret_efficiency > 1.0:
         fret_efficiency = 1.0
 
-    if donor_freting < 0.0:
-        donor_freting = 0.0
-    elif donor_freting > 1.0:
-        donor_freting = 1.0
+    if donor_fretting < 0.0:
+        donor_fretting = 0.0
+    elif donor_fretting > 1.0:
+        donor_fretting = 1.0
 
     if donor_background < 0.0:
         donor_background = 0.0
 
-    f_pure = 1.0 - donor_freting
-    f_quenched = (1.0 - fret_efficiency) * donor_freting
+    f_pure = 1.0 - donor_fretting
+    f_quenched = (1.0 - fret_efficiency) * donor_fretting
     sum = f_pure + f_quenched + donor_background
     if sum < 1e-9:
         # no signal in donor channel
@@ -516,7 +511,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
     double donor_lifetime,
     double acceptor_lifetime,
     double fret_efficiency,
-    double donor_freting,
+    double donor_fretting,
     double donor_bleedthrough,
     double acceptor_bleedthrough,
     double acceptor_background,
@@ -541,10 +536,10 @@ cdef (double, double) _phasor_from_fret_acceptor(
     elif fret_efficiency > 1.0:
         fret_efficiency = 1.0
 
-    if donor_freting < 0.0:
-        donor_freting = 0.0
-    elif donor_freting > 1.0:
-        donor_freting = 1.0
+    if donor_fretting < 0.0:
+        donor_fretting = 0.0
+    elif donor_fretting > 1.0:
+        donor_fretting = 1.0
 
     if donor_bleedthrough < 0.0:
         donor_bleedthrough = 0.0
@@ -575,7 +570,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
             quenched_imag,
             1.0,
             1.0 - fret_efficiency,
-            1.0 - donor_freting
+            1.0 - donor_fretting
         )
 
     # phasor of acceptor at frequency
@@ -597,8 +592,8 @@ cdef (double, double) _phasor_from_fret_acceptor(
     sensitized_imag = mod * sin(phi)
 
     # weighted average
-    f_donor = donor_bleedthrough * (1.0 - donor_freting * fret_efficiency)
-    f_acceptor = donor_freting * fret_efficiency
+    f_donor = donor_bleedthrough * (1.0 - donor_fretting * fret_efficiency)
+    f_acceptor = donor_fretting * fret_efficiency
     sum = f_donor + f_acceptor + acceptor_bleedthrough + acceptor_background
     if sum < 1e-9:
         # no signal in acceptor channel
@@ -919,7 +914,7 @@ cdef (float_t, float_t) _phasor_at_harmonic(
     int harmonic,
     int other_harmonic,
 ) noexcept nogil:
-    """Return phasor coordinates on semicircle at other harmonic."""
+    """Return phasor coordinates on universal semicircle at other harmonic."""
     if isnan(real):
         return <float_t> NAN, <float_t> NAN
 
@@ -982,7 +977,7 @@ cdef (float_t, float_t) _phasor_divide(
 
 
 @cython.ufunc
-cdef short _is_inside_range(
+cdef unsigned char _is_inside_range(
     float_t x,  # point
     float_t y,
     float_t xmin,  # x range
@@ -1002,7 +997,7 @@ cdef short _is_inside_range(
 
 
 @cython.ufunc
-cdef short _is_inside_rectangle(
+cdef unsigned char _is_inside_rectangle(
     float_t x,  # point
     float_t y,
     float_t x0,  # segment start
@@ -1044,7 +1039,7 @@ cdef short _is_inside_rectangle(
 
 
 @cython.ufunc
-cdef short _is_inside_polar_rectangle(
+cdef unsigned char _is_inside_polar_rectangle(
     float_t x,  # point
     float_t y,
     float_t angle_min,  # phase, -pi to pi
@@ -1054,7 +1049,7 @@ cdef short _is_inside_polar_rectangle(
 ) noexcept nogil:
     """Return whether point is inside polar rectangle.
 
-    Angles should be in range -pi to pi, else performance is degraded.
+    Angles should be in range [-pi, pi], else performance is degraded.
 
     """
     cdef:
@@ -1083,7 +1078,7 @@ cdef short _is_inside_polar_rectangle(
 
 
 @cython.ufunc
-cdef short _is_inside_circle(
+cdef unsigned char _is_inside_circle(
     float_t x,  # point
     float_t y,
     float_t x0,  # circle center
@@ -1100,7 +1095,7 @@ cdef short _is_inside_circle(
 
 
 @cython.ufunc
-cdef short _is_inside_ellipse(
+cdef unsigned char _is_inside_ellipse(
     float_t x,  # point
     float_t y,
     float_t x0,  # ellipse center
@@ -1135,7 +1130,7 @@ cdef short _is_inside_ellipse(
 
 
 @cython.ufunc
-cdef short _is_inside_ellipse_(
+cdef unsigned char _is_inside_ellipse_(
     float_t x,  # point
     float_t y,
     float_t x0,  # ellipse center
@@ -1164,7 +1159,7 @@ cdef short _is_inside_ellipse_(
 
 
 @cython.ufunc
-cdef short _is_inside_stadium(
+cdef unsigned char _is_inside_stadium(
     float_t x,  # point
     float_t y,
     float_t x0,  # line start
@@ -1210,7 +1205,7 @@ _is_near_segment = _is_inside_stadium
 
 
 @cython.ufunc
-cdef short _is_near_line(
+cdef unsigned char _is_near_line(
     float_t x,  # point
     float_t y,
     float_t x0,  # line start
@@ -1476,7 +1471,7 @@ cdef float_t _distance_from_line(
 
 
 @cython.ufunc
-cdef (double, double, double) _segment_direction_and_length(
+cdef (float_t, float_t, float_t) _segment_direction_and_length(
     float_t x0,  # segment start
     float_t y0,
     float_t x1,  # segment end
@@ -1500,7 +1495,7 @@ cdef (double, double, double) _segment_direction_and_length(
 
 
 @cython.ufunc
-cdef (double, double, double, double) _intersection_circle_circle(
+cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
     float_t x0,  # circle 0
     float_t y0,
     float_t r0,
@@ -1538,15 +1533,15 @@ cdef (double, double, double, double) _intersection_circle_circle(
     hd = sqrt(dd) / dr
     ld = ll / dr
     return (
-        ld * dx + hd * dy + x0,
-        ld * dy - hd * dx + y0,
-        ld * dx - hd * dy + x0,
-        ld * dy + hd * dx + y0,
+        <float_t> (ld * dx + hd * dy + x0),
+        <float_t> (ld * dy - hd * dx + y0),
+        <float_t> (ld * dx - hd * dy + x0),
+        <float_t> (ld * dy + hd * dx + y0),
     )
 
 
 @cython.ufunc
-cdef (double, double, double, double) _intersection_circle_line(
+cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
     float_t x,  # circle
     float_t y,
     float_t r,
@@ -1581,10 +1576,10 @@ cdef (double, double, double, double) _intersection_circle_line(
         return NAN, NAN, NAN, NAN
     rdd = sqrt(rdd)
     return (
-        x + (dd * dy + copysign(1.0, dy) * dx * rdd) / dr,
-        y + (-dd * dx + fabs(dy) * rdd) / dr,
-        x + (dd * dy - copysign(1.0, dy) * dx * rdd) / dr,
-        y + (-dd * dx - fabs(dy) * rdd) / dr,
+        x + <float_t> ((dd * dy + copysign(1.0, dy) * dx * rdd) / dr),
+        y + <float_t> ((-dd * dx + fabs(dy) * rdd) / dr),
+        x + <float_t> ((dd * dy - copysign(1.0, dy) * dx * rdd) / dr),
+        y + <float_t> ((-dd * dx - fabs(dy) * rdd) / dr),
     )
 
 
@@ -1665,7 +1660,7 @@ cdef float_t _blend_lighten(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_open(
+cdef (float_t, float_t, float_t) _phasor_threshold_open(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1727,7 +1722,7 @@ cdef (double, double, double) _phasor_threshold_open(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_closed(
+cdef (float_t, float_t, float_t) _phasor_threshold_closed(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1789,7 +1784,7 @@ cdef (double, double, double) _phasor_threshold_closed(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_mean_open(
+cdef (float_t, float_t, float_t) _phasor_threshold_mean_open(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1809,7 +1804,7 @@ cdef (double, double, double) _phasor_threshold_mean_open(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_mean_closed(
+cdef (float_t, float_t, float_t) _phasor_threshold_mean_closed(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1829,7 +1824,7 @@ cdef (double, double, double) _phasor_threshold_mean_closed(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_nan(
+cdef (float_t, float_t, float_t) _phasor_threshold_nan(
     float_t mean,
     float_t real,
     float_t imag,
@@ -2171,6 +2166,7 @@ def _median_filter_2d(
 # Decoder functions
 
 
+@cython.boundscheck(True)
 def _flimlabs_signal(
     uint_t[:, :, ::] signal,   # channel, pixel, bin
     list data,  # list[list[list[[int, int]]]]
@@ -2178,6 +2174,7 @@ def _flimlabs_signal(
 ):
     """Return TCSPC histogram image from FLIM LABS JSON intensity data."""
     cdef:
+        uint_t[::] signal_
         list channels, pixels
         ssize_t c, i, h, count
 
@@ -2186,18 +2183,21 @@ def _flimlabs_signal(
         for channels in data:
             i = 0
             for pixels in channels:
+                signal_ = signal[c, i]
                 for h, count in pixels:
-                    signal[c, i, h] = <uint_t> count
+                    signal_[h] = <uint_t> count
                 i += 1
             c += 1
     else:
         i = 0
         for pixels in data[channel]:
+            signal_ = signal[0, i]
             for h, count in pixels:
-                signal[0, i, h] = <uint_t> count
+                signal_[h] = <uint_t> count
             i += 1
 
 
+@cython.boundscheck(True)
 def _flimlabs_mean(
     float_t[:, ::] mean,   # channel, pixel
     list data,  # list[list[list[[int, int]]]]
@@ -2205,6 +2205,7 @@ def _flimlabs_mean(
 ):
     """Return mean intensity image from FLIM LABS JSON intensity data."""
     cdef:
+        float_t[::] mean_
         list channels, pixels
         ssize_t c, i, h, count
         double sum
@@ -2212,19 +2213,21 @@ def _flimlabs_mean(
     if channel < 0:
         c = 0
         for channels in data:
+            mean_ = mean[c]
             i = 0
             for pixels in channels:
                 sum = 0.0
                 for h, count in pixels:
                     sum += <double> count
-                mean[c, i] = <float_t> (sum / 255.0)
+                mean_[i] = <float_t> (sum / 256.0)
                 i += 1
             c += 1
     else:
         i = 0
+        mean_ = mean[0]
         for pixels in data[channel]:
             sum = 0.0
             for h, count in pixels:
                 sum += <double> count
-            mean[0, i] = <float_t> (sum / 255.0)
+            mean_[i] = <float_t> (sum / 256.0)
             i += 1

phasorpy/_utils.py

@@ -2,26 +2,29 @@
 
 from __future__ import annotations
 
-__all__: list[str] = [
+__all__ = [
     'chunk_iter',
     'dilate_coordinates',
     'kwargs_notnone',
     'parse_harmonic',
     'parse_kwargs',
     'parse_signal_axis',
+    'parse_skip_axis',
     'phasor_from_polar_scalar',
     'phasor_to_polar_scalar',
     'scale_matrix',
+    'set_module',
     'sort_coordinates',
     'update_kwargs',
 ]
 
 import math
 import numbers
+from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ._typing import Any, Sequence, ArrayLike, Literal, NDArray, Iterator
+    from ._typing import Any, ArrayLike, Literal, NDArray, Iterator
 
 import numpy
 
@@ -268,7 +271,7 @@ def parse_signal_axis(
     -------
     axis : int
         Axis over which phasor coordinates are computed.
-    axis_label: str
+    axis_label : str
         Axis label from `signal.dims` if any.
 
     Raises
@@ -312,6 +315,65 @@ def parse_signal_axis(
     raise ValueError(f'{axis=} not valid for {type(signal)=}')
 
 
+def parse_skip_axis(
+    skip_axis: int | Sequence[int] | None,
+    /,
+    ndim: int,
+    prepend_axis: bool = False,
+) -> tuple[tuple[int, ...], tuple[int, ...]]:
+    """Return axes to skip and not to skip.
+
+    This helper function is used to validate and parse `skip_axis`
+    parameters.
+
+    Parameters
+    ----------
+    skip_axis : int or sequence of int, optional
+        Axes to skip. If None, no axes are skipped.
+    ndim : int
+        Dimensionality of array in which to skip axes.
+    prepend_axis : bool, optional
+        Prepend one dimension and include in `skip_axis`.
+
+    Returns
+    -------
+    skip_axis : tuple of int
+        Ordered, positive values of `skip_axis`.
+    other_axis : tuple of int
+        Axes indices not included in `skip_axis`.
+
+    Raises
+    ------
+    IndexError
+        If any `skip_axis` value is out of bounds of `ndim`.
+
+    Examples
+    --------
+    >>> parse_skip_axis((1, -2), 5)
+    ((1, 3), (0, 2, 4))
+
+    >>> parse_skip_axis((1, -2), 5, True)
+    ((0, 2, 4), (1, 3, 5))
+
+    """
+    if ndim < 0:
+        raise ValueError(f'invalid {ndim=}')
+    if skip_axis is None:
+        if prepend_axis:
+            return (0,), tuple(range(1, ndim + 1))
+        return (), tuple(range(ndim))
+    if not isinstance(skip_axis, Sequence):
+        skip_axis = (skip_axis,)
+    if any(i >= ndim or i < -ndim for i in skip_axis):
+        raise IndexError(f'skip_axis={skip_axis} out of range for {ndim=}')
+    skip_axis = sorted(int(i % ndim) for i in skip_axis)
+    if prepend_axis:
+        skip_axis = [0] + [i + 1 for i in skip_axis]
+        ndim += 1
+    other_axis = tuple(i for i in range(ndim) if i not in skip_axis)
+    return tuple(skip_axis), other_axis
+
+
 def parse_harmonic(
     harmonic: int | Sequence[int] | Literal['all'] | str | None,
     harmonic_max: int | None = None,
@@ -343,7 +405,7 @@ def parse_harmonic(
     Raises
     ------
     IndexError
-        Any element is out of range `[1..harmonic_max]`.
+        Any element is out of range `[1, harmonic_max]`.
     ValueError
         Elements are not unique.
         Harmonic is empty.
@@ -364,7 +426,7 @@ def parse_harmonic(
         if harmonic < 1 or (
             harmonic_max is not None and harmonic > harmonic_max
         ):
-            raise IndexError(f'{harmonic=} out of range [1..{harmonic_max}]')
+            raise IndexError(f'{harmonic=} out of range [1, {harmonic_max}]')
         return [int(harmonic)], False
 
     if isinstance(harmonic, str):
@@ -376,7 +438,7 @@ def parse_harmonic(
             return list(range(1, harmonic_max + 1)), True
         raise ValueError(f'{harmonic=!r} is not a valid harmonic')
 
-    h = numpy.atleast_1d(numpy.asarray(harmonic))
+    h = numpy.atleast_1d(harmonic)
     if h.size == 0:
         raise ValueError(f'{harmonic=} is empty')
     if h.dtype.kind not in 'iu' or h.ndim != 1:
@@ -387,7 +449,7 @@ def parse_harmonic(
         raise IndexError(f'{harmonic=} element > {harmonic_max}]')
     if numpy.unique(h).size != h.size:
         raise ValueError(f'{harmonic=} elements must be unique')
-    return h.tolist(), True
+    return [int(i) for i in harmonic], True
 
 
 def chunk_iter(
@@ -517,3 +579,23 @@ def chunk_iter(
                 for i in range(ndim)
             ),
         )
+
+
+def set_module(globs: dict[str, Any], /) -> None:
+    """Set ``__module__`` attribute for objects in ``__all__``.
+
+    Parameters
+    ----------
+    globs : dict
+        Module namespace to modify.
+
+    Examples
+    --------
+    >>> set_module(globals())
+
+    """
+    name = globs['__name__']
+    for item in globs['__all__']:
+        obj = globs[item]
+        if hasattr(obj, '__module__'):
+            obj.__module__ = name

phasorpy/cli.py

@@ -8,6 +8,8 @@ Invoke the command line application with::
 
 from __future__ import annotations
 
+__all__: list[str] = []
+
 import os
 from typing import TYPE_CHECKING
 

phasorpy/cluster.py

@@ -0,0 +1,170 @@
+"""Cluster phasor coordinates.
+
+The `phasorpy.cluster` module provides functions to:
+
+- fit elliptic clusters to phasor coordinates using
+  Gaussian Mixture Model (GMM):
+
+  - :py:func:`phasor_cluster_gmm`
+
+"""
+
+from __future__ import annotations
+
+__all__ = ['phasor_cluster_gmm']
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._typing import Any, ArrayLike
+
+import math
+
+import numpy
+from sklearn.mixture import GaussianMixture
+
+
+def phasor_cluster_gmm(
+    real: ArrayLike,
+    imag: ArrayLike,
+    /,
+    *,
+    sigma: float = 2.0,
+    clusters: int = 1,
+    **kwargs: Any,
+) -> tuple[
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+]:
+    """Return elliptic clusters in phasor coordinates using GMM.
+
+    Fit a Gaussian Mixture Model (GMM) to the provided phasor coordinates and
+    extract the parameters of ellipses that represent each cluster according
+    to [1]_.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    sigma: float, default = 2.0
+        Scaling factor for radii of major and minor axes.
+        Defaults to 2, which corresponds to the scaling of eigenvalues for a
+        95% confidence ellipse.
+    clusters : int, optional
+        Number of Gaussian distributions to fit to phasor coordinates.
+        Defaults to 1.
+    **kwargs
+        Additional keyword arguments passed to
+        :py:class:`sklearn.mixture.GaussianMixture`.
+
+        Common options include:
+
+        - covariance_type : {'full', 'tied', 'diag', 'spherical'}
+        - max_iter : int, maximum number of EM iterations
+        - random_state : int, for reproducible results
+
+    Returns
+    -------
+    center_real : tuple of float
+        Real component of ellipse centers.
+    center_imag : tuple of float
+        Imaginary component of ellipse centers.
+    radius_major : tuple of float
+        Major radii of ellipses.
+    radius_minor : tuple of float
+        Minor radii of ellipses.
+    angle : tuple of float
+        Rotation angles of major axes in radians, within range [0, pi].
+
+    Raises
+    ------
+    ValueError
+        If the array shapes of `real` and `imag` do not match.
+        If `clusters` is not a positive integer.
+
+
+    References
+    ----------
+    .. [1] Vallmitjana A, Torrado B, and Gratton E.
+      `Phasor-based image segmentation: machine learning clustering techniques
+      <https://doi.org/10.1364/BOE.422766>`_.
+      *Biomed Opt Express*, 12(6): 3410-3422 (2021).
+
+    Examples
+    --------
+    Recover the clusters from a synthetic distribution of phasor coordinates
+    with two clusters:
+
+    >>> real1, imag1 = numpy.random.multivariate_normal(
+    ...     [0.2, 0.3], [[3e-3, 1e-3], [1e-3, 2e-3]], 100
+    ... ).T
+    >>> real2, imag2 = numpy.random.multivariate_normal(
+    ...     [0.4, 0.5], [[2e-3, -1e-3], [-1e-3, 3e-3]], 100
+    ... ).T
+    >>> real = numpy.concatenate([real1, real2])
+    >>> imag = numpy.concatenate([imag1, imag2])
+    >>> center_real, center_imag, radius_major, radius_minor, angle = (
+    ...     phasor_cluster_gmm(real, imag, clusters=2)
+    ... )
+    >>> centers_real  # doctest: +SKIP
+    (0.2, 0.4)
+
+    """
+    coords = numpy.stack((real, imag), axis=-1).reshape(-1, 2)
+
+    valid_data = ~numpy.isnan(coords).any(axis=1)
+    coords = coords[valid_data]
+
+    kwargs.pop('n_components', None)
+
+    gmm = GaussianMixture(n_components=clusters, **kwargs)
+    gmm.fit(coords)
+
+    center_real = []
+    center_imag = []
+    radius_major = []
+    radius_minor = []
+    angle = []
+
+    for i in range(clusters):
+        center_real.append(float(gmm.means_[i, 0]))
+        center_imag.append(float(gmm.means_[i, 1]))
+
+        if gmm.covariance_type == 'full':
+            cov = gmm.covariances_[i]
+        elif gmm.covariance_type == 'tied':
+            cov = gmm.covariances_
+        elif gmm.covariance_type == 'diag':
+            cov = numpy.diag(gmm.covariances_[i])
+        else:  # 'spherical'
+            cov = numpy.eye(2) * gmm.covariances_[i]
+
+        eigenvalues, eigenvectors = numpy.linalg.eigh(cov[:2, :2])
+
+        idx = eigenvalues.argsort()[::-1]
+        eigenvalues = eigenvalues[idx]
+        eigenvectors = eigenvectors[:, idx]
+
+        major_vector = eigenvectors[:, 0]
+        current_angle = math.atan2(major_vector[1], major_vector[0])
+
+        if current_angle < 0:
+            current_angle += math.pi
+
+        angle.append(float(current_angle))
+
+        radius_major.append(sigma * math.sqrt(2 * eigenvalues[0]))
+        radius_minor.append(sigma * math.sqrt(2 * eigenvalues[1]))
+
+    return (
+        tuple(center_real),
+        tuple(center_imag),
+        tuple(radius_major),
+        tuple(radius_minor),
+        tuple(angle),
+    )