phasorpy 0.5__cp311-cp311-win_arm64.whl → 0.7__cp311-cp311-win_arm64.whl

phasorpy/_utils.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 __all__ = [
     'chunk_iter',
     'dilate_coordinates',
+    'init_module',
     'kwargs_notnone',
     'parse_harmonic',
     'parse_kwargs',
@@ -13,18 +14,29 @@ __all__ = [
     'phasor_from_polar_scalar',
     'phasor_to_polar_scalar',
     'scale_matrix',
-    'set_module',
     '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, ArrayLike, Literal, NDArray, Iterator
+    from ._typing import (
+        Any,
+        ArrayLike,
+        Literal,
+        NDArray,
+        Iterator,
+        Container,
+        PathLike,
+    )
 
 import numpy
 
@@ -40,6 +52,23 @@ def parse_kwargs(
 
     If `_del` is true (default), existing keys are deleted from `kwargs`.
 
+    Parameters
+    ----------
+    kwargs : dict
+        Source dictionary to extract keys from.
+    *keys : str
+        Keys to extract from kwargs if present.
+    _del : bool, default: True
+        If True, remove extracted keys from kwargs.
+    **keyvalues : Any
+        Key-value pairs. If key exists in kwargs, use kwargs value,
+        otherwise use provided default value.
+
+    Returns
+    -------
+    dict
+        Dictionary containing extracted keys and values.
+
     >>> kwargs = {'one': 1, 'two': 2, 'four': 4}
     >>> kwargs2 = parse_kwargs(kwargs, 'two', 'three', four=None, five=5)
     >>> kwargs == {'one': 1}
@@ -93,19 +122,19 @@ def scale_matrix(factor: float, origin: Sequence[float]) -> NDArray[Any]:
 
     Parameters
     ----------
-    factor: float
+    factor : float
         Scale factor.
-    origin: (float, float)
+    origin : (float, float)
         Coordinates of point around which to scale.
 
     Returns
     -------
-    matrix: ndarray
+    matrix : ndarray
         A 3x3 homogeneous transformation matrix.
 
     Examples
     --------
-    >>> scale_matrix(1.1, (0.0, 0.5))
+    >>> scale_matrix(1.1, [0.0, 0.5])
     array([[1.1, 0, -0],
            [0, 1.1, -0.05],
            [0, 0, 1]])
@@ -121,7 +150,7 @@ def sort_coordinates(
     real: ArrayLike,
     imag: ArrayLike,
     /,
-    origin: tuple[float, float] | None = None,
+    origin: ArrayLike | None = None,
 ) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any]]:
     """Return cartesian coordinates sorted counterclockwise around origin.
 
@@ -129,15 +158,19 @@ def sort_coordinates(
     ----------
     real, imag : array_like
         Coordinates to be sorted.
-    origin : (float, float)
+    origin : array_like, optional
         Coordinates around which to sort by angle.
+        By default, sort around the mean of `real` and `imag`.
 
     Returns
     -------
-    real, imag : ndarray
-        Coordinates sorted by angle.
+    real : ndarray
+        Sorted real coordinates.
+    imag : ndarray
+        Sorted imaginary coordinates.
     indices : ndarray
         Indices used to reorder coordinates.
+        Use ``indices.argsort()`` to get original order.
 
     Examples
     --------
@@ -148,11 +181,15 @@ def sort_coordinates(
     x, y = numpy.atleast_1d(real, imag)
     if x.ndim != 1 or x.shape != y.shape:
         raise ValueError(f'invalid {x.shape=} or {y.shape=}')
-    if x.size < 4:
+    if x.size < 3:
         return x, y, numpy.arange(x.size)
     if origin is None:
-        origin = x.mean(), y.mean()
-    indices = numpy.argsort(numpy.arctan2(y - origin[1], x - origin[0]))
+        ox, oy = x.mean(), y.mean()
+    else:
+        origin = numpy.asarray(origin, dtype=numpy.float64)
+        ox = origin[0]
+        oy = origin[1]
+    indices = numpy.argsort(numpy.arctan2(y - oy, x - ox))
     return x[indices], y[indices], indices
 
 
@@ -173,8 +210,10 @@ def dilate_coordinates(
 
     Returns
     -------
-    real, imag : ndarray
-        Coordinates dilated by offset.
+    real : ndarray
+        Dilated real coordinates.
+    imag : ndarray
+        Dilated imaginary coordinates.
 
     Examples
     --------
@@ -213,8 +252,28 @@ def phasor_to_polar_scalar(
 ) -> tuple[float, float]:
     """Return polar from scalar phasor coordinates.
 
-    >>> phasor_to_polar_scalar(1.0, 0.0, degree=True, percent=True)
-    (0.0, 100.0)
+    Parameters
+    ----------
+    real : float
+        Real component of phasor coordinate.
+    imag : float
+        Imaginary component of phasor coordinate.
+    degree : bool, optional
+        If true, return phase in degrees instead of radians.
+    percent : bool, optional
+        If true, return modulation as percentage instead of fraction.
+
+    Returns
+    -------
+    phase : float
+        Phase angle in radians (or degrees if degree=True).
+    modulation : float
+        Modulation depth as fraction (or percentage if percent=True).
+
+    Examples
+    --------
+    >>> phasor_to_polar_scalar(0.0, 1.0, degree=True, percent=True)
+    (90.0, 100.0)
 
     """
     phi = math.atan2(imag, real)
@@ -236,6 +295,26 @@ def phasor_from_polar_scalar(
 ) -> tuple[float, float]:
     """Return phasor from scalar polar coordinates.
 
+    Parameters
+    ----------
+    phase : float
+        Phase angle in radians (or degrees if degree=True).
+    modulation : float
+        Modulation depth as fraction (or percentage if percent=True).
+    degree : bool, optional
+        If true, phase is in degrees instead of radians.
+    percent : bool, optional
+        If true, modulation is as percentage instead of fraction.
+
+    Returns
+    -------
+    real : float
+        Real component of phasor coordinate.
+    imag : float
+        Imaginary component of phasor coordinate.
+
+    Examples
+    --------
     >>> phasor_from_polar_scalar(0.0, 100.0, degree=True, percent=True)
     (1.0, 0.0)
 
@@ -261,23 +340,27 @@ def parse_signal_axis(
     Parameters
     ----------
     signal : array_like
-        Image stack.
-    axis : int or str, optional
-        Axis over which phasor coordinates are computed.
-        By default, the 'H' or 'C' axes if `signal` contains such
-        dimension names, else the last axis (-1).
+        Signal array.
+        Axis names are used if it has a `dims` attribute.
+    axis : int, str, or None, default: None
+        Axis over which to compute phasor coordinates.
+        If None, automatically selects 'H' or 'C' axis if available,
+        otherwise uses the last axis (-1).
+        If int, specifies axis index.
+        If str, specifies axis name (requires `signal.dims`).
 
     Returns
     -------
     axis : int
-        Axis over which phasor coordinates are computed.
+        Index of axis over which phasor coordinates are computed.
     axis_label : str
-        Axis label from `signal.dims` if any.
+        Label of axis from `signal.dims` if available, empty string otherwise.
 
     Raises
     ------
     ValueError
-        Axis not found in signal.dims or invalid for signal type.
+        If axis string is not found in signal.dims.
+        If axis string is provided but signal has no dims attribute.
 
     Examples
     --------
@@ -344,15 +427,17 @@ def parse_skip_axis(
 
     Raises
     ------
+    ValueError
+        If ndim is negative.
     IndexError
         If any `skip_axis` value is out of bounds of `ndim`.
 
     Examples
     --------
-    >>> parse_skip_axis((1, -2), 5)
+    >>> parse_skip_axis([1, -2], 5)
     ((1, 3), (0, 2, 4))
 
-    >>> parse_skip_axis((1, -2), 5, True)
+    >>> parse_skip_axis([1, -2], 5, True)
     ((0, 2, 4), (1, 3, 5))
 
     """
@@ -389,7 +474,7 @@ def parse_harmonic(
     harmonic : int, sequence of int, 'all', or None
         Harmonic parameter to parse.
     harmonic_max : int, optional
-        Maximum value allowed in `hamonic`. Must be one or greater.
+        Maximum value allowed in `harmonic`. Must be one or greater.
         To verify against known number of signal samples,
         pass ``samples // 2``.
         If `harmonic='all'`, a range of harmonics from one to `harmonic_max`
@@ -475,11 +560,11 @@ def chunk_iter(
     pattern : str, optional
         String to format chunk indices.
         If None, use ``_[{dims[index]}{chunk_index[index]}]`` for each axis.
-    squeeze : bool
+    squeeze : bool, optional
         If true, do not include length-1 chunked dimensions in label
         unless dimensions are part of `chunk_shape`.
         Applies only if `pattern` is None.
-    use_index : bool
+    use_index : bool, optional
         If true, use indices of chunks in `shape` instead of chunk indices to
         format pattern.
 
@@ -581,8 +666,8 @@ def chunk_iter(
         )
 
 
-def set_module(globs: dict[str, Any], /) -> None:
-    """Set ``__module__`` attribute for objects in ``__all__``.
+def init_module(globs: dict[str, Any], /) -> None:
+    """Add names in module to ``__all__`` and set ``__module__`` attributes.
 
     Parameters
     ----------
@@ -591,11 +676,111 @@ def set_module(globs: dict[str, Any], /) -> None:
 
     Examples
     --------
-    >>> set_module(globals())
+    >>> init_module(globals())
 
     """
-    name = globs['__name__']
-    for item in globs['__all__']:
-        obj = globs[item]
+    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__ = name
+            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

@@ -18,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
@@ -38,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.')
@@ -83,6 +85,75 @@ def fret(hide: bool) -> None:
         plot.show()
 
 
+@main.command(help='Start interactive lifetime plots.')
+@click.argument(
+    'number_lifetimes',
+    default=2,
+    type=click.IntRange(1, 5),
+    required=False,
+    # help='Number of preconfigured lifetimes.',
+)
+@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(
+    number_lifetimes: int,
+    frequency: float | None,
+    lifetime: tuple[float, ...],
+    fraction: tuple[float, ...],
+    hide: bool,
+) -> None:
+    """Lifetime command group."""
+    from .lifetime import phasor_semicircle, phasor_to_normal_lifetime
+    from .plot import LifetimePlots
+
+    if not lifetime:
+        if number_lifetimes == 2:
+            lifetime = (4.0, 1.0)
+        else:
+            real, imag = phasor_semicircle(number_lifetimes + 2)
+            lifetime = phasor_to_normal_lifetime(
+                real[1:-1], imag[1:-1], frequency if frequency else 80.0
+            )  # type: ignore[assignment]
+
+    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

@@ -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`
@@ -16,12 +16,11 @@ __all__ = ['phasor_cluster_gmm']
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ._typing import Any, ArrayLike
+    from ._typing import Any, ArrayLike, Literal
 
 import math
 
 import numpy
-from sklearn.mixture import GaussianMixture
 
 
 def phasor_cluster_gmm(
@@ -31,6 +30,7 @@ def phasor_cluster_gmm(
     *,
     sigma: float = 2.0,
     clusters: int = 1,
+    sort: Literal['polar', 'phasor', 'area'] | None = None,
     **kwargs: Any,
 ) -> tuple[
     tuple[float, ...],
@@ -51,13 +51,20 @@ 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
+        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`.
@@ -81,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
     --------
@@ -111,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]
@@ -161,10 +163,38 @@ def phasor_cluster_gmm(
         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),
-        tuple(center_imag),
-        tuple(radius_major),
-        tuple(radius_minor),
-        tuple(angle),
+        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

@@ -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::