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

phasorpy/datasets.py

@@ -14,8 +14,11 @@ 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>`_
+  (`second record <https://zenodo.org/records/14860228>`_)
 - `Convallaria slice acquired with time-resolved 2-photon microscope
   <https://zenodo.org/records/14026720>`_
+- `Convallaria FLIM dataset in FLIM LABS JSON format
+  <https://zenodo.org/records/15007900>`_
 
 The implementation is based on the `Pooch <https://www.fatiando.org/pooch>`_
 library.
@@ -266,14 +269,15 @@ ZENODO_13625087 = pooch.create(
     base_url=(
         'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_13625087'
         # if DATA_ON_GITHUB
-        # else 'doi:10.1088/2050-6120/ac9ae9'
+        # else 'doi:10.1088/2050-6120/ac9ae9'  # TODO: not working with Pooch
     ),
     env=ENV,
     registry={
-        '33_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
-            'sha256:'
-            '68fcefcad4e750e9ec7068820e455258c986f6a9b724e66744a28bbbb689f986'
-        ),
+        # part of ZENODO_14860228
+        # '33_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
+        #    'sha256:'
+        #    '68fcefcad4e750e9ec7068820e455258c986f6a9b724e66744a28bbbb689f986'
+        # ),
         '34_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
             'sha256:'
             '5c0b7d76c274fd64891fca2507013b7c8c9979d8131ce282fac55fd24fbb38bd'
@@ -289,9 +293,65 @@ ZENODO_13625087 = pooch.create(
     },
 )
 
+ZENODO_14860228 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_14860228'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.14860228'
+    ),
+    env=ENV,
+    registry={
+        '38_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
+            'sha256:'
+            '092ac050edf55e26dcda8cba10122408c6f1b81d19accf07214385d6eebfcf3e'
+        ),
+        'spectral cell mask.lsm': (
+            'sha256:'
+            'c4c2c567bd99ef4930d7278794d4e3daebaad0375c0852a5ab86a2ea056f4fe3'
+        ),
+        'spectral golgi.lsm': (
+            'sha256:'
+            'd0a5079d9ed18b1248434f3f6d4b2b240fb034891121262cfe9dfec64d8429cd'
+        ),
+        'spectral hoehst.lsm': (
+            'sha256:'
+            '3ee44a7f9f125698bb5e34746d9723669f67c520ffbf21244757d7fc25dbbb88'
+        ),
+        'spectral lyso tracker green.lsm': (
+            'sha256:'
+            '0964448649e2c73a57f5ca0c705c86511fb4625c0a2af0d7850dfa39698fcbb9'
+        ),
+        'spectral mito tracker.lsm': (
+            'sha256:'
+            '99b9892b247256ebf8a9917c662bc7bb66a8daf3b5db950fbbb191de0cd35b37'
+        ),
+    },
+)
+
+ZENODO_14976703 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_14976703'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.14976703'
+    ),
+    env=ENV,
+    registry={
+        'Convalaria_LambdaScan.lif': (
+            'sha256:'
+            '27f1282cf02f87e11f8c7d3064066a4517ad4c9c769c796b32e459774f18c62a'
+        ),
+    },
+)
+
 CONVALLARIA_FBD = pooch.create(
     path=pooch.os_cache('phasorpy'),
-    base_url='doi:10.5281/zenodo.14026719',
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_14026720'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.14026719'
+    ),
     env=ENV,
     registry={
         'Convallaria_$EI0S.fbd': (
@@ -307,80 +367,94 @@ CONVALLARIA_FBD = pooch.create(
 
 FLIMLABS = pooch.create(
     path=pooch.os_cache('phasorpy'),
-    base_url='https://github.com/phasorpy/phasorpy-data/raw/main/flimlabs',
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/flimlabs'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.15007900'
+    ),
     env=ENV,
     registry={
-        'calibrator_2_5_1737112045_imaging.json': (
-            'sha256:'
-            'a34c7077e88d1e7272953a46b2bb4e3ab8adf5a2f61c824dfc27032d952b920e'
-        ),
-        'calibrator_2_5_1737112045_imaging.json.zip': (
+        'Convallaria_m2_1740751781_phasor_ch1.json': (
             'sha256:'
-            'fea791b28afd8365152018810cbbaaac1177cb72827578073587a1050d1af329'
+            'a8bf0179f352ab2c6c78d0bd399545ab1fb6d5537f23dc06e5f12a7ef5af6615'
         ),
-        'calibrator_2_5_1737112045_imaging_calibration.json': (
+        'Convallaria_m2_1740751781_phasor_ch1.json.zip': (
             'sha256:'
-            '8f2ebe9b544fae9524dc13221c1a5ab1b57d9dfd40ec2eb06a7b1475fcd63057'
+            '9c5691f55e85778717ace13607d573bcd00c29e357e063c8db4f173340f72984'
         ),
-        'calibrator_2_5_bis_1737112494_imaging.json': (
+        'Fluorescein_Calibration_m2_1740751189_imaging.json': (
             'sha256:'
-            '0509c5aba066419b03f83264eba58acbf4aae470aa1057c52f45e60225e033a4'
+            'aeebb074dbea6bff7578f409c7622b2f7f173bb23e5475d1436adedca7fc2eed'
         ),
-        'calibrator_2_5_bis_1737112494_imaging.json.zip': (
+        'Fluorescein_Calibration_m2_1740751189_imaging.json.zip': (
             'sha256:'
-            'bdc5df2a3f08a64ec7b7bb57b36e21546de142e67c59c052318252dbb66d8abf'
+            '32960bc1dec85fd16ffc7dd74a3cd63041fb3b69054ee6582f913129b0847086'
         ),
-        'calibrator_2_5_bis_1737112494_imaging_calibration.json': (
+        'Fluorescein_Calibration_m2_1740751189_imaging_calibration.json': (
             'sha256:'
-            '9bb0e21b1e7c04add672aa8a78048b09908c860fcaf907ca33c0c87d161f6ebf'
+            '7fd1b9749789bd139c132602a771a127ea0c76f403d1750e9636cd657cce017a'
         ),
-        'convallaria_1_1737112980_phasor_ch1.json': (
-            'sha256:'
-            '4a296a0d7898dc660a388e1bba5cf98b43c35fe12d94b7aba48d00245e37242d'
-        ),
-        'convallaria_1_1737112980_phasor_ch1.json.zip': (
+    },
+)
+
+FIGSHARE_22336594 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/figshare_22336594'
+        if DATA_ON_GITHUB
+        else 'doi:10.6084/m9.figshare.22336594.v1'
+    ),
+    env=ENV,
+    registry={
+        'FLIM_testdata.lif': (
             'sha256:'
-            '79c416b9099c9f58d2092fe5b26ea6d0f695977b877784cf564d3ead896d9354'
+            '902d8fa6cd39da7cf062b32d43aab518fa2a851eab72b4bd8b8eca1bad591850'
         ),
-        'convallaria_2_1737113097_phasor_ch1.json': (
+    },
+)
+
+FIGSHARE_22336594_EXPORTED = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/figshare_22336594'
+    ),
+    env=ENV,
+    registry={
+        'FLIM_testdata.lif.ptu': (
             'sha256:'
-            'da549645ffd898238c26f7a1eac3aca4ffccec86653c0d241a6ece674dfce90d'
+            'c85792b25d0b274f1484e490c99aa19052ab8e48e4e5022aabb1f218cd1123b6'
         ),
-        'convallaria_2_1737113097_phasor_ch1.json.zip': (
+        'FLIM_testdata.lif.ptu.zip': (
             'sha256:'
-            '8801bb14b457dceaef42e8b3bf6af770a2e14264cd2b282ba7e3d70b91ea954c'
+            'c5134c470f6a3e5cb21eabd538cbd5061d9911dad96d58e3a4040cfddadaef33'
         ),
-        'data_2_calibrator_2_5_1737112409_phasor_ch1.json': (
+        'FLIM_testdata.xlef': (
             'sha256:'
-            'ea8683892eb76f52231e5d6ceab64a3737454aa95fe73185366de8f758fd9b70'
+            '7860ef0847dc9f5534895a9c11b979bb446f67382b577fe63fb166e281e5dc5e'
         ),
-        'data_2_calibrator_2_5_1737112409_phasor_ch1.json.zip': (
+        'FLIM_testdata.xlef.zip': (
             'sha256:'
-            '40d2aa90b95fd8864a2392337c83a1a4f4931d7359cb30a486f65173f208de0a'
+            'ad0ad6389f38dcba6f9809b54934ef3f19da975d9dabeb4c3a248692b959b9cf'
         ),
-        'data_calibrator_2_5_1737112133_phasor_ch1.json': (
+        'FLIM_testdata.lif.filtered.ptu': (
             'sha256:'
-            '6a8790212bc62014d597402ec5feb0e50ec6ae2aa62d63fae8cb62c6c5656268'
+            'a00b84f626a39e79263322c60ae50b64163b36bb977ecc4dc54619097ba7f5b7'
         ),
-        'data_calibrator_2_5_1737112133_phasor_ch1.json.zip': (
+        'FLIM_testdata.lif.filtered.ptu.zip': (
             'sha256:'
-            'c9ef343bdbd7a51d23fdf4082e379dcdb1ce9f3e2ba065289bf2925d68ef55ba'
+            '717366b231213bfd6e295c3efb7bf1bcd90e720eb28aab3223376087172e93e5'
         ),
     },
 )
 
-FIGSHARE_22336594 = pooch.create(
+MISC = pooch.create(
     path=pooch.os_cache('phasorpy'),
-    base_url=(
-        'https://github.com/phasorpy/phasorpy-data/raw/main/figshare_22336594'
-        if DATA_ON_GITHUB
-        else 'doi:10.6084/m9.figshare.22336594.v1'
-    ),
+    base_url='https://github.com/phasorpy/phasorpy-data/raw/main/misc',
     env=ENV,
     registry={
-        'FLIM_testdata.lif': (
+        'NADHandSHG.ifli': (
             'sha256:'
-            '902d8fa6cd39da7cf062b32d43aab518fa2a851eab72b4bd8b8eca1bad591850'
+            'dfa65952850b8a222258776a8a14eb1ab7e70ff5f62b58aa2214797c5921b4a3'
         ),
     },
 )
@@ -391,9 +465,13 @@ REPOSITORIES: dict[str, pooch.Pooch] = {
     'flute': FLUTE,
     'napari-flim-phasor-plotter': NAPARI_FLIM_PHASOR_PLOTTER,
     'zenodo-13625087': ZENODO_13625087,
+    'zenodo-14860228': ZENODO_14860228,
+    'zenodo-14976703': ZENODO_14976703,
     'convallaria-fbd': CONVALLARIA_FBD,
     'flimlabs': FLIMLABS,
     'figshare_22336594': FIGSHARE_22336594,
+    'figshare_22336594_exported': FIGSHARE_22336594_EXPORTED,
+    'misc': MISC,
 }
 """Pooch repositories."""
 
@@ -406,19 +484,19 @@ def fetch(
 ) -> Any:  # str | tuple[str, ...]
     """Return absolute path(s) to sample file(s) in local storage.
 
-    The files are downloaded from a remote repository if they do not already
-    exist in the local storage.
+    The files are downloaded from a remote repository if not present in local
+    storage.
 
     Parameters
     ----------
-    *args: str or iterable of str, optional
+    *args : str or iterable of str, optional
         Name(s) of file(s) or repositories to fetch from local storage.
         If omitted, return files in all repositories.
     extract_dir : str or None, optional
         Path, relative to cache location, where ZIP files will be unpacked.
     return_scalar : bool, optional
         If true (default), return single path as string, else tuple of string.
-    **kwargs : optional
+    **kwargs
         Additional arguments passed to ``pooch.fetch()``.
         For example, ``progressbar=True``.
 

phasorpy/experimental.py

@@ -0,0 +1,312 @@
+"""Experimental functions.
+
+The ``phasorpy.experimental`` module provides functions related to phasor
+analysis for evaluation.
+The functions may be removed or moved to other modules in future releases.
+
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    'anscombe_transform',
+    'anscombe_transform_inverse',
+    'spectral_vector_denoise',
+]
+
+import math
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._typing import Any, NDArray, ArrayLike, DTypeLike, Literal, Sequence
+
+import numpy
+
+from ._phasorpy import (
+    _anscombe,
+    _anscombe_inverse,
+    _anscombe_inverse_approx,
+    _phasor_from_signal_vector,
+    _signal_denoise_vector,
+)
+from ._utils import parse_harmonic
+from .utils import number_threads
+
+
+def anscombe_transform(
+    data: ArrayLike,
+    /,
+    **kwargs: Any,
+) -> NDArray[Any]:
+    r"""Return Anscombe variance-stabilizing transformation.
+
+    The Anscombe transformation normalizes the standard deviation of noisy,
+    Poisson-distributed data.
+    It can be used to transform un-normalized phasor coordinates to
+    approximate standard Gaussian distributions.
+
+    Parameters
+    ----------
+    data : array_like
+        Noisy Poisson-distributed data to be transformed.
+    **kwargs
+        Optional `arguments passed to numpy universal functions
+        <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
+
+    Returns
+    -------
+    ndarray
+        Anscombe-transformed data with variance of approximately 1.
+
+    Notes
+    -----
+    The Anscombe transformation according to [1]_:
+
+    .. math::
+
+        z = 2 \cdot \sqrt{x + 3 / 8}
+
+    References
+    ----------
+
+    .. [1] Anscombe FJ.
+       `The transformation of Poisson, binomial and negative-binomial data
+       <https://doi.org/10.2307/2332343>`_.
+       *Biometrika*, 35(3-4): 246-254 (1948)
+
+    Examples
+    --------
+
+    >>> z = anscombe_transform(numpy.random.poisson(10, 10000))
+    >>> numpy.allclose(numpy.std(z), 1.0, atol=0.1)
+    True
+
+    """
+    return _anscombe(data, **kwargs)  # type: ignore[no-any-return]
+
+
+def anscombe_transform_inverse(
+    data: ArrayLike,
+    /,
+    *,
+    approx: bool = False,
+    **kwargs: Any,
+) -> NDArray[Any]:
+    r"""Return inverse Anscombe transformation.
+
+    Parameters
+    ----------
+    data : array_like
+        Anscombe-transformed data.
+    approx : bool, default: False
+        If true, return approximation of exact unbiased inverse.
+    **kwargs
+        Optional `arguments passed to numpy universal functions
+        <https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs>`_.
+
+    Returns
+    -------
+    ndarray
+        Inverse Anscombe-transformed data.
+
+    Notes
+    -----
+    The inverse Anscombe transformation according to [1]_:
+
+    .. math::
+
+        x = (z / 2.0)^2 - 3 / 8
+
+    The approximate inverse Anscombe transformation according to [2]_ and [3]_:
+
+    .. math::
+
+        x = 1/4 \cdot z^2
+          + 1/4 \cdot \sqrt{3/2} \cdot z^{-1}
+          - 11/8 \cdot z^{-2}
+          + 5/8 \cdot \sqrt(3/2) \cdot z^{-3}
+          - 1/8
+
+    References
+    ----------
+
+    .. [2] Makitalo M, and Foi A.
+       `A closed-form approximation of the exact unbiased inverse of the
+       Anscombe variance-stabilizing transformation
+       <https://doi.org/10.1109/TIP.2011.2121085>`_.
+       *IEEE Trans Image Process*, 20(9): 2697-8 (2011).
+
+    .. [3] Makitalo M, and Foi A
+       `Optimal inversion of the generalized Anscombe transformation for
+       Poisson-Gaussian noise
+       <https://doi.org/10.1109/TIP.2012.2202675>`_,
+       *IEEE Trans Image Process*, 22(1): 91-103 (2013)
+
+    Examples
+    --------
+
+    >>> x = numpy.random.poisson(10, 100)
+    >>> x2 = anscombe_transform_inverse(anscombe_transform(x))
+    >>> numpy.allclose(x, x2, atol=1e-3)
+    True
+
+    """
+    if approx:
+        return _anscombe_inverse_approx(  # type: ignore[no-any-return]
+            data, **kwargs
+        )
+    return _anscombe_inverse(data, **kwargs)  # type: ignore[no-any-return]
+
+
+def spectral_vector_denoise(
+    signal: ArrayLike,
+    /,
+    spectral_vector: ArrayLike | None = None,
+    *,
+    axis: int = -1,
+    harmonic: int | Sequence[int] | Literal['all'] | str | None = None,
+    sigma: float = 0.05,
+    vmin: float | None = None,
+    dtype: DTypeLike | None = None,
+    num_threads: int | None = None,
+) -> NDArray[Any]:
+    """Return spectral-vector-denoised signal.
+
+    The spectral vector denoising algorithm is based on a Gaussian weighted
+    average calculation, with weights obtained in n-dimensional Chebyshev or
+    Fourier space [4]_.
+
+    Parameters
+    ----------
+    signal : array_like
+        Hyperspectral data to be denoised.
+        A minimum of three samples are required along `axis`.
+        The samples must be uniformly spaced.
+    spectral_vector : array_like, optional
+        Spectral vector.
+        For example, phasor coordinates, PCA projected phasor coordinates,
+        or Chebyshev coefficients.
+        Must be of same shape as `signal` with `axis` removed and axis
+        containing spectral space appended.
+        If None (default), phasor coordinates are calculated at specified
+        `harmonic`.
+    axis : int, optional, default: -1
+        Axis over which `spectral_vector` is computed if not provided.
+        The default is the last axis (-1).
+    harmonic : int, sequence of int, or 'all', optional
+        Harmonics to include in calculating `spectral_vector`.
+        If `'all'`, include all harmonics for `signal` samples along `axis`.
+        Else, harmonics must be at least one and no larger than half the
+        number of `signal` samples along `axis`.
+        The default is the first harmonic (fundamental frequency).
+        A minimum of `harmonic * 2 + 1` samples are required along `axis`
+        to calculate correct phasor coordinates at `harmonic`.
+    sigma : float, default: 0.05
+        Width of Gaussian filter in spectral vector space.
+        Weighted averages are calculated using the spectra of signal items
+        within an spectral vector Euclidean distance of `3 * sigma` and
+        intensity above `vmin`.
+    vmin : float, optional
+        Signal intensity along `axis` below which not to include in denoising.
+    dtype : dtype_like, optional
+        Data type of output arrays. Either float32 or float64.
+        The default is float64 unless the `signal` is float32.
+    num_threads : int, optional
+        Number of OpenMP threads to use for parallelization.
+        By default, multi-threading is disabled.
+        If zero, up to half of logical CPUs are used.
+        OpenMP may not be available on all platforms.
+
+    Returns
+    -------
+    ndarray
+        Denoised signal of `dtype`.
+        Spectra with integrated intensity below `vmin` are unchanged.
+
+    References
+    ----------
+
+    .. [4] Harman RC, Lang RT, Kercher EM, Leven P, and Spring BQ.
+       `Denoising multiplexed microscopy images in n-dimensional spectral space
+       <https://doi.org/10.1364/BOE.463979>`_.
+       *Biomed Opt Express*, 13(8): 4298-4309 (2022)
+
+    Examples
+    --------
+    Denoise a hyperspectral image with a Gaussian filter width of 0.1 in
+    spectral vector space using first and second harmonic:
+
+    >>> signal = numpy.random.randint(0, 255, (8, 16, 16))
+    >>> spectral_vector_denoise(signal, axis=0, sigma=0.1, harmonic=[1, 2])
+    array([[[...]]])
+
+    """
+    num_threads = number_threads(num_threads)
+
+    signal = numpy.asarray(signal)
+    if axis == -1 or axis == signal.ndim - 1:
+        axis = -1
+    else:
+        signal = numpy.moveaxis(signal, axis, -1)
+    shape = signal.shape
+    samples = shape[-1]
+
+    if harmonic is None:
+        harmonic = 1
+    harmonic, _ = parse_harmonic(harmonic, samples // 2)
+    num_harmonics = len(harmonic)
+
+    if vmin is None or vmin < 0.0:
+        vmin = 0.0
+
+    sincos = numpy.empty((num_harmonics, samples, 2))
+    for i, h in enumerate(harmonic):
+        phase = numpy.linspace(
+            0,
+            h * math.pi * 2.0,
+            samples,
+            endpoint=False,
+            dtype=numpy.float64,
+        )
+        sincos[i, :, 0] = numpy.cos(phase)
+        sincos[i, :, 1] = numpy.sin(phase)
+
+    signal = numpy.ascontiguousarray(signal).reshape(-1, samples)
+    size = signal.shape[0]
+
+    if dtype is None:
+        if signal.dtype.char == 'f':
+            dtype = signal.dtype
+        else:
+            dtype = numpy.float64
+    dtype = numpy.dtype(dtype)
+    if dtype.char not in {'d', 'f'}:
+        raise ValueError('dtype is not floating point')
+
+    if spectral_vector is None:
+        spectral_vector = numpy.zeros((size, num_harmonics * 2), dtype=dtype)
+        _phasor_from_signal_vector(
+            spectral_vector, signal, sincos, num_threads
+        )
+    else:
+        spectral_vector = numpy.ascontiguousarray(spectral_vector, dtype=dtype)
+        if spectral_vector.shape[:-1] != shape[:-1]:
+            raise ValueError('signal and spectral_vector shape mismatch')
+        spectral_vector = spectral_vector.reshape(
+            -1, spectral_vector.shape[-1]
+        )
+
+    if dtype == signal.dtype:
+        denoised = signal.copy()
+    else:
+        denoised = numpy.zeros(signal.shape, dtype=dtype)
+        denoised[:] = signal
+    integrated = numpy.zeros(size, dtype=dtype)
+    _signal_denoise_vector(
+        denoised, integrated, signal, spectral_vector, sigma, vmin, num_threads
+    )
+
+    denoised = denoised.reshape(shape)
+    if axis != -1:
+        denoised = numpy.moveaxis(denoised, -1, axis)
+    return denoised