phasorpy 0.7__cp312-cp312-macosx_11_0_arm64.whl → 0.8__cp312-cp312-macosx_11_0_arm64.whl

phasorpy/__init__.py

@@ -5,5 +5,5 @@ from __future__ import annotations
 __all__ = ['__version__']
 
 
-__version__ = '0.7'
+__version__ = '0.8'
 """PhasorPy version string."""

phasorpy/_phasorpy.pyx

@@ -6,7 +6,13 @@
 # cython: nonecheck = False
 # cython: freethreading_compatible = True
 
-"""Cython implementation of low-level functions for the PhasorPy library."""
+"""Private functions implemented in Cython for performance.
+
+.. note::
+    This module and its functions are not part of the public interface.
+    They are intended to facilitate the development of the PhasorPy library.
+
+"""
 
 cimport cython
 
@@ -1005,6 +1011,38 @@ cdef (float_t, float_t) _phasor_divide(
     )
 
 
+@cython.ufunc
+cdef (float_t, float_t, float_t) _phasor_combine(
+    float_t int0,
+    float_t real0,
+    float_t imag0,
+    float_t int1,
+    float_t real1,
+    float_t imag1,
+    float_t fraction0,
+    float_t fraction1,
+) noexcept nogil:
+    """Return linear combination of two phasor coordinates."""
+    cdef:
+        float_t intensity
+
+    fraction1 += fraction0
+    if fraction1 == 0.0:
+        return <float_t> 0.0, <float_t> NAN, <float_t> NAN
+    fraction0 /= fraction1
+
+    int0 *= fraction0
+    int1 *= <float_t> 1.0 - fraction0
+    intensity = int0 + int1
+
+    if intensity == 0.0:
+        return <float_t> 0.0, <float_t> NAN, <float_t> NAN
+
+    int0 /= intensity
+    int1 /= intensity
+    return intensity, int0 * real0 + int1 * real1, int0 * imag0 + int1 * imag1
+
+
 ###############################################################################
 # Geometry ufuncs
 

phasorpy/_utils.py

@@ -1,4 +1,10 @@
-"""Private auxiliary and convenience functions."""
+"""Private auxiliary and convenience functions.
+
+.. note::
+    This module and its functions are not part of the public interface.
+    They are intended to facilitate the development of the PhasorPy library.
+
+"""
 
 from __future__ import annotations
 
@@ -667,7 +673,7 @@ def chunk_iter(
 
 
 def init_module(globs: dict[str, Any], /) -> None:
-    """Add names in module to ``__all__`` and set ``__module__`` attributes.
+    """Add names in module to ``__all__`` attribute.
 
     Parameters
     ----------
@@ -690,9 +696,11 @@ def init_module(globs: dict[str, Any], /) -> None:
         }:
             continue
         names.append(name)
-        obj = getattr(module, name)
-        if hasattr(obj, '__module__'):
-            obj.__module__ = module_name
+        # do not change __module__ attributes because that may interfere
+        # with introspection and pickling
+        # obj = getattr(module, name)
+        # if hasattr(obj, '__module__'):
+        #     obj.__module__ = module_name
     globs['__all__'] = sorted(set(names))
 
 

phasorpy/cluster.py

@@ -1,6 +1,6 @@
 """Cluster phasor coordinates.
 
-The `phasorpy.cluster` module provides functions to:
+The ``phasorpy.cluster`` module provides functions to:
 
 - fit elliptic clusters to phasor coordinates using a
   Gaussian Mixture Model (GMM):
@@ -66,7 +66,7 @@ def phasor_cluster_gmm(
         - 'area': Sort by inverse area of ellipse (-major * minor).
 
     **kwargs
-        Additional keyword arguments passed to
+        Optional arguments passed to
         :py:class:`sklearn.mixture.GaussianMixture`.
 
         Common options include:

phasorpy/component.py

@@ -1,4 +1,4 @@
-"""Component analysis of phasor coordinates.
+"""Analyze components in phasor coordinates.
 
 The ``phasorpy.component`` module provides functions to:
 
@@ -53,7 +53,7 @@ from ._phasorpy import (
     _segment_direction_and_length,
 )
 from ._utils import sort_coordinates
-from .phasor import phasor_threshold
+from .filter import phasor_threshold
 from .utils import number_threads
 
 
@@ -95,6 +95,10 @@ def phasor_from_component(
     imag : ndarray
         Imaginary component of phasor coordinates.
 
+    See Also
+    --------
+    phasorpy.phasor.phasor_combine
+
     Examples
     --------
     Calculate phasor coordinates from two components and their fractional
@@ -110,7 +114,7 @@ def phasor_from_component(
     if dtype.char not in {'f', 'd'}:
         raise ValueError(f'{dtype=} is not a floating point type')
 
-    fraction = numpy.array(fraction, dtype=dtype, copy=True)
+    fraction = numpy.asarray(fraction, dtype=dtype, copy=True)
     if fraction.ndim < 1:
         raise ValueError(f'{fraction.ndim=} < 1')
     if fraction.shape[axis] < 2:
@@ -362,7 +366,7 @@ def phasor_component_graphical(
 
     dtype = numpy.min_scalar_type(real.size)
     counts = numpy.empty(
-        (1 if num_components == 2 else 3, fractions.size), dtype
+        (1 if num_components == 2 else 3, fractions.size), dtype=dtype
     )
 
     c = 0
@@ -438,8 +442,8 @@ def phasor_component_fit(
     component_imag : array_like
         Imaginary coordinates of components.
         Must be one or two-dimensional with harmonics in the first dimension.
-    **kwargs : optional
-        Additional arguments passed to :py:func:`scipy.linalg.lstsq()`.
+    **kwargs
+        Optional arguments passed to :py:func:`scipy.linalg.lstsq`.
 
     Returns
     -------

phasorpy/datasets.py

@@ -600,7 +600,7 @@ def fetch(
     return_scalar : bool, optional
         If true (default), return single path as string, else tuple of string.
     **kwargs
-        Additional arguments passed to ``pooch.fetch()``.
+        Optional arguments passed to :py:func:`pooch.fetch`.
         For example, ``progressbar=True``.
 
     Returns

phasorpy/experimental.py

@@ -11,26 +11,18 @@ from __future__ import annotations
 __all__ = [
     'anscombe_transform',
     'anscombe_transform_inverse',
-    'spectral_vector_denoise',
 ]
 
-import math
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ._typing import Any, NDArray, ArrayLike, DTypeLike, Literal, Sequence
-
-import numpy
+    from ._typing import Any, NDArray, ArrayLike
 
 from ._phasorpy import (
     _anscombe,
     _anscombe_inverse,
     _anscombe_inverse_approx,
-    _phasor_from_signal_vector,
-    _signal_denoise_vector,
 )
-from ._utils import parse_harmonic
-from .utils import number_threads
 
 
 def anscombe_transform(
@@ -154,157 +146,3 @@ def anscombe_transform_inverse(
             data, **kwargs
         )
     return _anscombe_inverse(data, **kwargs)  # type: ignore[no-any-return]
-
-
-def spectral_vector_denoise(
-    signal: ArrayLike,
-    /,
-    spectral_vector: ArrayLike | None = None,
-    *,
-    axis: int = -1,
-    harmonic: int | Sequence[int] | Literal['all'] | str | None = None,
-    sigma: float = 0.05,
-    vmin: float | None = None,
-    dtype: DTypeLike | None = None,
-    num_threads: int | None = None,
-) -> NDArray[Any]:
-    """Return spectral-vector-denoised signal.
-
-    The spectral vector denoising algorithm is based on a Gaussian weighted
-    average calculation, with weights obtained in n-dimensional Chebyshev or
-    Fourier space [4]_.
-
-    Parameters
-    ----------
-    signal : array_like
-        Hyperspectral data to be denoised.
-        A minimum of three samples are required along `axis`.
-        The samples must be uniformly spaced.
-    spectral_vector : array_like, optional
-        Spectral vector.
-        For example, phasor coordinates, PCA projected phasor coordinates,
-        or Chebyshev coefficients.
-        Must be of the same shape as `signal` with `axis` removed and an axis
-        containing spectral space appended.
-        If None (default), phasor coordinates are calculated at specified
-        `harmonic`.
-    axis : int, optional, default: -1
-        Axis over which `spectral_vector` is computed if not provided.
-        The default is the last axis (-1).
-    harmonic : int, sequence of int, or 'all', optional
-        Harmonics to include in calculating `spectral_vector`.
-        If `'all'`, include all harmonics for `signal` samples along `axis`.
-        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`.
-    sigma : float, default: 0.05
-        Width of Gaussian filter in spectral vector space.
-        Weighted averages are calculated using the spectra of signal items
-        within a spectral vector Euclidean distance of `3 * sigma` and
-        intensity above `vmin`.
-    vmin : float, optional
-        Signal intensity along `axis` below which spectra are excluded from
-        denoising.
-    dtype : dtype_like, optional
-        Data type of output arrays. Either float32 or float64.
-        The default is float64 unless the `signal` is float32.
-    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
-    -------
-    ndarray
-        Denoised signal of `dtype`.
-        Spectra with integrated intensity below `vmin` are unchanged.
-
-    References
-    ----------
-    .. [4] Harman RC, Lang RT, Kercher EM, Leven P, and Spring BQ.
-       `Denoising multiplexed microscopy images in n-dimensional spectral space
-       <https://doi.org/10.1364/BOE.463979>`_.
-       *Biomed Opt Express*, 13(8): 4298-4309 (2022)
-
-    Examples
-    --------
-    Denoise a hyperspectral image with a Gaussian filter width of 0.1 in
-    spectral vector space using first and second harmonic:
-
-    >>> signal = numpy.random.randint(0, 255, (8, 16, 16))
-    >>> spectral_vector_denoise(signal, axis=0, sigma=0.1, harmonic=[1, 2])
-    array([[[...]]])
-
-    """
-    num_threads = number_threads(num_threads)
-
-    signal = numpy.asarray(signal)
-    if axis == -1 or axis == signal.ndim - 1:
-        axis = -1
-    else:
-        signal = numpy.moveaxis(signal, axis, -1)
-    shape = signal.shape
-    samples = shape[-1]
-
-    if harmonic is None:
-        harmonic = 1
-    harmonic, _ = parse_harmonic(harmonic, samples // 2)
-    num_harmonics = len(harmonic)
-
-    if vmin is None or vmin < 0.0:
-        vmin = 0.0
-
-    sincos = numpy.empty((num_harmonics, samples, 2))
-    for i, h in enumerate(harmonic):
-        phase = numpy.linspace(
-            0,
-            h * math.pi * 2.0,
-            samples,
-            endpoint=False,
-            dtype=numpy.float64,
-        )
-        sincos[i, :, 0] = numpy.cos(phase)
-        sincos[i, :, 1] = numpy.sin(phase)
-
-    signal = numpy.ascontiguousarray(signal).reshape(-1, samples)
-    size = signal.shape[0]
-
-    if dtype is None:
-        if signal.dtype.char == 'f':
-            dtype = signal.dtype
-        else:
-            dtype = numpy.float64
-    dtype = numpy.dtype(dtype)
-    if dtype.char not in {'d', 'f'}:
-        raise ValueError('dtype is not floating point')
-
-    if spectral_vector is None:
-        spectral_vector = numpy.zeros((size, num_harmonics * 2), dtype=dtype)
-        _phasor_from_signal_vector(
-            spectral_vector, signal, sincos, num_threads
-        )
-    else:
-        spectral_vector = numpy.ascontiguousarray(spectral_vector, dtype=dtype)
-        if spectral_vector.shape[:-1] != shape[:-1]:
-            raise ValueError('signal and spectral_vector shape mismatch')
-        spectral_vector = spectral_vector.reshape(
-            -1, spectral_vector.shape[-1]
-        )
-
-    if dtype == signal.dtype:
-        denoised = signal.copy()
-    else:
-        denoised = numpy.zeros(signal.shape, dtype=dtype)
-        denoised[:] = signal
-    integrated = numpy.zeros(size, dtype=dtype)
-    _signal_denoise_vector(
-        denoised, integrated, signal, spectral_vector, sigma, vmin, num_threads
-    )
-
-    denoised = denoised.reshape(shape)  # type: ignore[assignment]
-    if axis != -1:
-        denoised = numpy.moveaxis(denoised, -1, axis)
-    return denoised