phasorpy 0.6__cp312-cp312-win_amd64.whl → 0.7__cp312-cp312-win_amd64.whl

phasorpy/cluster.py

@@ -2,7 +2,7 @@
 
 The `phasorpy.cluster` module provides functions to:
 
-- fit elliptic clusters to phasor coordinates using
+- fit elliptic clusters to phasor coordinates using a
   Gaussian Mixture Model (GMM):
 
   - :py:func:`phasor_cluster_gmm`
@@ -21,7 +21,6 @@ if TYPE_CHECKING:
 import math
 
 import numpy
-from sklearn.mixture import GaussianMixture
 
 
 def phasor_cluster_gmm(
@@ -52,14 +51,14 @@ def phasor_cluster_gmm(
         Real component of phasor coordinates.
     imag : array_like
         Imaginary component of phasor coordinates.
-    sigma: float, default = 2.0
+    sigma : float, optional
         Scaling factor for radii of major and minor axes.
-        Defaults to 2, which corresponds to the scaling of eigenvalues for a
-        95% confidence ellipse.
+        Defaults to 2.0, which corresponds to the scaling of eigenvalues for
+        a 95% confidence ellipse.
     clusters : int, optional
         Number of Gaussian distributions to fit to phasor coordinates.
         Defaults to 1.
-    sort: {'polar', 'phasor', 'area'}, optional
+    sort : {'polar', 'phasor', 'area'}, optional
         Sorting method for output clusters. Defaults to 'polar'.
 
         - 'polar': Sort by polar coordinates (phase, then modulation).
@@ -89,19 +88,12 @@ def phasor_cluster_gmm(
     angle : tuple of float
         Rotation angles of major axes in radians, within range [0, pi].
 
-    Raises
-    ------
-    ValueError
-        If the array shapes of `real` and `imag` do not match.
-        If `clusters` is not a positive integer.
-
-
     References
     ----------
     .. [1] Vallmitjana A, Torrado B, and Gratton E.
       `Phasor-based image segmentation: machine learning clustering techniques
       <https://doi.org/10.1364/BOE.422766>`_.
-      *Biomed Opt Express*, 12(6): 3410-3422 (2021).
+      *Biomed Opt Express*, 12(6): 3410-3422 (2021)
 
     Examples
     --------
@@ -119,11 +111,13 @@ def phasor_cluster_gmm(
     >>> center_real, center_imag, radius_major, radius_minor, angle = (
     ...     phasor_cluster_gmm(real, imag, clusters=2)
     ... )
-    >>> centers_real  # doctest: +SKIP
+    >>> center_real  # doctest: +SKIP
     (0.2, 0.4)
 
     """
-    coords = numpy.stack((real, imag), axis=-1).reshape(-1, 2)
+    from sklearn.mixture import GaussianMixture
+
+    coords = numpy.stack([real, imag], axis=-1).reshape(-1, 2)
 
     valid_data = ~numpy.isnan(coords).any(axis=1)
     coords = coords[valid_data]

phasorpy/color.py

@@ -1,4 +1,4 @@
-"""Color palettes and manipulation."""
+"""Color palettes and color manipulation utilities."""
 
 from __future__ import annotations
 
@@ -19,20 +19,22 @@ def wavelength2rgb(
 ) -> tuple[float, float, float] | NDArray[Any]:
     """Return approximate sRGB color components of visible wavelength(s).
 
-    Wavelengths are clipped to range [360, 750] nm, rounded, and used to
+    Wavelengths are clipped to the range [360, 750] nm, rounded, and used to
     index the :py:attr:`SRGB_SPECTRUM` palette.
 
     Parameters
     ----------
     wavelength : array_like
         Scalar or array of wavelengths in nm.
-    dtype : data-type, optional
+    dtype : dtype_like, optional
         Data-type of return value. The default is ``float32``.
 
     Returns
     -------
-    ndarray or tuple
-        Approximate sRGB color components of visible wavelength.
+    ndarray or tuple of float
+        Approximate sRGB color components of visible wavelength(s).
+        If input is scalar, return tuple of three floats.
+        If input is array, return ndarray with shape (..., 3).
         Floating-point values are in range [0.0, 1.0].
         Integer values are scaled to the dtype's maximum value.
 
@@ -74,7 +76,7 @@ def float2int(
     ----------
     rgb : array_like
         Scalar or array of normalized floating-point color components.
-    dtype : data-type, optional
+    dtype : dtype_like, optional
         Data type of return value. The default is ``uint8``.
 
     Returns
@@ -169,7 +171,7 @@ CATEGORICAL: NDArray[numpy.float32] = numpy.array([
 ], dtype=numpy.float32)
 """Categorical sRGB color palette inspired by C. Glasbey.
 
-Contains 64 maximally distinct colours for visualization.
+Contains 64 maximally distinct colors for visualization.
 
 Generated using the `glasbey <https://glasbey.readthedocs.io>`_ package::
 
@@ -575,6 +577,8 @@ SRGB_SPECTRUM: NDArray[numpy.float32] = numpy.array([
 ], dtype=numpy.float32)
 """sRGB color components for wavelengths of visible light (360-750 nm).
 
+Array of shape (391, 3) containing normalized sRGB color components
+for wavelengths from 360 to 750 nm in 1 nm increments.
 Based on the CIE 1931 2° Standard Observer.
 
 Generated using the `colour <https://colour.readthedocs.io>`_ package::

phasorpy/{components.py → component.py}

@@ -1,6 +1,6 @@
 """Component analysis of phasor coordinates.
 
-The ``phasorpy.components`` module provides functions to:
+The ``phasorpy.component`` module provides functions to:
 
 - calculate fractions of two known components by projecting onto the
   line between the components (:py:func:`phasor_component_fraction`)
@@ -14,9 +14,15 @@ The ``phasorpy.components`` module provides functions to:
 - calculate fractions of two or three known components by resolving
   graphically with histogram (:py:func:`phasor_component_graphical`)
 
+- calculate mean value coordinates of phasor coordinates with respect
+  to three or more components (:py:func:`phasor_component_mvc`)
+
 - blindly resolve fractions of multiple components by using harmonic
   information (:py:func:`phasor_component_blind`, not implemented)
 
+- calculate phasor coordinates from fractional intensities of
+  components (:py:func:`phasor_from_component`)
+
 """
 
 from __future__ import annotations
@@ -26,13 +32,15 @@ __all__ = [
     'phasor_component_fit',
     'phasor_component_fraction',
     'phasor_component_graphical',
+    'phasor_component_mvc',
+    'phasor_from_component',
 ]
 
 import numbers
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ._typing import Any, ArrayLike, NDArray
+    from ._typing import Any, ArrayLike, DTypeLike, NDArray
 
 import numpy
 
@@ -41,9 +49,88 @@ from ._phasorpy import (
     _fraction_on_segment,
     _is_inside_circle,
     _is_inside_stadium,
+    _mean_value_coordinates,
     _segment_direction_and_length,
 )
+from ._utils import sort_coordinates
 from .phasor import phasor_threshold
+from .utils import number_threads
+
+
+def phasor_from_component(
+    component_real: ArrayLike,
+    component_imag: ArrayLike,
+    fraction: ArrayLike,
+    /,
+    axis: int = 0,
+    dtype: DTypeLike | None = None,
+) -> tuple[NDArray[Any], NDArray[Any]]:
+    """Return phasor coordinates from fractional intensities of components.
+
+    Return the dot products of the fractional intensities of components
+    with the real and imaginary phasor coordinates of the components.
+
+    Multi-dimensional component arrays are currently not supported.
+
+    Parameters
+    ----------
+    component_real : array_like, shape (n,)
+        Real coordinates of components.
+        At least two components are required.
+    component_imag : array_like, shape (n,)
+        Imaginary coordinates of components.
+    fraction : array_like
+        Fractional intensities of components.
+        Fractions are normalized to sum to one along `axis`.
+    axis : int, optional, default: 0
+        Axis of components in `fraction`.
+    dtype : dtype_like, optional
+        Floating point data type used for calculation and output values.
+        Either `float32` or `float64`. The default is `float64`.
+
+    Returns
+    -------
+    real : ndarray
+        Real component of phasor coordinates.
+    imag : ndarray
+        Imaginary component of phasor coordinates.
+
+    Examples
+    --------
+    Calculate phasor coordinates from two components and their fractional
+    intensities:
+
+    >>> phasor_from_component(
+    ...     [0.6, 0.4], [0.3, 0.2], [[1.0, 0.2, 0.9], [0.0, 0.8, 0.1]]
+    ... )
+    (array([0.6, 0.44, 0.58]), array([0.3, 0.22, 0.29]))
+
+    """
+    dtype = numpy.dtype(dtype)
+    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)
+    if fraction.ndim < 1:
+        raise ValueError(f'{fraction.ndim=} < 1')
+    if fraction.shape[axis] < 2:
+        raise ValueError(f'{fraction.shape[axis]=} < 2')
+    with numpy.errstate(divide='ignore', invalid='ignore'):
+        fraction /= fraction.sum(axis=axis, keepdims=True)
+
+    component_real = numpy.asarray(component_real, dtype=dtype)
+    component_imag = numpy.asarray(component_imag, dtype=dtype)
+    if component_real.shape != component_imag.shape:
+        raise ValueError(f'{component_real.shape=} != {component_imag.shape=}')
+    if component_real.ndim != 1:
+        raise ValueError(f'{component_real.ndim=} != 1')
+    if component_real.size != fraction.shape[axis]:
+        raise ValueError(f'{component_real.size=} != {fraction.shape[axis]=}')
+
+    fraction = numpy.moveaxis(fraction, axis, -1)
+    real = numpy.dot(fraction, component_real)
+    imag = numpy.dot(fraction, component_imag)
+    return real, imag
 
 
 def phasor_component_fraction(
@@ -83,7 +170,7 @@ def phasor_component_fraction(
 
     See Also
     --------
-    :ref:`sphx_glr_tutorials_api_phasorpy_components.py`
+    :ref:`sphx_glr_tutorials_api_phasorpy_component.py`
 
     Notes
     -----
@@ -97,7 +184,7 @@ def phasor_component_fraction(
     --------
     >>> phasor_component_fraction(
     ...     [0.6, 0.5, 0.4], [0.4, 0.3, 0.2], [0.2, 0.9], [0.4, 0.3]
-    ... )  # doctest: +NUMBER
+    ... )
     array([0.44, 0.56, 0.68])
 
     """
@@ -132,7 +219,7 @@ def phasor_component_graphical(
     *,
     radius: float = 0.05,
     fractions: ArrayLike | None = None,
-) -> tuple[NDArray[Any], ...]:
+) -> NDArray[Any]:
     r"""Return fractions of two or three components from phasor coordinates.
 
     The graphical method is based on moving circular cursors along the line
@@ -162,9 +249,11 @@ def phasor_component_graphical(
 
     Returns
     -------
-    counts : tuple of ndarray
+    counts : ndarray
         Counts along each line segment connecting components.
         Ordered 0-1 (2 components) or 0-1, 0-2, 1-2 (3 components).
+        Shaped `(number fractions,)` (2 components) or
+        `(3, number fractions)` (3 components).
 
     Raises
     ------
@@ -176,7 +265,7 @@ def phasor_component_graphical(
 
     See Also
     --------
-    :ref:`sphx_glr_tutorials_api_phasorpy_components.py`
+    :ref:`sphx_glr_tutorials_api_phasorpy_component.py`
 
     Notes
     -----
@@ -202,7 +291,6 @@ def phasor_component_graphical(
 
     References
     ----------
-
     .. [1] Ranjit S, Datta R, Dvornikov A, and Gratton E.
       `Multicomponent analysis of phasor plot in a single pixel to
       calculate changes of metabolic trajectory in biological systems
@@ -215,8 +303,8 @@ def phasor_component_graphical(
 
     >>> phasor_component_graphical(
     ...     [0.6, 0.3], [0.35, 0.38], [0.2, 0.9], [0.4, 0.3], fractions=6
-    ... )  # doctest: +NUMBER
-    (array([0, 0, 1, 0, 1, 0], dtype=uint64),)
+    ... )
+    array([0, 0, 1, 0, 1, 0], dtype=uint8)
 
     Count the number of phasors between the combinations of three components:
 
@@ -226,10 +314,10 @@ def phasor_component_graphical(
     ...     [0.0, 0.2, 0.9],
     ...     [0.0, 0.4, 0.3],
     ...     fractions=6,
-    ... )  # doctest: +NUMBER +NORMALIZE_WHITESPACE
-    (array([0, 1, 1, 1, 1, 0], dtype=uint64),
-     array([0, 1, 0, 0, 0, 0], dtype=uint64),
-     array([0, 1, 2, 0, 0, 0], dtype=uint64))
+    ... )
+    array([[0, 1, 1, 1, 1, 0],
+           [0, 1, 0, 0, 0, 0],
+           [0, 1, 2, 0, 0, 0]], dtype=uint8)
 
     """
     real = numpy.asarray(real)
@@ -272,7 +360,12 @@ def phasor_component_graphical(
         if fractions.ndim != 1:
             raise ValueError('fractions is not a one-dimensional array')
 
-    counts = []
+    dtype = numpy.min_scalar_type(real.size)
+    counts = numpy.empty(
+        (1 if num_components == 2 else 3, fractions.size), dtype
+    )
+
+    c = 0
     for i in range(num_components):
         a_real = component_real[i]
         a_imag = component_imag[i]
@@ -282,8 +375,7 @@ def phasor_component_graphical(
             ab_real = a_real - b_real
             ab_imag = a_imag - b_imag
 
-            component_counts = []
-            for f in fractions:
+            for k, f in enumerate(fractions):
                 if f < 0.0 or f > 1.0:
                     raise ValueError(f'fraction {f} out of bounds [0.0, 1.0]')
                 if num_components == 2:
@@ -305,12 +397,10 @@ def phasor_component_graphical(
                         component_imag[3 - i - j],  # c_imag
                         radius,
                     )
-                fraction_counts = numpy.sum(mask, dtype=numpy.uint64)
-                component_counts.append(fraction_counts)
+                counts[c, k] = numpy.sum(mask, dtype=dtype)
+            c += 1
 
-            counts.append(numpy.asarray(component_counts))
-
-    return tuple(counts)
+    return counts[0] if num_components == 2 else counts
 
 
 def phasor_component_fit(
@@ -321,7 +411,7 @@ def phasor_component_fit(
     component_imag: ArrayLike,
     /,
     **kwargs: Any,
-) -> tuple[NDArray[Any], ...]:
+) -> NDArray[Any]:
     """Return fractions of multiple components from phasor coordinates.
 
     Component fractions are obtained from the least-squares solution of a
@@ -353,8 +443,8 @@ def phasor_component_fit(
 
     Returns
     -------
-    fractions : tuple of ndarray
-        Component fractions, one array per component.
+    fractions : ndarray
+        Component fractions.
         Fractions may not exactly add up to 1.0.
 
     Raises
@@ -369,7 +459,7 @@ def phasor_component_fit(
 
     See Also
     --------
-    :ref:`sphx_glr_tutorials_api_phasorpy_components.py`
+    :ref:`sphx_glr_tutorials_api_phasorpy_component.py`
     :ref:`sphx_glr_tutorials_applications_phasorpy_component_fit.py`
 
     Notes
@@ -392,12 +482,13 @@ def phasor_component_fit(
       imaging <https://doi.org/10.1088/2050-6120/ac9ae9>`_.
       *Methods Appl Fluoresc*, 11(1): 014001 (2022)
 
-    Example
-    -------
+    Examples
+    --------
     >>> phasor_component_fit(
     ...     [1, 1, 1], [0.6, 0.5, 0.4], [0.4, 0.3, 0.2], [0.2, 0.9], [0.4, 0.3]
-    ... )  # doctest: +NUMBER
-    (array([0.4644, 0.5356, 0.6068]), array([0.5559, 0.4441, 0.3322]))
+    ... )
+    array([[0.4644, 0.5356, 0.6068],
+           [0.5559, 0.4441, 0.3322]])
 
     """
     from scipy.linalg import lstsq
@@ -464,7 +555,9 @@ def phasor_component_fit(
     # [real coordinates (for each harmonic)] +
     # [imaginary coordinates (for each harmonic)] +
     # [ones for intensity constraint]
-    coords = numpy.ones((2 * num_harmonics + 1,) + real.shape[1:])
+    coords = numpy.ones(
+        (2 * num_harmonics + 1,) + real.shape[1:]  # type: ignore[union-attr]
+    )
     coords[:num_harmonics] = real
     coords[num_harmonics : 2 * num_harmonics] = imag
 
@@ -481,4 +574,134 @@ def phasor_component_fit(
     # restore NaN values in fractions from mean
     _blend_and(mean, fractions, out=fractions)
 
-    return tuple(fractions)
+    return numpy.asarray(fractions)
+
+
+def phasor_component_mvc(
+    real: ArrayLike,
+    imag: ArrayLike,
+    component_real: ArrayLike,
+    component_imag: ArrayLike,
+    /,
+    *,
+    dtype: DTypeLike = None,
+    num_threads: int | None = None,
+) -> NDArray[Any]:
+    """Return mean value coordinates of phasor coordinates from components.
+
+    The mean value coordinates of phasor coordinates with respect to three or
+    more components spanning an arbitrary simple polygon are computed using
+    the stable method described in [3]_.
+    For three components, mean value coordinates are equivalent to
+    barycentric coordinates.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    component_real : array_like
+        Real coordinates of at least three components.
+    component_imag : array_like
+        Imaginary coordinates of at least three components.
+    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
+    -------
+    fractions : ndarray
+        Mean value coordinates for each phasor coordinate.
+
+    Raises
+    ------
+    ValueError
+        The array shapes of `real` and `imag` do not match.
+        The array shapes of `component_real` and `component_imag` do not match.
+
+    Notes
+    -----
+    Calculation of mean value coordinates for different channels,
+    frequencies, or harmonics is not supported. Only one set of components
+    can be analyzed and is broadcast to all channels/frequencies/harmonics.
+
+    For three components, this function returns the same result as
+    :py:func:`phasor_component_fit`. For more than three components,
+    the system is underdetermined and the mean value coordinates represent
+    one of multiple solutions. However, the special properties of the mean
+    value coordinates make them particularly useful for interpolating and
+    visualizing multi-component data.
+
+    References
+    ----------
+    .. [3] Fuda C and Hormann K.
+      `A new stable method to compute mean value coordinates
+      <https://doi.org/10.1016/j.cagd.2024.102310>`_.
+      *Computer Aided Geometric Design*, 111: 102310 (2024)
+
+    Examples
+    --------
+    Calculate the barycentric coordinates of a phasor coordinate
+    in a triangle defined by three components:
+
+    >>> phasor_component_mvc(0.6, 0.3, [0.0, 1.0, 0.0], [1.0, 0.0, 0.0])
+    array([0.3, 0.6, 0.1])
+
+    The barycentric coordinates of phasor coordinates outside the polygon
+    defined by the components may be outside the range [0.0, 1.0]:
+
+    >>> phasor_component_mvc(0.6, 0.6, [0.0, 1.0, 0.0], [1.0, 0.0, 0.0])
+    array([0.6, 0.6, -0.2])
+
+    """
+    num_threads = number_threads(num_threads)
+
+    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)
+    component_real = numpy.ascontiguousarray(component_real, dtype=dtype)
+    component_imag = numpy.ascontiguousarray(component_imag, dtype=dtype)
+
+    if real.shape != imag.shape:
+        raise ValueError(f'{real.shape=} != {imag.shape=}')
+    if component_real.shape != component_imag.shape:
+        raise ValueError(f'{component_real.shape=} != {component_imag.shape=}')
+    if component_real.ndim != 1 or component_real.size < 3:
+        raise ValueError('number of components must be three or more')
+    if numpy.isnan(component_real).any() or numpy.isnan(component_imag).any():
+        raise ValueError('component coordinates must not contain NaN values')
+    if numpy.isinf(component_real).any() or numpy.isinf(component_imag).any():
+        raise ValueError(
+            'component coordinates must not contain infinite values'
+        )
+
+    # TODO:: sorting not strictly required for three components?
+    component_real, component_imag, indices = sort_coordinates(
+        component_real, component_imag
+    )
+
+    shape = real.shape
+    real = real.reshape(-1)
+    imag = imag.reshape(-1)
+    fraction = numpy.zeros((component_real.size, real.size), dtype=dtype)
+
+    _mean_value_coordinates(
+        fraction,
+        indices,
+        real,
+        imag,
+        component_real,
+        component_imag,
+        num_threads,
+    )
+
+    return numpy.asarray(fraction.reshape((-1, *shape)).squeeze())