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

phasorpy/_phasorpy.pyx

@@ -4,15 +4,10 @@
 # cython: wraparound = False
 # cython: cdivision = True
 # cython: nonecheck = False
+# cython: freethreading_compatible = True
 
 """Cython implementation of low-level functions for the PhasorPy library."""
 
-# TODO: replace short with unsigned char when Cython supports it
-# https://github.com/cython/cython/pull/6196#issuecomment-2209509572
-
-# TODO: use fused return types for functions returning more than two items
-# https://github.com/cython/cython/issues/6328
-
 cimport cython
 
 from cython.parallel import parallel, prange
@@ -49,6 +44,12 @@ ctypedef fused float_t:
     float
     double
 
+ctypedef fused uint_t:
+    uint8_t
+    uint16_t
+    uint32_t
+    uint64_t
+
 ctypedef fused signal_t:
     uint8_t
     uint16_t
@@ -445,7 +446,7 @@ cdef (double, double) _phasor_from_fret_donor(
     double omega,
     double donor_lifetime,
     double fret_efficiency,
-    double donor_freting,
+    double donor_fretting,
     double donor_background,
     double background_real,
     double background_imag,
@@ -465,16 +466,16 @@ cdef (double, double) _phasor_from_fret_donor(
     elif fret_efficiency > 1.0:
         fret_efficiency = 1.0
 
-    if donor_freting < 0.0:
-        donor_freting = 0.0
-    elif donor_freting > 1.0:
-        donor_freting = 1.0
+    if donor_fretting < 0.0:
+        donor_fretting = 0.0
+    elif donor_fretting > 1.0:
+        donor_fretting = 1.0
 
     if donor_background < 0.0:
         donor_background = 0.0
 
-    f_pure = 1.0 - donor_freting
-    f_quenched = (1.0 - fret_efficiency) * donor_freting
+    f_pure = 1.0 - donor_fretting
+    f_quenched = (1.0 - fret_efficiency) * donor_fretting
     sum = f_pure + f_quenched + donor_background
     if sum < 1e-9:
         # no signal in donor channel
@@ -510,7 +511,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
     double donor_lifetime,
     double acceptor_lifetime,
     double fret_efficiency,
-    double donor_freting,
+    double donor_fretting,
     double donor_bleedthrough,
     double acceptor_bleedthrough,
     double acceptor_background,
@@ -535,10 +536,10 @@ cdef (double, double) _phasor_from_fret_acceptor(
     elif fret_efficiency > 1.0:
         fret_efficiency = 1.0
 
-    if donor_freting < 0.0:
-        donor_freting = 0.0
-    elif donor_freting > 1.0:
-        donor_freting = 1.0
+    if donor_fretting < 0.0:
+        donor_fretting = 0.0
+    elif donor_fretting > 1.0:
+        donor_fretting = 1.0
 
     if donor_bleedthrough < 0.0:
         donor_bleedthrough = 0.0
@@ -569,7 +570,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
             quenched_imag,
             1.0,
             1.0 - fret_efficiency,
-            1.0 - donor_freting
+            1.0 - donor_fretting
         )
 
     # phasor of acceptor at frequency
@@ -591,8 +592,8 @@ cdef (double, double) _phasor_from_fret_acceptor(
     sensitized_imag = mod * sin(phi)
 
     # weighted average
-    f_donor = donor_bleedthrough * (1.0 - donor_freting * fret_efficiency)
-    f_acceptor = donor_freting * fret_efficiency
+    f_donor = donor_bleedthrough * (1.0 - donor_fretting * fret_efficiency)
+    f_acceptor = donor_fretting * fret_efficiency
     sum = f_donor + f_acceptor + acceptor_bleedthrough + acceptor_background
     if sum < 1e-9:
         # no signal in acceptor channel
@@ -913,7 +914,7 @@ cdef (float_t, float_t) _phasor_at_harmonic(
     int harmonic,
     int other_harmonic,
 ) noexcept nogil:
-    """Return phasor coordinates on semicircle at other harmonic."""
+    """Return phasor coordinates on universal semicircle at other harmonic."""
     if isnan(real):
         return <float_t> NAN, <float_t> NAN
 
@@ -976,7 +977,7 @@ cdef (float_t, float_t) _phasor_divide(
 
 
 @cython.ufunc
-cdef short _is_inside_range(
+cdef unsigned char _is_inside_range(
     float_t x,  # point
     float_t y,
     float_t xmin,  # x range
@@ -996,7 +997,7 @@ cdef short _is_inside_range(
 
 
 @cython.ufunc
-cdef short _is_inside_rectangle(
+cdef unsigned char _is_inside_rectangle(
     float_t x,  # point
     float_t y,
     float_t x0,  # segment start
@@ -1038,7 +1039,7 @@ cdef short _is_inside_rectangle(
 
 
 @cython.ufunc
-cdef short _is_inside_polar_rectangle(
+cdef unsigned char _is_inside_polar_rectangle(
     float_t x,  # point
     float_t y,
     float_t angle_min,  # phase, -pi to pi
@@ -1048,7 +1049,7 @@ cdef short _is_inside_polar_rectangle(
 ) noexcept nogil:
     """Return whether point is inside polar rectangle.
 
-    Angles should be in range -pi to pi, else performance is degraded.
+    Angles should be in range [-pi, pi], else performance is degraded.
 
     """
     cdef:
@@ -1077,7 +1078,7 @@ cdef short _is_inside_polar_rectangle(
 
 
 @cython.ufunc
-cdef short _is_inside_circle(
+cdef unsigned char _is_inside_circle(
     float_t x,  # point
     float_t y,
     float_t x0,  # circle center
@@ -1094,7 +1095,7 @@ cdef short _is_inside_circle(
 
 
 @cython.ufunc
-cdef short _is_inside_ellipse(
+cdef unsigned char _is_inside_ellipse(
     float_t x,  # point
     float_t y,
     float_t x0,  # ellipse center
@@ -1129,7 +1130,7 @@ cdef short _is_inside_ellipse(
 
 
 @cython.ufunc
-cdef short _is_inside_ellipse_(
+cdef unsigned char _is_inside_ellipse_(
     float_t x,  # point
     float_t y,
     float_t x0,  # ellipse center
@@ -1158,7 +1159,7 @@ cdef short _is_inside_ellipse_(
 
 
 @cython.ufunc
-cdef short _is_inside_stadium(
+cdef unsigned char _is_inside_stadium(
     float_t x,  # point
     float_t y,
     float_t x0,  # line start
@@ -1204,7 +1205,7 @@ _is_near_segment = _is_inside_stadium
 
 
 @cython.ufunc
-cdef short _is_near_line(
+cdef unsigned char _is_near_line(
     float_t x,  # point
     float_t y,
     float_t x0,  # line start
@@ -1470,7 +1471,7 @@ cdef float_t _distance_from_line(
 
 
 @cython.ufunc
-cdef (double, double, double) _segment_direction_and_length(
+cdef (float_t, float_t, float_t) _segment_direction_and_length(
     float_t x0,  # segment start
     float_t y0,
     float_t x1,  # segment end
@@ -1494,7 +1495,7 @@ cdef (double, double, double) _segment_direction_and_length(
 
 
 @cython.ufunc
-cdef (double, double, double, double) _intersection_circle_circle(
+cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
     float_t x0,  # circle 0
     float_t y0,
     float_t r0,
@@ -1532,15 +1533,15 @@ cdef (double, double, double, double) _intersection_circle_circle(
     hd = sqrt(dd) / dr
     ld = ll / dr
     return (
-        ld * dx + hd * dy + x0,
-        ld * dy - hd * dx + y0,
-        ld * dx - hd * dy + x0,
-        ld * dy + hd * dx + y0,
+        <float_t> (ld * dx + hd * dy + x0),
+        <float_t> (ld * dy - hd * dx + y0),
+        <float_t> (ld * dx - hd * dy + x0),
+        <float_t> (ld * dy + hd * dx + y0),
     )
 
 
 @cython.ufunc
-cdef (double, double, double, double) _intersection_circle_line(
+cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
     float_t x,  # circle
     float_t y,
     float_t r,
@@ -1575,10 +1576,10 @@ cdef (double, double, double, double) _intersection_circle_line(
         return NAN, NAN, NAN, NAN
     rdd = sqrt(rdd)
     return (
-        x + (dd * dy + copysign(1.0, dy) * dx * rdd) / dr,
-        y + (-dd * dx + fabs(dy) * rdd) / dr,
-        x + (dd * dy - copysign(1.0, dy) * dx * rdd) / dr,
-        y + (-dd * dx - fabs(dy) * rdd) / dr,
+        x + <float_t> ((dd * dy + copysign(1.0, dy) * dx * rdd) / dr),
+        y + <float_t> ((-dd * dx + fabs(dy) * rdd) / dr),
+        x + <float_t> ((dd * dy - copysign(1.0, dy) * dx * rdd) / dr),
+        y + <float_t> ((-dd * dx - fabs(dy) * rdd) / dr),
     )
 
 
@@ -1659,7 +1660,7 @@ cdef float_t _blend_lighten(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_open(
+cdef (float_t, float_t, float_t) _phasor_threshold_open(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1721,7 +1722,7 @@ cdef (double, double, double) _phasor_threshold_open(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_closed(
+cdef (float_t, float_t, float_t) _phasor_threshold_closed(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1783,7 +1784,7 @@ cdef (double, double, double) _phasor_threshold_closed(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_mean_open(
+cdef (float_t, float_t, float_t) _phasor_threshold_mean_open(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1803,7 +1804,7 @@ cdef (double, double, double) _phasor_threshold_mean_open(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_mean_closed(
+cdef (float_t, float_t, float_t) _phasor_threshold_mean_closed(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1823,7 +1824,7 @@ cdef (double, double, double) _phasor_threshold_mean_closed(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_nan(
+cdef (float_t, float_t, float_t) _phasor_threshold_nan(
     float_t mean,
     float_t real,
     float_t imag,
@@ -2159,3 +2160,74 @@ def _median_filter_2d(
                     image[i, j] = filtered_image[i, j]
 
         free(kernel)
+
+
+###############################################################################
+# Decoder functions
+
+
+@cython.boundscheck(True)
+def _flimlabs_signal(
+    uint_t[:, :, ::] signal,   # channel, pixel, bin
+    list data,  # list[list[list[[int, int]]]]
+    ssize_t channel = -1  # -1 == None
+):
+    """Return TCSPC histogram image from FLIM LABS JSON intensity data."""
+    cdef:
+        uint_t[::] signal_
+        list channels, pixels
+        ssize_t c, i, h, count
+
+    if channel < 0:
+        c = 0
+        for channels in data:
+            i = 0
+            for pixels in channels:
+                signal_ = signal[c, i]
+                for h, count in pixels:
+                    signal_[h] = <uint_t> count
+                i += 1
+            c += 1
+    else:
+        i = 0
+        for pixels in data[channel]:
+            signal_ = signal[0, i]
+            for h, count in pixels:
+                signal_[h] = <uint_t> count
+            i += 1
+
+
+@cython.boundscheck(True)
+def _flimlabs_mean(
+    float_t[:, ::] mean,   # channel, pixel
+    list data,  # list[list[list[[int, int]]]]
+    ssize_t channel = -1  # -1 == None
+):
+    """Return mean intensity image from FLIM LABS JSON intensity data."""
+    cdef:
+        float_t[::] mean_
+        list channels, pixels
+        ssize_t c, i, h, count
+        double sum
+
+    if channel < 0:
+        c = 0
+        for channels in data:
+            mean_ = mean[c]
+            i = 0
+            for pixels in channels:
+                sum = 0.0
+                for h, count in pixels:
+                    sum += <double> count
+                mean_[i] = <float_t> (sum / 256.0)
+                i += 1
+            c += 1
+    else:
+        i = 0
+        mean_ = mean[0]
+        for pixels in data[channel]:
+            sum = 0.0
+            for h, count in pixels:
+                sum += <double> count
+            mean_[i] = <float_t> (sum / 256.0)
+            i += 1

phasorpy/_utils.py

@@ -1,28 +1,30 @@
-"""Private auxiliary and convenience functions.
-
-"""
+"""Private auxiliary and convenience functions."""
 
 from __future__ import annotations
 
-__all__: list[str] = [
+__all__ = [
     'chunk_iter',
     'dilate_coordinates',
     'kwargs_notnone',
     'parse_harmonic',
     'parse_kwargs',
+    'parse_signal_axis',
+    'parse_skip_axis',
     'phasor_from_polar_scalar',
     'phasor_to_polar_scalar',
     'scale_matrix',
+    'set_module',
     'sort_coordinates',
     'update_kwargs',
 ]
 
 import math
 import numbers
+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
 
 import numpy
 
@@ -247,6 +249,131 @@ def phasor_from_polar_scalar(
     return real, imag
 
 
+def parse_signal_axis(
+    signal: ArrayLike,
+    /,
+    axis: int | str | None = None,
+) -> tuple[int, str]:
+    """Return axis over which phasor coordinates are computed.
+
+    The axis parameter is not validated against the signal shape.
+
+    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).
+
+    Returns
+    -------
+    axis : int
+        Axis over which phasor coordinates are computed.
+    axis_label : str
+        Axis label from `signal.dims` if any.
+
+    Raises
+    ------
+    ValueError
+        Axis not found in signal.dims or invalid for signal type.
+
+    Examples
+    --------
+    >>> parse_signal_axis([])
+    (-1, '')
+    >>> parse_signal_axis([], 1)
+    (1, '')
+    >>> class DataArray:
+    ...     dims = ('C', 'H', 'Y', 'X')
+    ...
+    >>> parse_signal_axis(DataArray())
+    (1, 'H')
+    >>> parse_signal_axis(DataArray(), 'C')
+    (0, 'C')
+    >>> parse_signal_axis(DataArray(), 1)
+    (1, 'H')
+
+    """
+    if hasattr(signal, 'dims'):
+        assert isinstance(signal.dims, tuple)
+        if axis is None:
+            for ax in 'HC':
+                if ax in signal.dims:
+                    return signal.dims.index(ax), ax
+            return -1, signal.dims[-1]
+        if isinstance(axis, int):
+            return axis, signal.dims[axis]
+        if axis in signal.dims:
+            return signal.dims.index(axis), axis
+        raise ValueError(f'{axis=} not found in {signal.dims}')
+    if axis is None:
+        return -1, ''
+    if isinstance(axis, int):
+        return 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,
@@ -259,7 +386,7 @@ def parse_harmonic(
 
     Parameters
     ----------
-    harmonic : int, list of int, 'all', or None
+    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.
@@ -278,7 +405,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.
@@ -299,7 +426,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):
@@ -311,7 +438,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:
@@ -322,14 +449,14 @@ 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(
     shape: tuple[int, ...],
     chunk_shape: tuple[int, ...],
     /,
-    axes: str | Sequence[str] | None = None,
+    dims: Sequence[str] | None = None,
     *,
     pattern: str | None = None,
     squeeze: bool = False,
@@ -343,11 +470,11 @@ def chunk_iter(
         Shape of C-order ndarray to chunk.
     chunk_shape : tuple of int
         Shape of chunks in the most significant dimensions.
-    axes : str or sequence of str, optional
+    dims : sequence of str, optional
         Labels for each axis in shape if `pattern` is None.
     pattern : str, optional
         String to format chunk indices.
-        If None, use ``_[{axes[index]}{chunk_index[index]}]`` for each axis.
+        If None, use ``_[{dims[index]}{chunk_index[index]}]`` for each axis.
     squeeze : bool
         If true, do not include length-1 chunked dimensions in label
         unless dimensions are part of `chunk_shape`.
@@ -384,11 +511,11 @@ def chunk_iter(
     ndim = len(shape)
 
     sep = '_'
-    if axes is None:
-        axes = sep * ndim
+    if dims is None:
+        dims = sep * ndim
         sep = ''
-    elif ndim != len(axes):
-        raise ValueError(f'{len(shape)=} != {len(axes)=}')
+    elif ndim != len(dims):
+        raise ValueError(f'{len(shape)=} != {len(dims)=}')
 
     if pattern is not None:
         try:
@@ -406,7 +533,7 @@ def chunk_iter(
 
     chunked_shape = []
     pattern_list = []
-    for i, (size, chunk_size, ax) in enumerate(zip(shape, chunk_shape, axes)):
+    for i, (size, chunk_size, ax) in enumerate(zip(shape, chunk_shape, dims)):
         if size <= 0:
             raise ValueError('shape must contain positive sizes')
         if chunk_size <= 0:
@@ -452,3 +579,23 @@ def chunk_iter(
                 for i in range(ndim)
             ),
         )
+
+
+def set_module(globs: dict[str, Any], /) -> None:
+    """Set ``__module__`` attribute for objects in ``__all__``.
+
+    Parameters
+    ----------
+    globs : dict
+        Module namespace to modify.
+
+    Examples
+    --------
+    >>> set_module(globals())
+
+    """
+    name = globs['__name__']
+    for item in globs['__all__']:
+        obj = globs[item]
+        if hasattr(obj, '__module__'):
+            obj.__module__ = name

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