phasorpy 0.4__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):
 
@@ -59,15 +60,20 @@ The ``phasorpy.phasor`` module provides functions to:
   - :py:func:`lifetime_fraction_from_amplitude`
   - :py:func:`lifetime_fraction_to_amplitude`
 
-- calculate phasor coordinates on semicircle at other harmonics:
+- calculate phasor coordinates on universal semicircle at other harmonics:
 
   - :py:func:`phasor_at_harmonic`
 
 - filter phasor coordinates:
 
   - :py:func:`phasor_filter_median`
+  - :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
@@ -83,6 +89,7 @@ __all__ = [
     'phasor_center',
     'phasor_divide',
     'phasor_filter_median',
+    'phasor_filter_pawflim',
     'phasor_from_apparent_lifetime',
     'phasor_from_fret_acceptor',
     'phasor_from_fret_donor',
@@ -90,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',
@@ -123,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,
@@ -140,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,
@@ -149,7 +162,7 @@ from ._phasorpy import (
     _polar_from_single_lifetime,
     _polar_to_apparent_lifetime,
 )
-from ._utils import parse_harmonic, parse_signal_axis
+from ._utils import parse_harmonic, parse_signal_axis, parse_skip_axis
 from .utils import number_threads
 
 
@@ -502,7 +515,8 @@ def phasor_to_signal(
     else:
         keepdims = mean.ndim > 0 or real.ndim > 0
 
-    mean, real = numpy.atleast_1d(mean, real)
+    mean = numpy.asarray(numpy.atleast_1d(mean))
+    real = numpy.asarray(numpy.atleast_1d(real))
 
     if real.dtype.kind != 'f' or imag.dtype.kind != 'f':
         raise ValueError(f'{real.dtype=} or {imag.dtype=} not floating point')
@@ -595,7 +609,7 @@ def lifetime_to_signal(
         or `1` to synthesize a homodyne signal.
     zero_phase : float, optional
         Position of instrument response function in radians.
-        Must be in range 0.0 to :math:`\pi`. The default is the 8th sample.
+        Must be in range [0, pi]. The default is the 8th sample.
     zero_stdev : float, optional
         Standard deviation of instrument response function in radians.
         Must be at least 1.5 samples and no more than one tenth of samples
@@ -671,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)
@@ -683,7 +697,7 @@ def lifetime_to_signal(
     stdev = zero_stdev * scale  # in sample units
 
     if zero_phase < 0 or zero_phase > 2.0 * math.pi:
-        raise ValueError(f'{zero_phase=} out of range [0 .. 2 pi]')
+        raise ValueError(f'{zero_phase=} out of range [0, 2 pi]')
     if stdev < 1.5:
         raise ValueError(
             f'{zero_stdev=} < {1.5 / scale} cannot be sampled sufficiently'
@@ -749,9 +763,9 @@ def phasor_semicircle(
     Returns
     -------
     real : ndarray
-        Real component of semicircle phasor coordinates.
+        Real component of phasor coordinates on universal semicircle.
     imag : ndarray
-        Imaginary component of semicircle phasor coordinates.
+        Imaginary component of phasor coordinates on universal semicircle.
 
     Raises
     ------
@@ -791,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,
@@ -1050,9 +1123,7 @@ def phasor_normalize(
     else:
         real = numpy.array(real_unnormalized, dtype, copy=True)
     imag = numpy.array(imag_unnormalized, real.dtype, copy=True)
-    mean = numpy.array(
-        mean_unnormalized, real.dtype, copy=None if samples == 1 else True
-    )
+    mean = numpy.array(mean_unnormalized, real.dtype, copy=True)
 
     with numpy.errstate(divide='ignore', invalid='ignore'):
         numpy.divide(real, mean, out=real)
@@ -1158,7 +1229,8 @@ def phasor_calibrate(
     ValueError
         The array shapes of `real` and `imag`, or `reference_real` and
         `reference_imag` do not match.
-        Number of harmonics does not match the first axis of `real` and `imag`.
+        Number of harmonics or frequencies does not match the first axis
+        of `real` and `imag`.
 
     See Also
     --------
@@ -1257,13 +1329,24 @@ def phasor_calibrate(
         ),
     )
 
+    frequency = numpy.asarray(frequency)
+    frequency = frequency * harmonic
+
     if has_harmonic_axis:
         if real.ndim == 0:
-            raise ValueError(f'{real.shape=} != {len(harmonic)=}')
-        if real.shape[0] != len(harmonic):
-            raise ValueError(f'{real.shape[0]=} != {len(harmonic)=}')
-        if reference_real.shape[0] != len(harmonic):
-            raise ValueError(f'{reference_real.shape[0]=} != {len(harmonic)=}')
+            raise ValueError(
+                f'{real.shape=} != {len(frequency)} frequencies or harmonics'
+            )
+        if real.shape[0] != len(frequency):
+            raise ValueError(
+                f'{real.shape[0]=} != {len(frequency)} '
+                'frequencies or harmonics'
+            )
+        if reference_real.shape[0] != len(frequency):
+            raise ValueError(
+                f'{reference_real.shape[0]=} != {len(frequency)} '
+                'frequencies or harmonics'
+            )
         if reference_mean.shape != reference_real.shape[1:]:
             raise ValueError(
                 f'{reference_mean.shape=} != {reference_real.shape[1:]=}'
@@ -1275,9 +1358,6 @@ def phasor_calibrate(
             f'{reference_mean.shape=} does not have harmonic axis'
         )
 
-    frequency = numpy.asarray(frequency)
-    frequency = frequency * harmonic
-
     _, measured_re, measured_im = phasor_center(
         reference_mean,
         reference_real,
@@ -1295,6 +1375,24 @@ def phasor_calibrate(
         unit_conversion=unit_conversion,
     )
 
+    skip_axis, axis = parse_skip_axis(
+        skip_axis, real.ndim - int(has_harmonic_axis), has_harmonic_axis
+    )
+
+    if has_harmonic_axis and any(skip_axis):
+        known_re = numpy.expand_dims(
+            known_re, tuple(range(1, measured_re.ndim))
+        )
+        known_re = numpy.broadcast_to(
+            known_re, (len(frequency), *measured_re.shape[1:])
+        )
+        known_im = numpy.expand_dims(
+            known_im, tuple(range(1, measured_im.ndim))
+        )
+        known_im = numpy.broadcast_to(
+            known_im, (len(frequency), *measured_im.shape[1:])
+        )
+
     phi_zero, mod_zero = polar_from_reference_phasor(
         measured_re, measured_im, known_re, known_im
     )
@@ -1303,9 +1401,6 @@ def phasor_calibrate(
         if reverse:
             numpy.negative(phi_zero, out=phi_zero)
             numpy.reciprocal(mod_zero, out=mod_zero)
-        _, axis = _parse_skip_axis(
-            skip_axis, real.ndim - int(has_harmonic_axis), has_harmonic_axis
-        )
         if axis is not None:
             phi_zero = numpy.expand_dims(phi_zero, axis=axis)
             mod_zero = numpy.expand_dims(mod_zero, axis=axis)
@@ -1552,6 +1647,7 @@ def phasor_to_polar(
     See Also
     --------
     phasorpy.phasor.phasor_from_polar
+    :ref:`sphx_glr_tutorials_phasorpy_lifetime_geometry.py`
 
     Examples
     --------
@@ -1659,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
     -----
@@ -1794,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,
     *,
@@ -2113,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
@@ -2433,7 +2615,7 @@ def phasor_from_fret_donor(
     donor_lifetime: ArrayLike,
     *,
     fret_efficiency: ArrayLike = 0.0,
-    donor_freting: ArrayLike = 1.0,
+    donor_fretting: ArrayLike = 1.0,
     donor_background: ArrayLike = 0.0,
     background_real: ArrayLike = 0.0,
     background_imag: ArrayLike = 0.0,
@@ -2459,9 +2641,9 @@ def phasor_from_fret_donor(
     donor_lifetime : array_like
         Lifetime of donor without FRET in ns.
     fret_efficiency : array_like, optional, default 0
-        FRET efficiency in range [0..1].
-    donor_freting : array_like, optional, default 1
-        Fraction of donors participating in FRET. Range [0..1].
+        FRET efficiency in range [0, 1].
+    donor_fretting : array_like, optional, default 1
+        Fraction of donors participating in FRET. Range [0, 1].
     donor_background : array_like, optional, default 0
         Weight of background fluorescence in donor channel
         relative to fluorescence of donor without FRET.
@@ -2492,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
     --------
@@ -2502,7 +2685,7 @@ def phasor_from_fret_donor(
     ...     frequency=80,
     ...     donor_lifetime=4.2,
     ...     fret_efficiency=[0.0, 0.3, 1.0],
-    ...     donor_freting=0.9,
+    ...     donor_fretting=0.9,
     ...     donor_background=0.1,
     ...     background_real=0.11,
     ...     background_imag=0.12,
@@ -2516,7 +2699,7 @@ def phasor_from_fret_donor(
         omega,
         donor_lifetime,
         fret_efficiency,
-        donor_freting,
+        donor_fretting,
         donor_background,
         background_real,
         background_imag,
@@ -2530,7 +2713,7 @@ def phasor_from_fret_acceptor(
     acceptor_lifetime: ArrayLike,
     *,
     fret_efficiency: ArrayLike = 0.0,
-    donor_freting: ArrayLike = 1.0,
+    donor_fretting: ArrayLike = 1.0,
     donor_bleedthrough: ArrayLike = 0.0,
     acceptor_bleedthrough: ArrayLike = 0.0,
     acceptor_background: ArrayLike = 0.0,
@@ -2563,9 +2746,9 @@ def phasor_from_fret_acceptor(
     acceptor_lifetime : array_like
         Lifetime of acceptor in ns.
     fret_efficiency : array_like, optional, default 0
-        FRET efficiency in range [0..1].
-    donor_freting : array_like, optional, default 1
-        Fraction of donors participating in FRET. Range [0..1].
+        FRET efficiency in range [0, 1].
+    donor_fretting : array_like, optional, default 1
+        Fraction of donors participating in FRET. Range [0, 1].
     donor_bleedthrough : array_like, optional, default 0
         Weight of donor fluorescence in acceptor channel
         relative to fluorescence of fully sensitized acceptor.
@@ -2618,7 +2801,7 @@ def phasor_from_fret_acceptor(
     ...     donor_lifetime=4.2,
     ...     acceptor_lifetime=3.0,
     ...     fret_efficiency=[0.0, 0.3, 1.0],
-    ...     donor_freting=0.9,
+    ...     donor_fretting=0.9,
     ...     donor_bleedthrough=0.1,
     ...     acceptor_bleedthrough=0.1,
     ...     acceptor_background=0.1,
@@ -2635,7 +2818,7 @@ def phasor_from_fret_acceptor(
         donor_lifetime,
         acceptor_lifetime,
         fret_efficiency,
-        donor_freting,
+        donor_fretting,
         donor_bleedthrough,
         acceptor_bleedthrough,
         acceptor_background,
@@ -2720,7 +2903,7 @@ def phasor_to_principal_plane(
     References
     ----------
 
-    .. [1] Franssen WMJ, Vergeldt FJ, Bader AN, van Amerongen H, & Terenzi C.
+    .. [1] Franssen WMJ, Vergeldt FJ, Bader AN, van Amerongen H, and Terenzi C.
       `Full-harmonics phasor analysis: unravelling multiexponential trends
       in magnetic resonance imaging data
       <https://doi.org/10.1021/acs.jpclett.0c02319>`_.
@@ -2932,7 +3115,7 @@ def phasor_filter_median(
         raise ValueError(f'{real.shape=} != {imag.shape=}')
 
     prepend_axis = mean.ndim + 1 == real.ndim
-    _, axes = _parse_skip_axis(skip_axis, mean.ndim, prepend_axis)
+    _, axes = parse_skip_axis(skip_axis, mean.ndim, prepend_axis)
 
     # in case mean is also filtered
     # if prepend_axis:
@@ -3006,6 +3189,209 @@ def phasor_filter_median(
     return mean, real, imag
 
 
+def phasor_filter_pawflim(
+    mean: ArrayLike,
+    real: ArrayLike,
+    imag: ArrayLike,
+    /,
+    *,
+    sigma: float = 2.0,
+    levels: int = 1,
+    harmonic: Sequence[int] | None = None,
+    skip_axis: int | Sequence[int] | None = None,
+) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any]]:
+    """Return pawFLIM wavelet-filtered phasor coordinates.
+
+    This function must only be used with calibrated, unprocessed phasor
+    coordinates obtained from FLIM data. The coordinates must not be filtered,
+    thresholded, or otherwise pre-processed.
+
+    The pawFLIM wavelet filter is described in [2]_.
+
+    Parameters
+    ----------
+    mean : array_like
+        Intensity of phasor coordinates.
+    real : array_like
+        Real component of phasor coordinates to be filtered.
+        Must have at least two harmonics in the first axis.
+    imag : array_like
+        Imaginary component of phasor coordinates to be filtered.
+        Must have at least two harmonics in the first axis.
+    sigma : float, optional
+        Significance level to test difference between two phasors.
+        Given in terms of the equivalent 1D standard deviations.
+        sigma=2 corresponds to ~95% (or 5%) significance.
+    levels : int, optional
+        Number of levels for wavelet decomposition.
+        Controls the maximum averaging area, which has a length of
+        :math:`2^level`.
+    harmonic : sequence of int or None, optional
+        Harmonics included in first axis of `real` and `imag`.
+        If None (default), the first axis of `real` and `imag` contains lower
+        harmonics starting at and increasing by one.
+        All harmonics must have a corresponding half or double harmonic.
+    skip_axis : int or sequence of int, optional
+        Axes in `mean` to exclude from filter.
+        By default, all axes except harmonics are included.
+
+    Returns
+    -------
+    mean : ndarray
+        Unchanged intensity of phasor coordinates.
+    real : ndarray
+        Filtered real component of phasor coordinates.
+    imag : ndarray
+        Filtered imaginary component of phasor coordinates.
+
+    Raises
+    ------
+    ValueError
+        If `level` is less than 0.
+        The array shapes of `mean`, `real`, and `imag` do not match.
+        If `real` and `imag` have no harmonic axis.
+        Number of harmonics in `harmonic` is less than 2 or does not match
+        the first axis of `real` and `imag`.
+        Not all harmonics in `harmonic` have a corresponding half
+        or double harmonic.
+
+    References
+    ----------
+
+    .. [2] 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
+    --------
+    Apply a pawFLIM wavelet filter with four significance levels (sigma)
+    and three decomposition levels:
+
+    >>> mean, real, imag = phasor_filter_pawflim(
+    ...     [[1, 1], [1, 1]],
+    ...     [[[0.5, 0.8], [0.5, 0.8]], [[0.2, 0.4], [0.2, 0.4]]],
+    ...     [[[0.5, 0.4], [0.5, 0.4]], [[0.4, 0.5], [0.4, 0.5]]],
+    ...     sigma=4,
+    ...     levels=3,
+    ...     harmonic=[1, 2],
+    ... )
+    >>> mean
+    array([[1, 1],
+           [1, 1]])
+    >>> real
+    array([[[0.65, 0.65],
+            [0.65, 0.65]],
+           [[0.3, 0.3],
+            [0.3, 0.3]]])
+    >>> imag
+    array([[[0.45, 0.45],
+            [0.45, 0.45]],
+           [[0.45, 0.45],
+            [0.45, 0.45]]])
+
+    """
+    from pawflim import pawflim  # type: ignore[import-untyped]
+
+    mean = numpy.asarray(mean)
+    real = numpy.asarray(real)
+    imag = numpy.asarray(imag)
+
+    if levels < 0:
+        raise ValueError(f'{levels=} < 0')
+    if levels == 0:
+        return mean, real, imag
+
+    if mean.shape != real.shape[-mean.ndim if mean.ndim else 1 :]:
+        raise ValueError(f'{mean.shape=} != {real.shape=}')
+    if real.shape != imag.shape:
+        raise ValueError(f'{real.shape=} != {imag.shape=}')
+
+    has_harmonic_axis = mean.ndim + 1 == real.ndim
+    if not has_harmonic_axis:
+        raise ValueError('no harmonic axis')
+    if harmonic is None:
+        harmonics, _ = parse_harmonic('all', real.shape[0])
+    else:
+        harmonics, _ = parse_harmonic(harmonic, None)
+    if len(harmonics) < 2:
+        raise ValueError(
+            'at least two harmonics required, ' f'got {len(harmonics)}'
+        )
+    if len(harmonics) != real.shape[0]:
+        raise ValueError(
+            'number of harmonics does not match first axis of real and imag'
+        )
+
+    mean = numpy.asarray(numpy.nan_to_num(mean), dtype=float)
+    real = numpy.asarray(numpy.nan_to_num(real * mean), dtype=float)
+    imag = numpy.asarray(numpy.nan_to_num(imag * mean), dtype=float)
+
+    mean_expanded = numpy.broadcast_to(mean, real.shape).copy()
+    original_mean_expanded = mean_expanded.copy()
+    real_filtered = real.copy()
+    imag_filtered = imag.copy()
+
+    _, axes = parse_skip_axis(skip_axis, mean.ndim, True)
+
+    for index in numpy.ndindex(
+        *(
+            real.shape[ax]
+            for ax in range(real.ndim)
+            if ax not in axes and ax != 0
+        )
+    ):
+        index_list: list[int | slice] = list(index)
+        for ax in axes:
+            index_list = index_list[:ax] + [slice(None)] + index_list[ax:]
+        full_index = tuple(index_list)
+
+        processed_harmonics = set()
+
+        for h in harmonics:
+            if h in processed_harmonics and (
+                h * 4 in harmonics or h * 2 not in harmonics
+            ):
+                continue
+            if h * 2 not in harmonics:
+                raise ValueError(
+                    f'harmonic {h} does not have a corresponding half '
+                    f'or double harmonic in {harmonics}'
+                )
+            n = harmonics.index(h)
+            n2 = harmonics.index(h * 2)
+
+            complex_phasor = numpy.empty(
+                (3, *original_mean_expanded[n][full_index].shape),
+                dtype=complex,
+            )
+            complex_phasor[0] = original_mean_expanded[n][full_index]
+            complex_phasor[1] = real[n][full_index] + 1j * imag[n][full_index]
+            complex_phasor[2] = (
+                real[n2][full_index] + 1j * imag[n2][full_index]
+            )
+
+            complex_phasor = pawflim(
+                complex_phasor, n_sigmas=sigma, levels=levels
+            )
+
+            for i, idx in enumerate([n, n2]):
+                if harmonics[idx] in processed_harmonics:
+                    continue
+                mean_expanded[idx][full_index] = complex_phasor[0].real
+                real_filtered[idx][full_index] = complex_phasor[i + 1].real
+                imag_filtered[idx][full_index] = complex_phasor[i + 1].imag
+
+            processed_harmonics.add(h)
+            processed_harmonics.add(h * 2)
+
+    with numpy.errstate(divide='ignore', invalid='ignore'):
+        real = numpy.asarray(numpy.divide(real_filtered, mean_expanded))
+        imag = numpy.asarray(numpy.divide(imag_filtered, mean_expanded))
+
+    return mean, real, imag
+
+
 def phasor_threshold(
     mean: ArrayLike,
     real: ArrayLike,
@@ -3224,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,
@@ -3314,7 +3848,7 @@ def phasor_center(
         raise ValueError(f'{mean.shape=} != {real.shape=}')
 
     prepend_axis = mean.ndim + 1 == real.ndim
-    _, axis = _parse_skip_axis(skip_axis, mean.ndim, prepend_axis)
+    _, axis = parse_skip_axis(skip_axis, mean.ndim, prepend_axis)
     if prepend_axis:
         mean = numpy.expand_dims(mean, axis=0)
 
@@ -3358,62 +3892,3 @@ def _median(
         numpy.nanmedian(real, **kwargs),
         numpy.nanmedian(imag, **kwargs),
     )
-
-
-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
-        Ordered, positive values of `skip_axis`.
-    other_axis
-        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