phasorpy 0.1__cp313-cp313-macosx_11_0_arm64.whl → 0.2__cp313-cp313-macosx_11_0_arm64.whl

phasorpy/_phasorpy.pyx

@@ -61,6 +61,8 @@ ctypedef fused signal_t:
     float
     double
 
+from libc.stdlib cimport free, malloc
+
 
 def _phasor_from_signal(
     float_t[:, :, ::1] phasor,
@@ -115,7 +117,7 @@ def _phasor_from_signal(
     # https://numpy.org/devdocs/reference/c-api/iterator.html
 
     if (
-        samples < 3
+        samples < 2
         or harmonics > samples // 2
         or phasor.shape[0] != harmonics * 2 + 1
         or phasor.shape[1] != signal.shape[0]
@@ -428,6 +430,7 @@ def _gaussian_signal(
 ###############################################################################
 # FRET model
 
+
 @cython.ufunc
 cdef (double, double) _phasor_from_fret_donor(
     double omega,
@@ -953,6 +956,7 @@ cdef (float_t, float_t) _phasor_divide(
 ###############################################################################
 # Geometry ufuncs
 
+
 @cython.ufunc
 cdef short _is_inside_range(
     float_t x,  # point
@@ -1559,6 +1563,7 @@ cdef (double, double, double, double) _intersection_circle_line(
         y + (-dd * dx - fabs(dy) * rdd) / dr,
     )
 
+
 ###############################################################################
 # Blend ufuncs
 
@@ -1630,6 +1635,7 @@ cdef float_t _blend_lighten(
         return a
     return <float_t> max(a, b)
 
+
 ###############################################################################
 # Threshold ufuncs
 
@@ -1809,3 +1815,329 @@ cdef (double, double, double) _phasor_threshold_nan(
         return <float_t> NAN, <float_t> NAN, <float_t> NAN
 
     return mean, real, imag
+
+
+###############################################################################
+# Unary ufuncs
+
+
+@cython.ufunc
+cdef float_t _anscombe(
+    float_t x,
+) noexcept nogil:
+    """Return anscombe variance stabilizing transformation."""
+    if isnan(x):
+        return <float_t> NAN
+
+    return <float_t> (2.0 * sqrt(<double> x + 0.375))
+
+
+@cython.ufunc
+cdef float_t _anscombe_inverse(
+    float_t x,
+) noexcept nogil:
+    """Return inverse anscombe transformation."""
+    if isnan(x):
+        return <float_t> NAN
+
+    return <float_t> (x * x / 4.0 - 0.375)  # 3/8
+
+
+@cython.ufunc
+cdef float_t _anscombe_inverse_approx(
+    float_t x,
+) noexcept nogil:
+    """Return inverse anscombe transformation.
+
+    Using approximation of exact unbiased inverse.
+
+    """
+    if isnan(x):
+        return <float_t> NAN
+
+    return <float_t> (
+        0.25 * x * x  # 1/4
+        + 0.30618621784789724 / x  # 1/4 * sqrt(3/2)
+        - 1.375 / (x * x)  # 11/8
+        + 0.7654655446197431 / (x * x * x)  # 5/8 * sqrt(3/2)
+        - 0.125  # 1/8
+    )
+
+
+###############################################################################
+# Denoising in spectral space
+
+
+def _phasor_from_signal_vector(
+    float_t[:, ::1] phasor,
+    const signal_t[:, ::1] signal,
+    const double[:, :, ::1] sincos,
+    const int num_threads
+):
+    """Calculate phasor coordinate vectors from signal along last axis.
+
+    Parameters
+    ----------
+    phasor : 2D memoryview of float32 or float64
+        Writable buffer of two dimensions where calculated phasor
+        vectors are stored:
+
+        0. other dimensions flat
+        1. real and imaginary components
+
+    signal : 2D memoryview of float32 or float64
+        Buffer of two dimensions containing signal:
+
+        0. other dimensions flat
+        1. dimension over which to compute FFT, number samples
+
+    sincos : 3D memoryview of float64
+        Buffer of three dimensions containing sine and cosine terms to be
+        multiplied with signal:
+
+        0. number harmonics
+        1. number samples
+        2. cos and sin
+
+    num_threads : int
+        Number of OpenMP threads to use for parallelization.
+
+    Notes
+    -----
+    This implementation requires contiguous input arrays.
+
+    """
+    cdef:
+        ssize_t size = signal.shape[0]
+        ssize_t samples = signal.shape[1]
+        ssize_t harmonics = sincos.shape[0]
+        ssize_t i, j, k, h
+        double dc, re, im, sample
+
+    if (
+        samples < 2
+        or harmonics > samples // 2
+        or phasor.shape[0] != size
+        or phasor.shape[1] != harmonics * 2
+    ):
+        raise ValueError('invalid shape of phasor or signal')
+    if sincos.shape[1] != samples or sincos.shape[2] != 2:
+        raise ValueError('invalid shape of sincos')
+
+    with nogil, parallel(num_threads=num_threads):
+        for i in prange(signal.shape[0]):
+            j = 0
+            for h in range(harmonics):
+                dc = 0.0
+                re = 0.0
+                im = 0.0
+                for k in range(samples):
+                    sample = <double> signal[i, k]
+                    dc = dc + sample
+                    re = re + sample * sincos[h, k, 0]
+                    im = im + sample * sincos[h, k, 1]
+                if dc != 0.0:
+                    re = re / dc
+                    im = im / dc
+                else:
+                    re = NAN if re == 0.0 else re * INFINITY
+                    im = NAN if im == 0.0 else im * INFINITY
+                phasor[i, j] = <float_t> re
+                j = j + 1
+                phasor[i, j] = <float_t> im
+                j = j + 1
+
+
+def _signal_denoise_vector(
+    float_t[:, ::1] denoised,
+    float_t[::1] integrated,
+    const signal_t[:, ::1] signal,
+    const float_t[:, ::1] spectral_vector,
+    const double sigma,
+    const double vmin,
+    const int num_threads
+):
+    """Calculate denoised signal from spectral_vector."""
+    cdef:
+        ssize_t size = signal.shape[0]
+        ssize_t samples = signal.shape[1]
+        ssize_t dims = spectral_vector.shape[1]
+        ssize_t i, j, m
+        float_t n
+        double weight, sum, t
+        double sigma2 = -1.0 / (2.0 * sigma * sigma)
+        double threshold = 9.0 * sigma * sigma
+
+    if denoised.shape[0] != size or denoised.shape[1] != samples:
+        raise ValueError('signal and denoised shape mismatch')
+    if integrated.shape[0] != size:
+        raise ValueError('integrated.shape[0] != signal.shape[0]')
+    if spectral_vector.shape[0] != size:
+        raise ValueError('spectral_vector.shape[0] != signal.shape[0]')
+
+    with nogil, parallel(num_threads=num_threads):
+
+        # integrate channel intensities for each pixel
+        # and filter low intensities
+        for i in prange(size):
+            sum = 0.0
+            for m in range(samples):
+                sum = sum + <double> signal[i, m]
+            if sum < vmin:
+                sum = NAN
+            integrated[i] = <float_t> sum
+
+        # loop over all pixels
+        for i in prange(size):
+
+            n = integrated[i]
+            if not n > 0.0:
+                # n is NaN or zero; cannot denoise; return original signal
+                continue
+
+            for m in range(samples):
+                denoised[i, m] /= n  # weight = 1.0
+
+            # loop over other pixels
+            for j in range(size):
+                if i == j:
+                    # weight = 1.0 already accounted for
+                    continue
+
+                n = integrated[j]
+                if not n > 0.0:
+                    # n is NaN or zero
+                    continue
+
+                # calculate weight from Euclidean distance of
+                # pixels i and j in spectral vector space
+                sum = 0.0
+                for m in range(dims):
+                    t = spectral_vector[i, m] - spectral_vector[j, m]
+                    sum = sum + t * t
+                    if sum > threshold:
+                        sum = -1.0
+                        break
+                if sum >= 0.0:
+                    weight = exp(sum * sigma2) / n
+                else:
+                    # sum is NaN or greater than threshold
+                    continue
+
+                # add weighted signal[j] to denoised[i]
+                for m in range(samples):
+                    denoised[i, m] += <float_t> (weight * signal[j, m])
+
+            # re-normalize to original intensity
+            # sum cannot be zero because integrated == 0 was filtered
+            sum = 0.0
+            for m in range(samples):
+                sum = sum + denoised[i, m]
+            n = <float_t> (<double> integrated[i] / sum)
+            for m in range(samples):
+                denoised[i, m] *= n
+
+
+###############################################################################
+# Filtering functions
+
+
+cdef float_t _median(float_t *values, const ssize_t size) noexcept nogil:
+    """Return median of array values using Quickselect algorithm."""
+    cdef:
+        ssize_t i, pivot_index, pivot_index_new
+        ssize_t left = 0
+        ssize_t right = size - 1
+        ssize_t middle = size // 2
+        float_t pivot_value, temp
+
+    if size % 2 == 0:
+        middle -= 1  # Quickselect sorts on right
+
+    while left <= right:
+        pivot_index = left + (right - left) // 2
+        pivot_value = values[pivot_index]
+        temp = values[pivot_index]
+        values[pivot_index] = values[right]
+        values[right] = temp
+        pivot_index_new = left
+        for i in range(left, right):
+            if values[i] < pivot_value:
+                temp = values[i]
+                values[i] = values[pivot_index_new]
+                values[pivot_index_new] = temp
+                pivot_index_new += 1
+        temp = values[right]
+        values[right] = values[pivot_index_new]
+        values[pivot_index_new] = temp
+
+        if pivot_index_new == middle:
+            if size % 2 == 0:
+                return (values[middle] + values[middle + 1]) / <float_t> 2.0
+            return values[middle]
+        if pivot_index_new < middle:
+            left = pivot_index_new + 1
+        else:
+            right = pivot_index_new - 1
+
+    return values[middle]  # unreachable code?
+
+
+def _median_filter_2d(
+    float_t[:, :] image,
+    float_t[:, ::1] filtered_image,
+    const ssize_t kernel_size,
+    const int repeat=1,
+    const int num_threads=1,
+):
+    """Apply 2D median filter ignoring NaN."""
+    cdef:
+        ssize_t rows = image.shape[0]
+        ssize_t cols = image.shape[1]
+        ssize_t k = kernel_size // 2
+        ssize_t i, j, r, di, dj, ki, kj, valid_count
+        float_t element
+        float_t *kernel
+
+    if kernel_size <= 0:
+        raise ValueError('kernel_size must be greater than 0')
+
+    with nogil, parallel(num_threads=num_threads):
+
+        kernel = <float_t *> malloc(
+            kernel_size * kernel_size * sizeof(float_t)
+        )
+        if kernel == NULL:
+            with gil:
+                raise MemoryError('failed to allocate kernel')
+
+        for r in range(repeat):
+            for i in prange(rows):
+                for j in range(cols):
+                    if isnan(image[i, j]):
+                        filtered_image[i, j] = <float_t> NAN
+                        continue
+                    valid_count = 0
+                    for di in range(kernel_size):
+                        ki = i - k + di
+                        if ki < 0:
+                            ki = 0
+                        elif ki >= rows:
+                            ki = rows - 1
+                        for dj in range(kernel_size):
+                            kj = j - k + dj
+                            if kj < 0:
+                                kj = 0
+                            elif kj >= cols:
+                                kj = cols - 1
+                            element = image[ki, kj]
+                            if not isnan(element):
+                                kernel[valid_count] = element
+                                valid_count = valid_count + 1
+                    filtered_image[i, j] = _median(kernel, valid_count)
+
+            for i in prange(rows):
+                for j in range(cols):
+                    image[i, j] = filtered_image[i, j]
+
+        free(kernel)

phasorpy/_utils.py

@@ -249,52 +249,65 @@ def phasor_from_polar_scalar(
 
 def parse_harmonic(
     harmonic: int | Sequence[int] | Literal['all'] | str | None,
-    samples: int,
+    harmonic_max: int | None = None,
     /,
 ) -> tuple[list[int], bool]:
     """Return parsed harmonic parameter.
 
+    This function performs common, but not necessarily all, verifications
+    of user-provided `harmonic` parameter.
+
     Parameters
     ----------
     harmonic : int, list of int, 'all', or None
         Harmonic parameter to parse.
-    samples : int
-        Number of samples in signal.
-        Used to verify harmonic values and set maximum harmonic value.
+    harmonic_max : int, optional
+        Maximum value allowed in `hamonic`. 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`
+        (included) is returned.
 
     Returns
     -------
     harmonic : list of int
         Parsed list of harmonics.
     has_harmonic_axis : bool
-        If true, `harmonic` input parameter is an integer, else a list.
+        False if `harmonic` input parameter is a scalar integer.
 
     Raises
     ------
     IndexError
-        Any element is out of range [1..samples // 2].
+        Any element is out of range `[1..harmonic_max]`.
     ValueError
         Elements are not unique.
         Harmonic is empty.
         String input is not 'all'.
+        `harmonic_max` is smaller than 1.
     TypeError
         Any element is not an integer.
+        `harmonic` is `'all'` and `harmonic_max` is None.
 
     """
-    if samples < 3:
-        raise ValueError(f'{samples=} < 3')
+    if harmonic_max is not None and harmonic_max < 1:
+        raise ValueError(f'{harmonic_max=} < 1')
 
     if harmonic is None:
         return [1], False
 
-    harmonic_max = samples // 2
     if isinstance(harmonic, (int, numbers.Integral)):
-        if harmonic < 1 or harmonic > harmonic_max:
+        if harmonic < 1 or (
+            harmonic_max is not None and harmonic > harmonic_max
+        ):
             raise IndexError(f'{harmonic=} out of range [1..{harmonic_max}]')
         return [int(harmonic)], False
 
     if isinstance(harmonic, str):
         if harmonic == 'all':
+            if harmonic_max is None:
+                raise TypeError(
+                    f'maximum harmonic must be specified for {harmonic=!r}'
+                )
             return list(range(1, harmonic_max + 1)), True
         raise ValueError(f'{harmonic=!r} is not a valid harmonic')
 
@@ -303,10 +316,10 @@ def parse_harmonic(
         raise ValueError(f'{harmonic=} is empty')
     if h.dtype.kind not in 'iu' or h.ndim != 1:
         raise TypeError(f'{harmonic=} element not an integer')
-    if numpy.any(h < 1) or numpy.any(h > harmonic_max):
-        raise IndexError(
-            f'{harmonic=} element out of range [1..{harmonic_max}]'
-        )
+    if numpy.any(h < 1):
+        raise IndexError(f'{harmonic=} element < 1')
+    if harmonic_max is not None and numpy.any(h > harmonic_max):
+        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

phasorpy/datasets.py

@@ -14,6 +14,8 @@ Datasets from the following repositories are available:
   <https://github.com/zoccoler/napari-flim-phasor-plotter/tree/0.0.6/src/napari_flim_phasor_plotter/data>`_
 - `Phasor-based multi-harmonic unmixing for in-vivo hyperspectral imaging
   <https://zenodo.org/records/13625087>`_
+- `Convallaria slice acquired with time-resolved 2-photon microscope
+  <https://zenodo.org/records/14026720>`_
 
 The implementation is based on the `Pooch <https://www.fatiando.org/pooch>`_
 library.
@@ -287,12 +289,30 @@ ZENODO_13625087 = pooch.create(
     },
 )
 
+CONVALLARIA_FBD = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url='doi:10.5281/zenodo.14026719',
+    env=ENV,
+    registry={
+        'Convallaria_$EI0S.fbd': (
+            'sha256:'
+            '3751891b02e3095fedd53a09688d8a22ff2a0083544dd5c0726b9267d11df1bc'
+        ),
+        'Calibration_Rhodamine110_$EI0S.fbd': (
+            'sha256:'
+            'd745cbcdd4a10dbaed83ee9f1b150f0c7ddd313031e18233293582cdf10e4691'
+        ),
+    },
+)
+
+
 REPOSITORIES: dict[str, pooch.Pooch] = {
     'tests': TESTS,
     'lfd-workshop': LFD_WORKSHOP,
     'flute': FLUTE,
     'napari-flim-phasor-plotter': NAPARI_FLIM_PHASOR_PLOTTER,
     'zenodo-13625087': ZENODO_13625087,
+    'convallaria-fbd': CONVALLARIA_FBD,
 }
 """Pooch repositories."""
 

phasorpy/io.py

@@ -290,11 +290,9 @@ def phasor_to_ometiff(
             imag = imag.reshape(1, -1)
 
     if harmonic is not None:
-        harmonic_array = numpy.atleast_1d(harmonic)
-        if harmonic_array.ndim > 1 or harmonic_array.size != nharmonic:
+        harmonic, _ = parse_harmonic(harmonic)
+        if len(harmonic) != nharmonic:
             raise ValueError('invalid harmonic')
-        samples = int(harmonic_array.max()) * 2 + 1
-        harmonic, _ = parse_harmonic(harmonic, samples)
 
     if frequency is not None:
         frequency_array = numpy.atleast_2d(frequency).astype(numpy.float64)
@@ -488,7 +486,7 @@ def phasor_from_ometiff(
 
         has_harmonic_dim = tif.series[1].ndim > tif.series[0].ndim
         nharmonics = tif.series[1].shape[0] if has_harmonic_dim else 1
-        maxharmonic = nharmonics
+        harmonic_max = nharmonics
         for i in (3, 4):
             if len(tif.series) < i + 1:
                 break
@@ -499,10 +497,10 @@ def phasor_from_ometiff(
             elif series.name == 'Phasor harmonic':
                 if not has_harmonic_dim and data.size == 1:
                     attrs['harmonic'] = int(data.item(0))
-                    maxharmonic = attrs['harmonic']
+                    harmonic_max = attrs['harmonic']
                 elif has_harmonic_dim and data.size == nharmonics:
                     attrs['harmonic'] = data.tolist()
-                    maxharmonic = max(attrs['harmonic'])
+                    harmonic_max = max(attrs['harmonic'])
                 else:
                     logger.warning(
                         f'harmonic={data} does not match phasor '
@@ -535,7 +533,7 @@ def phasor_from_ometiff(
             imag = tif.series[2].asarray()
         else:
             # specified harmonics
-            harmonic, keepdims = parse_harmonic(harmonic, 2 * maxharmonic + 1)
+            harmonic, keepdims = parse_harmonic(harmonic, harmonic_max)
             try:
                 if isinstance(harmonic_stored, list):
                     index = [harmonic_stored.index(h) for h in harmonic]
@@ -769,7 +767,7 @@ def phasor_from_simfcs_referenced(
     else:
         raise ValueError(f'file extension must be .ref or .r64, not {ext!r}')
 
-    harmonic, keep_harmonic_dim = parse_harmonic(harmonic, data.shape[0])
+    harmonic, keep_harmonic_dim = parse_harmonic(harmonic, data.shape[0] // 2)
 
     mean = data[0].copy()
     real = numpy.empty((len(harmonic),) + mean.shape, numpy.float32)