phasorpy 0.4__cp313-cp313-win_amd64.whl → 0.6__cp313-cp313-win_amd64.whl

phasorpy/_utils.py

@@ -2,26 +2,41 @@
 
 from __future__ import annotations
 
-__all__: list[str] = [
+__all__ = [
     'chunk_iter',
     'dilate_coordinates',
+    'init_module',
     'kwargs_notnone',
     'parse_harmonic',
     'parse_kwargs',
     'parse_signal_axis',
+    'parse_skip_axis',
     'phasor_from_polar_scalar',
     'phasor_to_polar_scalar',
     'scale_matrix',
     'sort_coordinates',
+    'squeeze_dims',
     'update_kwargs',
+    'xarray_metadata',
 ]
 
 import math
 import numbers
+import os
+import sys
+from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ._typing import Any, Sequence, ArrayLike, Literal, NDArray, Iterator
+    from ._typing import (
+        Any,
+        ArrayLike,
+        Literal,
+        NDArray,
+        Iterator,
+        Container,
+        PathLike,
+    )
 
 import numpy
 
@@ -268,7 +283,7 @@ def parse_signal_axis(
     -------
     axis : int
         Axis over which phasor coordinates are computed.
-    axis_label: str
+    axis_label : str
         Axis label from `signal.dims` if any.
 
     Raises
@@ -312,6 +327,65 @@ def parse_signal_axis(
     raise ValueError(f'{axis=} not valid for {type(signal)=}')
 
 
+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 : tuple of int
+        Ordered, positive values of `skip_axis`.
+    other_axis : tuple of int
+        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
+
+
 def parse_harmonic(
     harmonic: int | Sequence[int] | Literal['all'] | str | None,
     harmonic_max: int | None = None,
@@ -343,7 +417,7 @@ def parse_harmonic(
     Raises
     ------
     IndexError
-        Any element is out of range `[1..harmonic_max]`.
+        Any element is out of range `[1, harmonic_max]`.
     ValueError
         Elements are not unique.
         Harmonic is empty.
@@ -364,7 +438,7 @@ def parse_harmonic(
         if harmonic < 1 or (
             harmonic_max is not None and harmonic > harmonic_max
         ):
-            raise IndexError(f'{harmonic=} out of range [1..{harmonic_max}]')
+            raise IndexError(f'{harmonic=} out of range [1, {harmonic_max}]')
         return [int(harmonic)], False
 
     if isinstance(harmonic, str):
@@ -376,7 +450,7 @@ def parse_harmonic(
             return list(range(1, harmonic_max + 1)), True
         raise ValueError(f'{harmonic=!r} is not a valid harmonic')
 
-    h = numpy.atleast_1d(numpy.asarray(harmonic))
+    h = numpy.atleast_1d(harmonic)
     if h.size == 0:
         raise ValueError(f'{harmonic=} is empty')
     if h.dtype.kind not in 'iu' or h.ndim != 1:
@@ -387,7 +461,7 @@ def parse_harmonic(
         raise IndexError(f'{harmonic=} element > {harmonic_max}]')
     if numpy.unique(h).size != h.size:
         raise ValueError(f'{harmonic=} elements must be unique')
-    return h.tolist(), True
+    return [int(i) for i in harmonic], True
 
 
 def chunk_iter(
@@ -517,3 +591,123 @@ def chunk_iter(
                 for i in range(ndim)
             ),
         )
+
+
+def init_module(globs: dict[str, Any], /) -> None:
+    """Add names in module to ``__all__`` and set ``__module__`` attributes.
+
+    Parameters
+    ----------
+    globs : dict
+        Module namespace to modify.
+
+    Examples
+    --------
+    >>> init_module(globals())
+
+    """
+    names = globs['__all__']
+    module_name = globs['__name__']
+    module = sys.modules[module_name]
+    for name in dir(module):
+        if name.startswith('_') or name in {
+            'annotations',
+            'init_module',
+            'utils',  # TODO: where does this come from?
+        }:
+            continue
+        names.append(name)
+        obj = getattr(module, name)
+        if hasattr(obj, '__module__'):
+            obj.__module__ = module_name
+    globs['__all__'] = sorted(set(names))
+
+
+def xarray_metadata(
+    dims: Sequence[str] | None,
+    shape: tuple[int, ...],
+    /,
+    name: str | PathLike[Any] | None = None,
+    attrs: dict[str, Any] | None = None,
+    **coords: Any,
+) -> dict[str, Any]:
+    """Return xarray-style dims, coords, and attrs in a dict.
+
+    >>> xarray_metadata('SYX', (3, 2, 1), S=['0', '1', '2'])
+    {'dims': ('S', 'Y', 'X'), 'coords': {'S': ['0', '1', '2']}, 'attrs': {}}
+
+    """
+    assert dims is not None
+    dims = tuple(dims)
+    if len(dims) != len(shape):
+        raise ValueError(
+            f'dims do not match shape {len(dims)} != {len(shape)}'
+        )
+    coords = {dim: coords[dim] for dim in dims if dim in coords}
+    if attrs is None:
+        attrs = {}
+    metadata = {'dims': dims, 'coords': coords, 'attrs': attrs}
+    if name:
+        metadata['name'] = os.path.basename(name)
+    return metadata
+
+
+def squeeze_dims(
+    shape: Sequence[int],
+    dims: Sequence[str],
+    /,
+    skip: Container[str] = 'XY',
+) -> tuple[tuple[int, ...], tuple[str, ...], tuple[bool, ...]]:
+    """Return shape and axes with length-1 dimensions removed.
+
+    Remove unused dimensions unless their axes are listed in the `skip`
+    parameter.
+
+    Adapted from the tifffile library.
+
+    Parameters
+    ----------
+    shape : tuple of ints
+        Sequence of dimension sizes.
+    dims : sequence of str
+        Character codes for dimensions in `shape`.
+    skip : container of str, optional
+        Character codes for dimensions whose length-1 dimensions are
+        not removed. The default is 'XY'.
+
+    Returns
+    -------
+    shape : tuple of ints
+        Sequence of dimension sizes with length-1 dimensions removed.
+    dims : tuple of str
+        Character codes for dimensions in output `shape`.
+    squeezed : str
+        Dimensions were kept (True) or removed (False).
+
+    Examples
+    --------
+    >>> squeeze_dims((5, 1, 2, 1, 1), 'TZYXC')
+    ((5, 2, 1), ('T', 'Y', 'X'), (True, False, True, True, False))
+    >>> squeeze_dims((1,), ('Q',))
+    ((1,), ('Q',), (True,))
+
+    """
+    if len(shape) != len(dims):
+        raise ValueError(f'{len(shape)=} != {len(dims)=}')
+    if not dims:
+        return tuple(shape), tuple(dims), ()
+    squeezed: list[bool] = []
+    shape_squeezed: list[int] = []
+    dims_squeezed: list[str] = []
+    for size, ax in zip(shape, dims):
+        if size > 1 or ax in skip:
+            squeezed.append(True)
+            shape_squeezed.append(size)
+            dims_squeezed.append(ax)
+        else:
+            squeezed.append(False)
+    if len(shape_squeezed) == 0:
+        squeezed[-1] = True
+        shape_squeezed.append(shape[-1])
+        dims_squeezed.append(dims[-1])
+    return tuple(shape_squeezed), tuple(dims_squeezed), tuple(squeezed)

phasorpy/cli.py

@@ -8,6 +8,8 @@ Invoke the command line application with::
 
 from __future__ import annotations
 
+__all__: list[str] = []
+
 import os
 from typing import TYPE_CHECKING
 
@@ -16,11 +18,11 @@ if TYPE_CHECKING:
 
 import click
 
-from . import version
+from . import __version__
 
 
 @click.group(help='PhasorPy package command line interface.')
-@click.version_option(version=version.__version__)
+@click.version_option(version=__version__)
 def main() -> int:
     """PhasorPy command line interface."""
     return 0
@@ -36,7 +38,9 @@ def main() -> int:
 )
 def versions(verbose: bool) -> None:
     """Versions command group."""
-    click.echo(version.versions(verbose=verbose))
+    from .utils import versions
+
+    click.echo(versions(verbose=verbose))
 
 
 @main.command(help='Fetch sample files from remote repositories.')
@@ -81,6 +85,57 @@ def fret(hide: bool) -> None:
         plot.show()
 
 
+@main.command(help='Start interactive lifetime plots.')
+@click.option(
+    '-f',
+    '--frequency',
+    type=float,
+    required=False,
+    help='Laser/modulation frequency in MHz.',
+)
+@click.option(
+    '-l',
+    '--lifetime',
+    default=(4.0, 1.0),
+    type=float,
+    multiple=True,
+    required=False,
+    help='Lifetime in ns.',
+)
+@click.option(
+    '-a',
+    '--fraction',
+    type=float,
+    multiple=True,
+    required=False,
+    help='Fractional intensity of lifetime.',
+)
+@click.option(
+    '--hide',
+    default=False,
+    is_flag=True,
+    type=click.BOOL,
+    help='Do not show interactive plot.',
+)
+def lifetime(
+    frequency: float | None,
+    lifetime: tuple[float, ...],
+    fraction: tuple[float, ...],
+    hide: bool,
+) -> None:
+    """Lifetime command group."""
+    from .plot import LifetimePlots
+
+    plot = LifetimePlots(
+        frequency,
+        lifetime,
+        fraction if len(fraction) > 0 else None,
+        interactive=True,
+    )
+    if not hide:
+        plot.show()
+
+
 if __name__ == '__main__':
     import sys
 

phasorpy/cluster.py

@@ -0,0 +1,206 @@
+"""Cluster phasor coordinates.
+
+The `phasorpy.cluster` module provides functions to:
+
+- fit elliptic clusters to phasor coordinates using
+  Gaussian Mixture Model (GMM):
+
+  - :py:func:`phasor_cluster_gmm`
+
+"""
+
+from __future__ import annotations
+
+__all__ = ['phasor_cluster_gmm']
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._typing import Any, ArrayLike, Literal
+
+import math
+
+import numpy
+from sklearn.mixture import GaussianMixture
+
+
+def phasor_cluster_gmm(
+    real: ArrayLike,
+    imag: ArrayLike,
+    /,
+    *,
+    sigma: float = 2.0,
+    clusters: int = 1,
+    sort: Literal['polar', 'phasor', 'area'] | None = None,
+    **kwargs: Any,
+) -> tuple[
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+]:
+    """Return elliptic clusters in phasor coordinates using GMM.
+
+    Fit a Gaussian Mixture Model (GMM) to the provided phasor coordinates and
+    extract the parameters of ellipses that represent each cluster according
+    to [1]_.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    sigma: float, default = 2.0
+        Scaling factor for radii of major and minor axes.
+        Defaults to 2, 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
+        Sorting method for output clusters. Defaults to 'polar'.
+
+        - 'polar': Sort by polar coordinates (phase, then modulation).
+        - 'phasor': Sort by phasor coordinates (real, then imaginary).
+        - 'area': Sort by inverse area of ellipse (-major * minor).
+
+    **kwargs
+        Additional keyword arguments passed to
+        :py:class:`sklearn.mixture.GaussianMixture`.
+
+        Common options include:
+
+        - covariance_type : {'full', 'tied', 'diag', 'spherical'}
+        - max_iter : int, maximum number of EM iterations
+        - random_state : int, for reproducible results
+
+    Returns
+    -------
+    center_real : tuple of float
+        Real component of ellipse centers.
+    center_imag : tuple of float
+        Imaginary component of ellipse centers.
+    radius_major : tuple of float
+        Major radii of ellipses.
+    radius_minor : tuple of float
+        Minor radii of ellipses.
+    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).
+
+    Examples
+    --------
+    Recover the clusters from a synthetic distribution of phasor coordinates
+    with two clusters:
+
+    >>> real1, imag1 = numpy.random.multivariate_normal(
+    ...     [0.2, 0.3], [[3e-3, 1e-3], [1e-3, 2e-3]], 100
+    ... ).T
+    >>> real2, imag2 = numpy.random.multivariate_normal(
+    ...     [0.4, 0.5], [[2e-3, -1e-3], [-1e-3, 3e-3]], 100
+    ... ).T
+    >>> real = numpy.concatenate([real1, real2])
+    >>> imag = numpy.concatenate([imag1, imag2])
+    >>> center_real, center_imag, radius_major, radius_minor, angle = (
+    ...     phasor_cluster_gmm(real, imag, clusters=2)
+    ... )
+    >>> centers_real  # doctest: +SKIP
+    (0.2, 0.4)
+
+    """
+    coords = numpy.stack((real, imag), axis=-1).reshape(-1, 2)
+
+    valid_data = ~numpy.isnan(coords).any(axis=1)
+    coords = coords[valid_data]
+
+    kwargs.pop('n_components', None)
+
+    gmm = GaussianMixture(n_components=clusters, **kwargs)
+    gmm.fit(coords)
+
+    center_real = []
+    center_imag = []
+    radius_major = []
+    radius_minor = []
+    angle = []
+
+    for i in range(clusters):
+        center_real.append(float(gmm.means_[i, 0]))
+        center_imag.append(float(gmm.means_[i, 1]))
+
+        if gmm.covariance_type == 'full':
+            cov = gmm.covariances_[i]
+        elif gmm.covariance_type == 'tied':
+            cov = gmm.covariances_
+        elif gmm.covariance_type == 'diag':
+            cov = numpy.diag(gmm.covariances_[i])
+        else:  # 'spherical'
+            cov = numpy.eye(2) * gmm.covariances_[i]
+
+        eigenvalues, eigenvectors = numpy.linalg.eigh(cov[:2, :2])
+
+        idx = eigenvalues.argsort()[::-1]
+        eigenvalues = eigenvalues[idx]
+        eigenvectors = eigenvectors[:, idx]
+
+        major_vector = eigenvectors[:, 0]
+        current_angle = math.atan2(major_vector[1], major_vector[0])
+
+        if current_angle < 0:
+            current_angle += math.pi
+
+        angle.append(float(current_angle))
+
+        radius_major.append(sigma * math.sqrt(2 * eigenvalues[0]))
+        radius_minor.append(sigma * math.sqrt(2 * eigenvalues[1]))
+
+    if clusters == 1:
+        argsort = [0]
+    else:
+        if sort is None or sort == 'polar':
+
+            def sort_key(i: int) -> Any:
+                return (
+                    math.atan2(center_imag[i], center_real[i]),
+                    math.hypot(center_real[i], center_imag[i]),
+                )
+
+        elif sort == 'phasor':
+
+            def sort_key(i: int) -> Any:
+                return center_imag[i], center_real[i]
+
+        elif sort == 'area':
+
+            def sort_key(i: int) -> Any:
+                return -radius_major[i] * radius_minor[i]
+
+        else:
+            raise ValueError(
+                f"invalid {sort=!r} != 'phasor', 'polar', or 'area'"
+            )
+
+        argsort = sorted(range(len(center_real)), key=sort_key)
+
+    return (
+        tuple(center_real[i] for i in argsort),
+        tuple(center_imag[i] for i in argsort),
+        tuple(radius_major[i] for i in argsort),
+        tuple(radius_minor[i] for i in argsort),
+        tuple(angle[i] for i in argsort),
+    )

phasorpy/color.py

@@ -19,13 +19,13 @@ def wavelength2rgb(
 ) -> tuple[float, float, float] | NDArray[Any]:
     """Return approximate sRGB color components of visible wavelength(s).
 
-    Wavelength values are clipped to 360..750, rounded, and used to index
-    the :py:attr:`SRGB_SPECTRUM` palette.
+    Wavelengths are clipped to range [360, 750] nm, rounded, and used to
+    index the :py:attr:`SRGB_SPECTRUM` palette.
 
     Parameters
     ----------
     wavelength : array_like
-        Scalar or array of wavelength(s) to convert.
+        Scalar or array of wavelengths in nm.
     dtype : data-type, optional
         Data-type of return value. The default is ``float32``.
 
@@ -33,8 +33,8 @@ def wavelength2rgb(
     -------
     ndarray or tuple
         Approximate sRGB color components of visible wavelength.
-        Floating-point types are in range 0.0 to 1.0.
-        Integer types are scaled to the dtype's maximum value.
+        Floating-point values are in range [0.0, 1.0].
+        Integer values are scaled to the dtype's maximum value.
 
     Examples
     --------
@@ -68,7 +68,7 @@ def float2int(
     /,
     dtype: DTypeLike = numpy.uint8,
 ) -> NDArray[Any]:
-    """Return normalized color components as integer type.
+    """Return normalized color components as integers.
 
     Parameters
     ----------
@@ -77,6 +77,11 @@ def float2int(
     dtype : data-type, optional
         Data type of return value. The default is ``uint8``.
 
+    Returns
+    -------
+    ndarray
+        Color components as integers scaled to dtype's range.
+
     Examples
     --------
     >>> float2int([0.0, 0.5, 1.0])
@@ -162,11 +167,11 @@ CATEGORICAL: NDArray[numpy.float32] = numpy.array([
     [0.523809, 0.888889, 0.460317],
     [0.285714, 0.0, 0.238095],
 ], dtype=numpy.float32)
-"""Categorical sRGB color palette inspired by C Glasbey.
+"""Categorical sRGB color palette inspired by C. Glasbey.
 
-The palette contains 64 maximally distinct colours.
+Contains 64 maximally distinct colours for visualization.
 
-Generated with the `glasbey <https://glasbey.readthedocs.io>`_ package::
+Generated using the `glasbey <https://glasbey.readthedocs.io>`_ package::
 
     import glasbey; numpy.array(glasbey.create_palette(64, as_hex=False))
 
@@ -568,11 +573,11 @@ SRGB_SPECTRUM: NDArray[numpy.float32] = numpy.array([
     [0.005006, 0.0, 0.0],
     [0.004664, 0.0, 0.0],
 ], dtype=numpy.float32)
-"""sRGB color components for visible light wavelengths 360-750 nm.
+"""sRGB color components for wavelengths of visible light (360-750 nm).
 
 Based on the CIE 1931 2° Standard Observer.
 
-Generated with the `colour <https://colour.readthedocs.io>`_ package::
+Generated using the `colour <https://colour.readthedocs.io>`_ package::
 
     import colour; colour.plotting.plot_visible_spectrum()