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

phasorpy/__init__.py

@@ -2,9 +2,8 @@
 
 from __future__ import annotations
 
-__all__ = ['__version__', 'versions']
+__all__ = ['__version__']
 
-from .version import __version__, versions
 
-__version__ = __version__  # pylint: disable=self-assigning-variable
+__version__ = '0.6'
 """PhasorPy version string."""

phasorpy/_phasorpy.pyx

@@ -50,6 +50,12 @@ ctypedef fused uint_t:
     uint32_t
     uint64_t
 
+ctypedef fused int_t:
+    int8_t
+    int16_t
+    int32_t
+    int64_t
+
 ctypedef fused signal_t:
     uint8_t
     uint16_t
@@ -767,6 +773,33 @@ cdef (float_t, float_t) _phasor_from_apparent_lifetime(
     return <float_t> (mod * cos(phi)), <float_t> (mod * sin(phi))
 
 
+@cython.ufunc
+cdef float_t _phasor_to_normal_lifetime(
+    float_t real,
+    float_t imag,
+    float_t omega,
+) noexcept nogil:
+    """Return normal lifetimes from phasor coordinates."""
+    cdef:
+        double taunorm = INFINITY
+        double t
+
+    if isnan(real) or isnan(imag):
+        return <float_t> NAN
+
+    omega *= omega
+    if omega > 0.0:
+        t = 0.5 * (1.0 + cos(atan2(imag, real - 0.5)))
+        if t <= 0.0:
+            taunorm = INFINITY
+        elif t > 1.0:
+            taunorm = NAN
+        else:
+            taunorm = sqrt((1.0 - t) / (omega * t))
+
+    return <float_t> taunorm
+
+
 @cython.ufunc
 cdef (float_t, float_t) _phasor_from_single_lifetime(
     float_t lifetime,
@@ -1204,6 +1237,44 @@ cdef unsigned char _is_inside_stadium(
 _is_near_segment = _is_inside_stadium
 
 
+@cython.ufunc
+cdef unsigned char _is_inside_semicircle(
+    float_t x,  # point
+    float_t y,
+    float_t r,  # distance
+) noexcept nogil:
+    """Return whether point is inside universal semicircle."""
+    if r < 0.0 or isnan(x) or isnan(y):
+        return False
+    if y < -r:
+        return False
+    if y <= 0.0:
+        if x >= 0.0 and x <= 1.0:
+            return True
+        # near endpoints?
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return x * x + y * y <= r * r
+    return hypot(x - 0.5, y) <= r + 0.5
+
+
+@cython.ufunc
+cdef unsigned char _is_near_semicircle(
+    float_t x,  # point
+    float_t y,
+    float_t r,  # distance
+) noexcept nogil:
+    """Return whether point is near universal semicircle."""
+    if r < 0.0 or isnan(x) or isnan(y):
+        return False
+    if y < 0.0:
+        # near endpoints?
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return x * x + y * y <= r * r
+    return fabs(hypot(x - 0.5, y) - 0.5) <= r
+
+
 @cython.ufunc
 cdef unsigned char _is_near_line(
     float_t x,  # point
@@ -1470,6 +1541,22 @@ cdef float_t _distance_from_line(
     return <float_t> hypot(x, y)
 
 
+@cython.ufunc
+cdef float_t _distance_from_semicircle(
+    float_t x,  # point
+    float_t y,
+) noexcept nogil:
+    """Return distance from universal semicircle."""
+    if isnan(x) or isnan(y):
+        return NAN
+    if y < 0.0:
+        # distance to endpoints
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return <float_t> hypot(x, y)
+    return <float_t> fabs(hypot(x - 0.5, y) - 0.5)
+
+
 @cython.ufunc
 cdef (float_t, float_t, float_t) _segment_direction_and_length(
     float_t x0,  # segment start
@@ -1495,7 +1582,7 @@ cdef (float_t, float_t, float_t) _segment_direction_and_length(
 
 
 @cython.ufunc
-cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
+cdef (float_t, float_t, float_t, float_t) _intersect_circle_circle(
     float_t x0,  # circle 0
     float_t y0,
     float_t r0,
@@ -1541,7 +1628,7 @@ cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
 
 
 @cython.ufunc
-cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
+cdef (float_t, float_t, float_t, float_t) _intersect_circle_line(
     float_t x,  # circle
     float_t y,
     float_t r,
@@ -1583,10 +1670,106 @@ cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
     )
 
 
+@cython.ufunc
+cdef (float_t, float_t, float_t, float_t) _intersect_semicircle_line(
+    float_t x0,  # line start
+    float_t y0,
+    float_t x1,  # line end
+    float_t y1,
+) noexcept nogil:
+    """Return coordinates of intersections of line and universal semicircle."""
+    cdef:
+        double dx, dy, dr, dd, rdd
+
+    if isnan(x0) or isnan(x1) or isnan(y0) or isnan(y1):
+        return NAN, NAN, NAN, NAN
+
+    dx = x1 - x0
+    dy = y1 - y0
+    dr = dx * dx + dy * dy
+    dd = (x0 - 0.5) * y1 - (x1 - 0.5) * y0
+    rdd = 0.25 * dr - dd * dd  # discriminant
+    if rdd < 0.0 or dr <= 0.0:
+        # no intersection
+        return NAN, NAN, NAN, NAN
+    rdd = sqrt(rdd)
+    x0 = <float_t> ((dd * dy - copysign(1.0, dy) * dx * rdd) / dr + 0.5)
+    y0 = <float_t> ((-dd * dx - fabs(dy) * rdd) / dr)
+    x1 = <float_t> ((dd * dy + copysign(1.0, dy) * dx * rdd) / dr + 0.5)
+    y1 = <float_t> ((-dd * dx + fabs(dy) * rdd) / dr)
+    if y0 < 0.0:
+        x0 = NAN
+        y0 = NAN
+    if y1 < 0.0:
+        x1 = NAN
+        y1 = NAN
+    return x0, y0, x1, y1
+
+
+def _nearest_neighbor_2d(
+    int_t[::1] indices,
+    const float_t[::1] x0,
+    const float_t[::1] y0,
+    const float_t[::1] x1,
+    const float_t[::1] y1,
+    const float_t distance_max,
+    const int num_threads
+):
+    """Find nearest neighbors in 2D.
+
+    For each point in the first set of arrays (x0, y0) find the nearest point
+    in the second set of arrays (x1, y1) and store the index of the nearest
+    point in the second array in the indices array.
+    If any coordinates are NaN, or the distance to the nearest point
+    is larger than distance_max, the index is set to -1.
+
+    """
+    cdef:
+        ssize_t i, j, index
+        float_t x, y, dmin
+        float_t distance_max_squared = distance_max * distance_max
+
+    if (
+        indices.shape[0] != x0.shape[0]
+        or x0.shape[0] != y0.shape[0]
+        or x1.shape[0] != y1.shape[0]
+    ):
+        raise ValueError('input array size mismatch')
+
+    with nogil, parallel(num_threads=num_threads):
+        for i in prange(x0.shape[0]):
+            x = x0[i]
+            y = y0[i]
+            if isnan(x) or isnan(y):
+                indices[i] = -1
+                continue
+            index = -1
+            dmin = INFINITY
+            for j in range(x1.shape[0]):
+                x = x0[i] - x1[j]
+                y = y0[i] - y1[j]
+                x = x * x + y * y
+                if x < dmin:
+                    dmin = x
+                    index = j
+            indices[i] = -1 if dmin > distance_max_squared else <int_t> index
+
+
 ###############################################################################
 # Blend ufuncs
 
 
+@cython.ufunc
+cdef float_t _blend_and(
+    float_t a,  # base layer
+    float_t b,  # blend layer
+) noexcept nogil:
+    """Return blended layers using `and` mode."""
+    if isnan(a):
+        return NAN
+    return b
+
+
 @cython.ufunc
 cdef float_t _blend_normal(
     float_t a,  # base layer

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
 
@@ -581,8 +593,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 +603,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,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

@@ -16,7 +16,7 @@ __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
 
@@ -31,6 +31,7 @@ def phasor_cluster_gmm(
     *,
     sigma: float = 2.0,
     clusters: int = 1,
+    sort: Literal['polar', 'phasor', 'area'] | None = None,
     **kwargs: Any,
 ) -> tuple[
     tuple[float, ...],
@@ -58,6 +59,13 @@ def phasor_cluster_gmm(
     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`.
@@ -161,10 +169,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),
     )