phasorpy 0.5__cp313-cp313-win_amd64.whl → 0.6__cp313-cp313-win_amd64.whl

phasorpy/phasor.py

@@ -17,6 +17,7 @@ The ``phasorpy.phasor`` module provides functions to:
   - :py:func:`phasor_from_lifetime`
   - :py:func:`phasor_from_apparent_lifetime`
   - :py:func:`phasor_to_apparent_lifetime`
+  - :py:func:`phasor_to_normal_lifetime`
 
 - convert to and from polar coordinates (phase and modulation):
 
@@ -69,6 +70,10 @@ The ``phasorpy.phasor`` module provides functions to:
   - :py:func:`phasor_filter_pawflim`
   - :py:func:`phasor_threshold`
 
+- find nearest neighbor phasor coordinates from another set of phasor coordinates:
+
+  - :py:func:`phasor_nearest_neighbor`
+
 """
 
 from __future__ import annotations
@@ -92,11 +97,14 @@ __all__ = [
     'phasor_from_polar',
     'phasor_from_signal',
     'phasor_multiply',
+    'phasor_nearest_neighbor',
     'phasor_normalize',
     'phasor_semicircle',
+    'phasor_semicircle_intersect',
     'phasor_threshold',
     'phasor_to_apparent_lifetime',
     'phasor_to_complex',
+    'phasor_to_normal_lifetime',
     'phasor_to_polar',
     'phasor_to_principal_plane',
     'phasor_to_signal',
@@ -125,7 +133,9 @@ import numpy
 
 from ._phasorpy import (
     _gaussian_signal,
+    _intersect_semicircle_line,
     _median_filter_2d,
+    _nearest_neighbor_2d,
     _phasor_at_harmonic,
     _phasor_divide,
     _phasor_from_apparent_lifetime,
@@ -142,6 +152,7 @@ from ._phasorpy import (
     _phasor_threshold_nan,
     _phasor_threshold_open,
     _phasor_to_apparent_lifetime,
+    _phasor_to_normal_lifetime,
     _phasor_to_polar,
     _phasor_transform,
     _phasor_transform_const,
@@ -674,7 +685,7 @@ def lifetime_to_signal(
         mean = 1.0
     mean = numpy.asarray(mean)
     mean -= background
-    if numpy.any(mean <= 0.0):
+    if numpy.any(mean < 0.0):
         raise ValueError('mean - background must not be less than zero')
 
     scale = samples / (2.0 * math.pi)
@@ -794,6 +805,65 @@ def phasor_semicircle(
     return real, imag
 
 
+def phasor_semicircle_intersect(
+    real0: ArrayLike,
+    imag0: ArrayLike,
+    real1: ArrayLike,
+    imag1: ArrayLike,
+    /,
+    **kwargs: Any,
+) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any], NDArray[Any]]:
+    """Return intersection of line through phasors with universal semicircle.
+
+    Return the phasor coordinates of two intersections of the universal
+    semicircle with the line between two phasor coordinates.
+    Return NaN if the line does not intersect the semicircle.
+
+    Parameters
+    ----------
+    real0 : array_like
+        Real component of first set of phasor coordinates.
+    imag0 : array_like
+        Imaginary component of first set of phasor coordinates.
+    real1 : array_like
+        Real component of second set of phasor coordinates.
+    imag1 : array_like
+        Imaginary component of second set of phasor coordinates.
+    **kwargs
+        Optional `arguments passed to numpy universal functions
+        <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
+
+    Returns
+    -------
+    real0 : ndarray
+        Real component of first intersect of phasors with semicircle.
+    imag0 : ndarray
+        Imaginary component of first intersect of phasors with semicircle.
+    real1 : ndarray
+        Real component of second intersect of phasors with semicircle.
+    imag1 : ndarray
+        Imaginary component of second intersect of phasors with semicircle.
+
+    Examples
+    --------
+    Calculate two intersects of a line through two phasor coordinates
+    with the universal semicircle:
+
+    >>> phasor_semicircle_intersect(0.2, 0.25, 0.6, 0.25)  # doctest: +NUMBER
+    (0.066, 0.25, 0.933, 0.25)
+
+    The line between two phasor coordinates may not intersect the semicircle
+    at two points:
+
+    >>> phasor_semicircle_intersect(0.2, 0.0, 0.6, 0.25)  # doctest: +NUMBER
+    (nan, nan, 0.817, 0.386)
+
+    """
+    return _intersect_semicircle_line(  # type: ignore[no-any-return]
+        real0, imag0, real1, imag1, **kwargs
+    )
+
+
 def phasor_to_complex(
     real: ArrayLike,
     imag: ArrayLike,
@@ -1577,6 +1647,7 @@ def phasor_to_polar(
     See Also
     --------
     phasorpy.phasor.phasor_from_polar
+    :ref:`sphx_glr_tutorials_phasorpy_lifetime_geometry.py`
 
     Examples
     --------
@@ -1684,6 +1755,7 @@ def phasor_to_apparent_lifetime(
     See Also
     --------
     phasorpy.phasor.phasor_from_apparent_lifetime
+    :ref:`sphx_glr_tutorials_phasorpy_lifetime_geometry.py`
 
     Notes
     -----
@@ -1819,6 +1891,86 @@ def phasor_from_apparent_lifetime(
     )
 
 
+def phasor_to_normal_lifetime(
+    real: ArrayLike,
+    imag: ArrayLike,
+    /,
+    frequency: ArrayLike,
+    *,
+    unit_conversion: float = 1e-3,
+    **kwargs: Any,
+) -> NDArray[Any]:
+    r"""Return normal lifetimes from phasor coordinates.
+
+    The normal lifetime of phasor coordinates represents the single lifetime
+    equivalent corresponding to the perpendicular projection of the coordinates
+    onto the universal semicircle, as defined in [3]_.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    frequency : array_like
+        Laser pulse or modulation frequency in MHz.
+    unit_conversion : float, optional
+        Product of `frequency` and returned `lifetime` units' prefix factors.
+        The default is 1e-3 for MHz and ns, or Hz and ms.
+        Use 1.0 for Hz and s.
+    **kwargs
+        Optional `arguments passed to numpy universal functions
+        <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
+
+    Returns
+    -------
+    normal_lifetime : ndarray
+        Normal lifetime from of phasor coordinates.
+
+    See Also
+    --------
+    :ref:`sphx_glr_tutorials_phasorpy_lifetime_geometry.py`
+
+    Notes
+    -----
+    The phasor coordinates `real` (:math:`G`) and `imag` (:math:`S`)
+    are converted to normal lifetimes `normal_lifetime` (:math:`\tau_{N}`)
+    at frequency :math:`f` according to:
+
+    .. math::
+
+        \omega &= 2 \pi f
+
+        G_{N} &= 0.5 \cdot (1 + \cos{\arctan{\frac{S}{G - 0.5}}})
+
+        \tau_{N} &= \sqrt{\frac{1 - G_{N}}{\omega^{2} \cdot G_{N}}}
+
+    References
+    ----------
+
+    .. [3] Silberberg M, and Grecco H. `pawFLIM: reducing bias and
+      uncertainty to enable lower photon count in FLIM experiments
+      <https://doi.org/10.1088/2050-6120/aa72ab>`_.
+      *Methods Appl Fluoresc*, 5(2): 024016 (2017)
+
+    Examples
+    --------
+    The normal lifetimes of phasor coordinates with a real component of 0.5
+    are independent of the imaginary component:
+
+    >>> phasor_to_normal_lifetime(
+    ...     0.5, [0.5, 0.45], frequency=80
+    ... )  # doctest: +NUMBER
+    array([1.989, 1.989])
+
+    """
+    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega *= math.pi * 2.0 * unit_conversion
+    return _phasor_to_normal_lifetime(  # type: ignore[no-any-return]
+        real, imag, omega, **kwargs
+    )
+
+
 def lifetime_to_frequency(
     lifetime: ArrayLike,
     *,
@@ -2138,6 +2290,11 @@ def phasor_from_lifetime(
     ValueError
         Input arrays exceed their allowed dimensionality or do not match.
 
+    See Also
+    --------
+    :ref:`sphx_glr_tutorials_api_phasorpy_phasor_from_lifetime.py`
+    :ref:`sphx_glr_tutorials_phasorpy_lifetime_geometry.py`
+
     Notes
     -----
     The phasor coordinates :math:`G` (`real`) and :math:`S` (`imag`) for
@@ -2517,6 +2674,7 @@ def phasor_from_fret_donor(
     --------
     phasorpy.phasor.phasor_from_fret_acceptor
     :ref:`sphx_glr_tutorials_api_phasorpy_fret.py`
+    :ref:`sphx_glr_tutorials_applications_phasorpy_fret_efficiency.py`
 
     Examples
     --------
@@ -3452,6 +3610,154 @@ def phasor_threshold(
     return mean, real, imag
 
 
+def phasor_nearest_neighbor(
+    real: ArrayLike,
+    imag: ArrayLike,
+    neighbor_real: ArrayLike,
+    neighbor_imag: ArrayLike,
+    /,
+    *,
+    values: ArrayLike | None = None,
+    dtype: DTypeLike | None = None,
+    distance_max: float | None = None,
+    num_threads: int | None = None,
+) -> NDArray[Any]:
+    """Return indices or values of nearest neighbor from other coordinates.
+
+    For each phasor coordinate, find the nearest neighbor in another set of
+    phasor coordinates and return its flat index. If more than one neighbor
+    has the same distance, return the smallest index.
+
+    For phasor coordinates that are NaN, or have a distance to the nearest
+    neighbor that is larger than `distance_max`, return an index of -1.
+
+    If `values` are provided, return the values corresponding to the nearest
+    neighbor coordinates instead of indices. Return NaN values for indices
+    that are -1.
+
+    This function does not support multi-harmonic, multi-channel, or
+    multi-frequency phasor coordinates.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    neighbor_real : array_like
+        Real component of neighbor phasor coordinates.
+    neighbor_imag : array_like
+        Imaginary component of neighbor phasor coordinates.
+    values : array_like, optional
+        Array of values corresponding to neighbor coordinates.
+        If provided, return the values corresponding to the nearest
+        neighbor coordinates.
+    distance_max : float, optional
+        Maximum Euclidean distance to consider a neighbor valid.
+        By default, all neighbors are considered.
+    dtype : dtype_like, optional
+        Floating point data type used for calculation and output values.
+        Either `float32` or `float64`. The default is `float64`.
+    num_threads : int, optional
+        Number of OpenMP threads to use for parallelization.
+        By default, multi-threading is disabled.
+        If zero, up to half of logical CPUs are used.
+        OpenMP may not be available on all platforms.
+
+    Returns
+    -------
+    nearest : ndarray
+        Flat indices (or the corresponding values if provided) of the nearest
+        neighbor coordinates.
+
+    Raises
+    ------
+    ValueError
+        If the shapes of `real`, and `imag` do not match.
+        If the shapes of `neighbor_real` and `neighbor_imag` do not match.
+        If the shapes of `values` and `neighbor_real` do not match.
+        If `distance_max` is less than or equal to zero.
+
+    See Also
+    --------
+    :ref:`sphx_glr_tutorials_applications_phasorpy_fret_efficiency.py`
+
+    Notes
+    -----
+    This function uses linear search, which is inefficient for large
+    number of coordinates or neighbors.
+    ``scipy.spatial.KDTree.query()`` would be more efficient in those cases.
+    However, KDTree is known to return non-deterministic results in case of
+    multiple neighbors with the same distance.
+
+    Examples
+    --------
+    >>> phasor_nearest_neighbor(
+    ...     [0.1, 0.5, numpy.nan],
+    ...     [0.1, 0.5, numpy.nan],
+    ...     [0, 0.4],
+    ...     [0, 0.4],
+    ...     values=[10, 20],
+    ... )
+    array([10, 20, nan])
+
+    """
+    dtype = numpy.dtype(dtype)
+    if dtype.char not in {'f', 'd'}:
+        raise ValueError(f'{dtype=} is not a floating point type')
+
+    real = numpy.ascontiguousarray(real, dtype=dtype)
+    imag = numpy.ascontiguousarray(imag, dtype=dtype)
+    neighbor_real = numpy.ascontiguousarray(neighbor_real, dtype=dtype)
+    neighbor_imag = numpy.ascontiguousarray(neighbor_imag, dtype=dtype)
+
+    if real.shape != imag.shape:
+        raise ValueError(f'{real.shape=} != {imag.shape=}')
+    if neighbor_real.shape != neighbor_imag.shape:
+        raise ValueError(f'{neighbor_real.shape=} != {neighbor_imag.shape=}')
+
+    shape = real.shape
+    real = real.ravel()
+    imag = imag.ravel()
+    neighbor_real = neighbor_real.ravel()
+    neighbor_imag = neighbor_imag.ravel()
+
+    indices = numpy.empty(
+        real.shape, numpy.min_scalar_type(-neighbor_real.size)
+    )
+
+    if distance_max is None:
+        distance_max = numpy.inf
+    else:
+        distance_max = float(distance_max)
+        if distance_max <= 0:
+            raise ValueError(f'{distance_max=} <= 0')
+
+    num_threads = number_threads(num_threads)
+
+    _nearest_neighbor_2d(
+        indices,
+        real,
+        imag,
+        neighbor_real,
+        neighbor_imag,
+        distance_max,
+        num_threads,
+    )
+
+    if values is None:
+        return numpy.asarray(indices.reshape(shape))
+
+    values = numpy.ascontiguousarray(values, dtype=dtype).ravel()
+    if values.shape != neighbor_real.shape:
+        raise ValueError(f'{values.shape=} != {neighbor_real.shape=}')
+
+    nearest_values = values[indices]
+    nearest_values[indices == -1] = numpy.nan
+
+    return numpy.asarray(nearest_values.reshape(shape))
+
+
 def phasor_center(
     mean: ArrayLike,
     real: ArrayLike,

phasorpy/plot/__init__.py

@@ -0,0 +1,27 @@
+"""Plot phasor coordinates and related data.
+
+The ``phasorpy.plot`` module provides functions and classes to visualize
+phasor coordinates and related data using the
+`matplotlib <https://matplotlib.org/>`_ library.
+
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+
+from .._utils import init_module
+from ._functions import *
+from ._lifetime_plots import *
+from ._phasorplot import *
+from ._phasorplot_fret import *
+
+# The `init_module()` function dynamically populates the `__all__` list with
+# all public symbols imported from submodules or defined in this module.
+# Any name not starting with an underscore will be automatically exported
+# when using "from phasorpy.plot import *"
+
+init_module(globals())
+del init_module
+
+# flake8: noqa: F401, F403