phasorpy 0.1__cp312-cp312-win_amd64.whl → 0.2__cp312-cp312-win_amd64.whl

phasorpy/phasor.py

@@ -104,7 +104,6 @@ __all__ = [
 ]
 
 import math
-import numbers
 from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
@@ -122,6 +121,7 @@ import numpy
 
 from ._phasorpy import (
     _gaussian_signal,
+    _median_filter_2d,
     _phasor_at_harmonic,
     _phasor_divide,
     _phasor_from_apparent_lifetime,
@@ -180,6 +180,8 @@ def phasor_from_signal(
         Else, harmonics must be at least one and no larger than half the
         number of `signal` samples along `axis`.
         The default is the first harmonic (fundamental frequency).
+        A minimum of `harmonic * 2 + 1` samples are required along `axis`
+        to calculate correct phasor coordinates at `harmonic`.
     sample_phase : array_like, optional
         Phase values (in radians) of `signal` samples along `axis`.
         If None (default), samples are assumed to be uniformly spaced along
@@ -285,7 +287,7 @@ def phasor_from_signal(
     if dtype.kind != 'f':
         raise TypeError(f'{dtype=} not supported')
 
-    harmonic, keepdims = parse_harmonic(harmonic, samples)
+    harmonic, keepdims = parse_harmonic(harmonic, samples // 2)
     num_harmonics = len(harmonic)
 
     if sample_phase is not None:
@@ -303,7 +305,7 @@ def phasor_from_signal(
         use_fft = sample_phase is None and (
             rfft is not None
             or num_harmonics > 7
-            or num_harmonics == samples // 2
+            or num_harmonics >= samples // 2
         )
 
     if use_fft:
@@ -413,7 +415,7 @@ def phasor_to_signal(
         coordinates (most commonly, lower harmonics are present if the number
         of dimensions of `mean` is one less than `real`).
         If `'all'`, the harmonics in the first axis of phasor coordinates are
-        the lower harmonics.
+        the lower harmonics necessary to synthesize `samples`.
         Else, harmonics must be at least one and no larger than half of
         `samples`.
         The phasor coordinates of missing harmonics are zeroed
@@ -462,18 +464,15 @@ def phasor_to_signal(
     array([2.2, 2.486, 0.8566, -0.4365, 0.3938])
 
     """
+    if samples < 3:
+        raise ValueError(f'{samples=} < 3')
+
     mean = numpy.array(mean, ndmin=0, copy=True)
     real = numpy.array(real, ndmin=0, copy=True)
     imag = numpy.array(imag, ndmin=1, copy=True)
 
-    if isinstance(harmonic, (int, numbers.Integral)) and harmonic == 0:
-        # harmonics are expected in the first axes of real and imag
-        samples_ = 2 * imag.shape[0]
-    else:
-        samples_ = samples
-
     harmonic_ = harmonic
-    harmonic, has_harmonic_axis = parse_harmonic(harmonic, samples_)
+    harmonic, has_harmonic_axis = parse_harmonic(harmonic, samples // 2)
 
     if real.ndim == 1 and len(harmonic) > 1 and real.shape[0] == len(harmonic):
         # single axis contains harmonic
@@ -641,7 +640,7 @@ def lifetime_to_signal(
     if harmonic is None:
         harmonic = 'all'
     all_hamonics = harmonic == 'all'
-    harmonic, _ = parse_harmonic(harmonic, samples)
+    harmonic, _ = parse_harmonic(harmonic, samples // 2)
 
     if samples < 16:
         raise ValueError(f'{samples=} < 16')
@@ -962,12 +961,13 @@ def phasor_calibrate(
     frequency: ArrayLike,
     lifetime: ArrayLike,
     *,
+    harmonic: int | Sequence[int] | Literal['all'] | str | None = None,
+    skip_axis: int | Sequence[int] | None = None,
     fraction: ArrayLike | None = None,
     preexponential: bool = False,
     unit_conversion: float = 1e-3,
     reverse: bool = False,
     method: Literal['mean', 'median'] = 'mean',
-    skip_axis: int | Sequence[int] | None = None,
 ) -> tuple[NDArray[Any], NDArray[Any]]:
     """
     Return calibrated/referenced phasor coordinates.
@@ -992,10 +992,22 @@ def phasor_calibrate(
         Must be measured with the same instrument setting as the phasor
         coordinates to be calibrated.
     frequency : array_like
-        Laser pulse or modulation frequency in MHz.
-        A scalar or one-dimensional sequence.
+        Fundamental laser pulse or modulation frequency in MHz.
     lifetime : array_like
-        Lifetime components in ns. Must be scalar or one dimensional.
+        Lifetime components in ns. Must be scalar or one-dimensional.
+    harmonic : int, sequence of int, or 'all', default: 1
+        Harmonics included in `real` and `imag`.
+        If an integer, the harmonics at which `real` and `imag` were acquired
+        or calculated.
+        If a sequence, the harmonics included in the first axis of `real` and
+        `imag`.
+        If `'all'`, the first axis of `real` and `imag` contains lower
+        harmonics.
+        The default is the first harmonic (fundamental frequency).
+    skip_axis : int or sequence of int, optional
+        Axes to be excluded during center calculation. If None, all
+        axes are considered, except for the first axis if multiple harmonics
+        are specified.
     fraction : array_like, optional
         Fractional intensities or pre-exponential amplitudes of the lifetime
         components. Fractions are normalized to sum to 1.
@@ -1015,9 +1027,6 @@ def phasor_calibrate(
 
         - ``'mean'``: Arithmetic mean of phasor coordinates.
         - ``'median'``: Spatial median of phasor coordinates.
-    skip_axis : int or sequence of int, optional
-        Axes to be excluded during center calculation. If None, all
-        axes are considered.
 
     Returns
     -------
@@ -1031,6 +1040,7 @@ 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`.
 
     See Also
     --------
@@ -1113,6 +1123,22 @@ def phasor_calibrate(
             f'reference_real.shape={ref_re.shape} '
             f'!= reference_imag.shape{ref_im.shape}'
         )
+
+    if harmonic == 'all' and re.ndim > 0:
+        harmonic, has_harmonic_axis = parse_harmonic(harmonic, re.shape[0])
+    else:
+        harmonic, has_harmonic_axis = parse_harmonic(harmonic)
+    if has_harmonic_axis and len(harmonic) != re.shape[0]:
+        raise ValueError(f'{len(harmonic)=} != real.shape[0]={re.shape[0]}')
+
+    frequency = numpy.asarray(frequency)
+    frequency = frequency * harmonic
+
+    skip_axis, axis = _parse_skip_axis(skip_axis, re.ndim)
+    if has_harmonic_axis:
+        skip_axis = (0,) + skip_axis if 0 not in skip_axis else skip_axis
+        skip_axis, axis = _parse_skip_axis(skip_axis, re.ndim)
+
     measured_re, measured_im = phasor_center(
         reference_real, reference_imag, skip_axis=skip_axis, method=method
     )
@@ -1130,7 +1156,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, re.ndim)
         if axis is not None:
             phi_zero = numpy.expand_dims(
                 phi_zero,
@@ -2648,14 +2673,17 @@ def phasor_filter(
     imag: ArrayLike,
     /,
     *,
-    method: Literal['median'] = 'median',
+    method: Literal['median', 'median_scipy'] = 'median',
     repeat: int = 1,
+    size: int = 3,
+    skip_axis: int | Sequence[int] | None = None,
+    num_threads: int | None = None,
     **kwargs: Any,
 ) -> tuple[NDArray[Any], NDArray[Any]]:
     """Return filtered phasor coordinates.
 
-    By default, a median filter is applied to the real and imaginary
-    components of phasor coordinates once with a kernel size of 3
+    By default, a median filter is applied independently to the real and
+    imaginary components of phasor coordinates once with a kernel size of 3
     multiplied by the number of dimensions of the input arrays.
 
     Parameters
@@ -2668,9 +2696,21 @@ def phasor_filter(
         Method used for filtering:
 
         - ``'median'``: Spatial median of phasor coordinates.
+        - ``'median_scipy'``: Spatial median of phasor coordinates
+          based on :py:func:`scipy.ndimage.median_filter`.
 
     repeat : int, optional
         Number of times to apply filter. The default is 1.
+    size : int, optional
+        Size of filter kernel. The default is 3.
+    skip_axis : int or sequence of int, optional
+        Axis or axes to skip filtering. By default all axes are filtered.
+    num_threads : int, optional
+        Number of OpenMP threads to use for parallelization.
+        Applies to filtering in two dimensions with the `median` method only.
+        By default, multi-threading is disabled.
+        If zero, up to half of logical CPUs are used.
+        OpenMP may not be available on all platforms.
     **kwargs
         Optional arguments passed to :py:func:`scipy.ndimage.median_filter`.
 
@@ -2685,26 +2725,33 @@ def phasor_filter(
     ------
     ValueError
         If the specified method is not supported.
+        If `repeat` is less than 0.
+        If `size` is less than 1.
         The array shapes of `real` and `imag` do not match.
-        If `repeat` is less than 1.
 
     Notes
     -----
-    For now, only the median filter method is implemented.
     Additional filtering methods may be added in the future.
 
-    The implementation of the median filter method is based on
+    The `median` method ignores `NaN` values. If the kernel contains an even
+    number of elements, the median is the average of the two middle elements.
+
+    The implementation of the `median_scipy` method is based on
     :py:func:`scipy.ndimage.median_filter`,
     which has undefined behavior if the input arrays contain `NaN` values.
     See `issue #87 <https://github.com/phasorpy/phasorpy/issues/87>`_.
 
+    When filtering in more than two dimensions, the `median` method is
+    slower than the `median_scipy` method. When filtering in two
+    dimensions, both methods have similar performance.
+
     Examples
     --------
     Apply three times a median filter with a kernel size of three:
 
     >>> phasor_filter(
     ...     [[0, 0, 0], [5, 5, 5], [2, 2, 2]],
-    ...     [[3, 3, 3], [6, 6, 6], [4, 4, 4]],
+    ...     [[3, 3, 3], [6, math.nan, 6], [4, 4, 4]],
     ...     size=3,
     ...     repeat=3,
     ... )
@@ -2712,25 +2759,42 @@ def phasor_filter(
             [2, 2, 2],
             [2, 2, 2]]),
     array([[3, 3, 3],
-            [4, 4, 4],
+            [4, nan, 4],
             [4, 4, 4]]))
 
     """
-    methods = {'median': _median_filter}
+    methods: dict[str, Callable[..., Any]] = {
+        'median': _median_filter,
+        'median_scipy': _median_filter_scipy,
+    }
     if method not in methods:
         raise ValueError(
-            f"Method not supported, supported methods are: "
+            f'Method not supported, supported methods are: '
             f"{', '.join(methods)}"
         )
+    if repeat == 0 or size == 1:
+        return numpy.asarray(real), numpy.asarray(imag)
+    if repeat < 0:
+        raise ValueError(f'{repeat=} < 0')
+    if size < 1:
+        raise ValueError(f'{size=} < 1')
+
     real = numpy.asarray(real)
     imag = numpy.asarray(imag)
 
     if real.shape != imag.shape:
         raise ValueError(f'{real.shape=} != {imag.shape=}')
-    if repeat < 1:
-        raise ValueError(f'{repeat=} < 1')
 
-    return methods[method](real, imag, repeat, **kwargs)
+    _, axes = _parse_skip_axis(skip_axis, real.ndim)
+
+    if 'axes' in kwargs and method == 'median_scipy':
+        axes = kwargs.pop('axes')
+    if method == 'median':
+        kwargs['num_threads'] = num_threads
+
+    return methods[method](  # type: ignore[no-any-return]
+        real, imag, axes, repeat=repeat, size=size, **kwargs
+    )
 
 
 def phasor_threshold(
@@ -2973,7 +3037,7 @@ def phasor_center(
     }
     if method not in methods:
         raise ValueError(
-            f"Method not supported, supported methods are: "
+            f'Method not supported, supported methods are: '
             f"{', '.join(methods)}"
         )
     real = numpy.asarray(real)
@@ -3024,18 +3088,18 @@ def _median(
     Parameters
     ----------
     real : ndarray
-        Real components of the phasor coordinates.
+        Real components of phasor coordinates.
     imag : ndarray
-        Imaginary components of the phasor coordinates.
+        Imaginary components of phasor coordinates.
     **kwargs
         Optional arguments passed to :py:func:`numpy.nanmedian`.
 
     Returns
     -------
     real_center : ndarray
-        Spatial median center for real coordinates.
+        Spatial median center of real coordinates.
     imag_center : ndarray
-        Spatial median center for imaginary coordinates.
+        Spatial median center of imaginary coordinates.
 
     Examples
     --------
@@ -3047,42 +3111,154 @@ def _median(
 
 
 def _median_filter(
-    real: ArrayLike,
-    imag: ArrayLike,
+    real: NDArray[Any],
+    imag: NDArray[Any],
+    axes: Sequence[int],
+    /,
+    *,
+    repeat: int = 1,
+    size: int = 3,
+    num_threads: int | None = None,
+) -> tuple[NDArray[Any], NDArray[Any]]:
+    """Return median-filtered phasor coordinates, ignoring NaN values.
+
+    Parameters
+    ----------
+    real : ndarray
+        Real components of phasor coordinates.
+    imag : ndarray
+        Imaginary components of phasor coordinates.
+    axes : sequence of int
+        Axes along which to apply median filter.
+    repeat : int, optional
+        Number of times to apply filter. The default is 1.
+    size : int, optional
+        Size of median filter kernel. The default is 3.
+    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
+    -------
+    real : ndarray
+        Median-filtered real component of phasor coordinates.
+    imag : ndarray
+        Median-filtered imaginary component of phasor coordinates.
+
+    """
+    real = numpy.asarray(real)
+    if real.dtype == numpy.float32:
+        real = real.copy()
+    else:
+        real = real.astype(float)
+
+    imag = numpy.asarray(imag)
+    if imag.dtype == numpy.float32:
+        imag = imag.copy()
+    else:
+        imag = imag.astype(float)
+
+    if len(axes) != 2:
+        # n-dimensional median filter using numpy
+        from numpy.lib.stride_tricks import sliding_window_view
+
+        kernel_shape = tuple(
+            size if i in axes else 1 for i in range(real.ndim)
+        )
+        pad_width = [
+            (s // 2, s // 2) if s > 1 else (0, 0) for s in kernel_shape
+        ]
+        axis = tuple(range(-real.ndim, 0))
+
+        nan_mask = numpy.isnan(real)
+        for _ in range(repeat):
+            real = numpy.pad(real, pad_width, mode='edge')
+            real = sliding_window_view(real, kernel_shape)
+            real = numpy.nanmedian(real, axis=axis)
+            real = numpy.where(nan_mask, numpy.nan, real)
+
+        nan_mask = numpy.isnan(imag)
+        for _ in range(repeat):
+            imag = numpy.pad(imag, pad_width, mode='edge')
+            imag = sliding_window_view(imag, kernel_shape)
+            imag = numpy.nanmedian(imag, axis=axis)
+            imag = numpy.where(nan_mask, numpy.nan, imag)
+
+        return real, imag
+
+    # 2-dimensional median filter using optimized Cython implementation
+    num_threads = number_threads(num_threads)
+
+    filtered_slice = numpy.empty(
+        tuple(real.shape[axis] for axis in axes), dtype=real.dtype
+    )
+
+    for index in numpy.ndindex(
+        *[real.shape[ax] for ax in range(real.ndim) if ax not in axes]
+    ):
+        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)
+
+        _median_filter_2d(
+            real[full_index], filtered_slice, size, repeat, num_threads
+        )
+
+        _median_filter_2d(
+            imag[full_index], filtered_slice, size, repeat, num_threads
+        )
+
+    return real, imag
+
+
+def _median_filter_scipy(
+    real: NDArray[Any],
+    imag: NDArray[Any],
+    axes: Sequence[int],
+    /,
+    *,
     repeat: int = 1,
-    size: int | tuple[int] | None = 3,
+    size: int = 3,
     **kwargs: Any,
 ) -> tuple[NDArray[Any], NDArray[Any]]:
-    """Return the phasor coordinates after applying a median filter.
+    """Return median-filtered phasor coordinates.
 
     Convenience wrapper around :py:func:`scipy.ndimage.median_filter`.
 
     Parameters
     ----------
     real : ndarray
-        Real components of the phasor coordinates.
+        Real components of phasor coordinates.
     imag : ndarray
-        Imaginary components of the phasor coordinates.
+        Imaginary components of phasor coordinates.
+    axes : sequence of int
+        Axes along which to apply median filter.
     repeat : int, optional
         Number of times to apply filter. The default is 1.
-    size : int or tuple of int, optional
-        The size of the median filter kernel. Default is 3.
+    size : int, optional
+        Size of median filter kernel. The default is 3.
     **kwargs
         Optional arguments passed to :py:func:`scipy.ndimage.median_filter`.
 
     Returns
     -------
     real : ndarray
-        Filtered real component of phasor coordinates.
+        Median-filtered real component of phasor coordinates.
     imag : ndarray
-        Filtered imaginary component of phasor coordinates.
+        Median-filtered imaginary component of phasor coordinates.
 
     """
     from scipy.ndimage import median_filter
 
+    real = numpy.asarray(real)
+    imag = numpy.asarray(imag)
+
     for _ in range(repeat):
-        real = median_filter(real, size=size, **kwargs)
-        imag = median_filter(imag, size=size, **kwargs)
+        real = median_filter(real, size=size, axes=axes, **kwargs)
+        imag = median_filter(imag, size=size, axes=axes, **kwargs)
 
     return numpy.asarray(real), numpy.asarray(imag)
 
@@ -3129,7 +3305,7 @@ def _parse_skip_axis(
     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=}")
+        raise IndexError(f'skip_axis={skip_axis} out of range for {ndim=}')
     skip_axis = tuple(sorted(int(i % ndim) for i in skip_axis))
     other_axis = tuple(i for i in range(ndim) if i not in skip_axis)
     return skip_axis, other_axis