phasorpy 0.3__cp312-cp312-win_amd64.whl → 0.5__cp312-cp312-win_amd64.whl

phasorpy/phasor.py

@@ -59,13 +59,14 @@ 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`
 
 """
@@ -83,6 +84,7 @@ __all__ = [
     'phasor_center',
     'phasor_divide',
     'phasor_filter_median',
+    'phasor_filter_pawflim',
     'phasor_from_apparent_lifetime',
     'phasor_from_fret_acceptor',
     'phasor_from_fret_donor',
@@ -149,7 +151,7 @@ from ._phasorpy import (
     _polar_from_single_lifetime,
     _polar_to_apparent_lifetime,
 )
-from ._utils import parse_harmonic
+from ._utils import parse_harmonic, parse_signal_axis, parse_skip_axis
 from .utils import number_threads
 
 
@@ -157,7 +159,7 @@ def phasor_from_signal(
     signal: ArrayLike,
     /,
     *,
-    axis: int = -1,
+    axis: int | str | None = None,
     harmonic: int | Sequence[int] | Literal['all'] | str | None = None,
     sample_phase: ArrayLike | None = None,
     use_fft: bool | None = None,
@@ -174,9 +176,10 @@ def phasor_from_signal(
         Frequency-domain, time-domain, or hyperspectral data.
         A minimum of three samples are required along `axis`.
         The samples must be uniformly spaced.
-    axis : int, optional
+    axis : int or str, optional
         Axis over which to compute phasor coordinates.
-        The default is the last axis (-1).
+        By default, the 'H' or 'C' axes if signal contains such dimension
+        names, else the last axis (-1).
     harmonic : int, sequence of int, or 'all', optional
         Harmonics to return.
         If `'all'`, return all harmonics for `signal` samples along `axis`.
@@ -287,6 +290,9 @@ def phasor_from_signal(
     """
     # TODO: C-order not required by rfft?
     # TODO: preserve array subtypes?
+
+    axis, _ = parse_signal_axis(signal, axis)
+
     signal = numpy.asarray(signal, order='C')
     if signal.dtype.kind not in 'uif':
         raise TypeError(f'signal must be real valued, not {signal.dtype=}')
@@ -498,7 +504,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')
@@ -591,7 +598,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
@@ -679,7 +686,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'
@@ -745,9 +752,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
     ------
@@ -1046,9 +1053,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)
@@ -1154,7 +1159,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
     --------
@@ -1243,16 +1249,34 @@ def phasor_calibrate(
 
     has_harmonic_axis = reference_mean.ndim + 1 == reference_real.ndim
     harmonic, _ = parse_harmonic(
-        harmonic, reference_real.shape[0] if has_harmonic_axis else None
+        harmonic,
+        (
+            reference_real.shape[0]
+            if has_harmonic_axis
+            and isinstance(harmonic, str)
+            and harmonic == 'all'
+            else None
+        ),
     )
 
+    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:]=}'
@@ -1264,9 +1288,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,
@@ -1284,6 +1305,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
     )
@@ -1292,9 +1331,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)
@@ -1966,6 +2002,7 @@ def lifetime_fraction_from_amplitude(
     array([0.8, 0.2])
 
     """
+    t: NDArray[numpy.float64]
     t = numpy.multiply(amplitude, lifetime, dtype=numpy.float64)
     t /= numpy.sum(t, axis=axis, keepdims=True)
     return t
@@ -2421,7 +2458,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,
@@ -2447,9 +2484,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.
@@ -2490,7 +2527,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,
@@ -2504,7 +2541,7 @@ def phasor_from_fret_donor(
         omega,
         donor_lifetime,
         fret_efficiency,
-        donor_freting,
+        donor_fretting,
         donor_background,
         background_real,
         background_imag,
@@ -2518,7 +2555,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,
@@ -2551,9 +2588,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.
@@ -2606,7 +2643,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,
@@ -2623,7 +2660,7 @@ def phasor_from_fret_acceptor(
         donor_lifetime,
         acceptor_lifetime,
         fret_efficiency,
-        donor_freting,
+        donor_fretting,
         donor_bleedthrough,
         acceptor_bleedthrough,
         acceptor_background,
@@ -2708,7 +2745,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>`_.
@@ -2920,7 +2957,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:
@@ -2994,6 +3031,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,
@@ -3302,7 +3542,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)
 
@@ -3346,62 +3586,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