phasorpy 0.1__cp310-cp310-win_amd64.whl → 0.2__cp310-cp310-win_amd64.whl

phasorpy/utils.py

@@ -7,9 +7,309 @@ that do not naturally fit into other modules.
 
 from __future__ import annotations
 
-__all__ = ['number_threads']
+__all__ = [
+    'anscombe_transformation',
+    'anscombe_transformation_inverse',
+    'number_threads',
+    'spectral_vector_denoise',
+]
 
+import math
 import os
+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
+
+
+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>`_.
+       *Biomedical Optics 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
+
+
+def anscombe_transformation(
+    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_transformation(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_transformation_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{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_transformation_inverse(anscombe_transformation(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 number_threads(

phasorpy/version.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = '0.1'
+__version__ = '0.2'
 
 
 def versions(

{phasorpy-0.1.dist-info → phasorpy-0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: phasorpy
-Version: 0.1
+Version: 0.2
 Summary: Analysis of fluorescence lifetime and hyperspectral images using the phasor approach
 Author: PhasorPy Contributors
 License: MIT
@@ -26,32 +26,32 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: numpy >=1.24.0
-Requires-Dist: matplotlib >=3.7.0
-Requires-Dist: scipy >=1.11.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: scipy>=1.11.0
 Requires-Dist: click
 Requires-Dist: pooch
 Requires-Dist: tqdm
-Requires-Dist: xarray >=2023.4.0
-Requires-Dist: tifffile >=2024.8.30
-Provides-Extra: all
-Requires-Dist: lfdfiles >=2024.5.24 ; extra == 'all'
-Requires-Dist: sdtfile >=2024.5.24 ; extra == 'all'
-Requires-Dist: ptufile >=2024.9.14 ; extra == 'all'
+Requires-Dist: xarray>=2023.4.0
+Requires-Dist: tifffile>=2024.8.30
 Provides-Extra: docs
-Requires-Dist: sphinx ; extra == 'docs'
-Requires-Dist: sphinx-issues ; extra == 'docs'
-Requires-Dist: sphinx-gallery ; extra == 'docs'
-Requires-Dist: sphinx-copybutton ; extra == 'docs'
-Requires-Dist: sphinx-click ; extra == 'docs'
-Requires-Dist: pydata-sphinx-theme ; extra == 'docs'
-Requires-Dist: numpydoc ; extra == 'docs'
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-issues; extra == "docs"
+Requires-Dist: sphinx_gallery; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx_click; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.16.0; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
 Provides-Extra: test
-Requires-Dist: pytest ; extra == 'test'
-Requires-Dist: pytest-cov ; extra == 'test'
-Requires-Dist: pytest-runner ; extra == 'test'
-Requires-Dist: pytest-doctestplus ; extra == 'test'
-Requires-Dist: coverage ; extra == 'test'
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-runner; extra == "test"
+Requires-Dist: pytest-doctestplus; extra == "test"
+Requires-Dist: coverage; extra == "test"
+Provides-Extra: all
+Requires-Dist: lfdfiles>=2024.5.24; extra == "all"
+Requires-Dist: sdtfile>=2024.5.24; extra == "all"
+Requires-Dist: ptufile>=2024.9.14; extra == "all"
 
 # PhasorPy
 

phasorpy-0.2.dist-info/RECORD

@@ -0,0 +1,24 @@
+phasorpy/__init__.py,sha256=SwOTreV7wd8ZEL3waXQlgbNnsErWJ0dh6A2d77DWp0Y,254
+phasorpy/__main__.py,sha256=0u6C98HYfajV1RoUww8kAc0CxdsON0ijgEyTYExCSLM,149
+phasorpy/_phasorpy.cp310-win_amd64.pyd,sha256=Vct4w6guzUyhS4imLU4i6MTFSKOtnXf1ELL7Z_mfuYk,857600
+phasorpy/_phasorpy.pyx,sha256=MYThk_WpOtiER3fetO5YbvT8f22l4L697WsZ4zqrz54,61361
+phasorpy/_typing.py,sha256=ii-5-8KTs2BZq0Ytu3yJl8ejSQj1V06c1_Jcwa_2Snk,1324
+phasorpy/_utils.py,sha256=0c3d8D69wG7mTUzc-qh4GDff64FXJK9vFzRrZ0-XOqw,13255
+phasorpy/cli.py,sha256=orN_31JOTzIUEfySwTo_Kr24UUzPKdA-DkemsmM8IHk,1977
+phasorpy/color.py,sha256=axzL2b0d_g_6pG1wgHSdbiNtn7wAooYl3t-zaUNOBTE,17313
+phasorpy/components.py,sha256=0ZuUaJllf4c2UFbiTOse5PYXkMLNF8q5VSUxvSgPjy8,10415
+phasorpy/conftest.py,sha256=BywY24LnrOhaTHZIYkVAQ09JmvKZXevNKoshdLeL9nA,949
+phasorpy/cursors.py,sha256=sUZ-9PJ5faJLWewRuENhF7nRJ-drPtW8Ui8YWD6UOw4,15546
+phasorpy/datasets.py,sha256=AvZcR9hVgW5m7blKt51tFPC7zd1HBJ46GjfCeBb2r9E,15523
+phasorpy/io.py,sha256=UGNsRJwzKQCxwilgHC6WYKH_jU97mEJhmC_X3ERoLmw,54103
+phasorpy/phasor.py,sha256=Zb3TD6yCLXskCoPSZtSAWeUl1SF0yUKU7pXnVYzJRwI,108671
+phasorpy/plot.py,sha256=NfIEn_QynSMNTQGvDrSU6UsIgz15A43VcCLRfsLtnMk,69810
+phasorpy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+phasorpy/utils.py,sha256=an_dOCZM9WCNUxI3GFuxdjrF8BRVQIc0OnQStgiXF7A,11675
+phasorpy/version.py,sha256=O9DsCV_S63GinqqT6KqrDH1NVV-e0GITROCioK300Pg,1800
+phasorpy-0.2.dist-info/LICENSE.txt,sha256=bxzmxrql9vHNenjAb0m7dSkLbEQJW9zJi2E0WjkAI68,1104
+phasorpy-0.2.dist-info/METADATA,sha256=DnwjIXBKU4CtRl1VOr0laS0nhsqfSXGeajgvRMdrKW0,3464
+phasorpy-0.2.dist-info/WHEEL,sha256=tcd-HDpskugT8GYYKyyid0lOlzoZtZdWwcrj5ormtfo,101
+phasorpy-0.2.dist-info/entry_points.txt,sha256=VRhsl3qGiIKwtMraKapmduchTMbdReUi1AoVTe9f3ss,47
+phasorpy-0.2.dist-info/top_level.txt,sha256=4Y0uYzya5R2loleAxZ6s2n53_FysUbgFTfFaU0i9rbo,9
+phasorpy-0.2.dist-info/RECORD,,

{phasorpy-0.1.dist-info → phasorpy-0.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.1.0)
+Generator: setuptools (75.6.0)
 Root-Is-Purelib: false
 Tag: cp310-cp310-win_amd64
 

phasorpy-0.1.dist-info/RECORD

@@ -1,24 +0,0 @@
-phasorpy/__init__.py,sha256=SwOTreV7wd8ZEL3waXQlgbNnsErWJ0dh6A2d77DWp0Y,254
-phasorpy/__main__.py,sha256=0u6C98HYfajV1RoUww8kAc0CxdsON0ijgEyTYExCSLM,149
-phasorpy/_phasorpy.cp310-win_amd64.pyd,sha256=KjLrBCDCjS-YmXeGgR-c-nIPF0GLUfel3BKeapqY0Oc,523776
-phasorpy/_phasorpy.pyx,sha256=UaeZnopcilXZVhJVSlR6tgTpfnaa3LZEEbqMwpSuGsE,50792
-phasorpy/_typing.py,sha256=ii-5-8KTs2BZq0Ytu3yJl8ejSQj1V06c1_Jcwa_2Snk,1324
-phasorpy/_utils.py,sha256=4Z_qsLoKLXh2GlQcDdO1tNORJkXqO3Pr2UhZoc2_TmA,12563
-phasorpy/cli.py,sha256=orN_31JOTzIUEfySwTo_Kr24UUzPKdA-DkemsmM8IHk,1977
-phasorpy/color.py,sha256=axzL2b0d_g_6pG1wgHSdbiNtn7wAooYl3t-zaUNOBTE,17313
-phasorpy/components.py,sha256=0ZuUaJllf4c2UFbiTOse5PYXkMLNF8q5VSUxvSgPjy8,10415
-phasorpy/conftest.py,sha256=BywY24LnrOhaTHZIYkVAQ09JmvKZXevNKoshdLeL9nA,949
-phasorpy/cursors.py,sha256=sUZ-9PJ5faJLWewRuENhF7nRJ-drPtW8Ui8YWD6UOw4,15546
-phasorpy/datasets.py,sha256=WnFAvMEAAz4pdl86ZXDzvLHuBAifxbCpVS9f5EAUo3k,14893
-phasorpy/io.py,sha256=ZiZ4GaRHvchRcfRJ77yz9Xy3FkznQECKPfmKb0lbY4s,54250
-phasorpy/phasor.py,sha256=GBk4hkRA2XuNlihLddhs2t_-pUNhkQpBzqAnmXJpJc0,102219
-phasorpy/plot.py,sha256=NfIEn_QynSMNTQGvDrSU6UsIgz15A43VcCLRfsLtnMk,69810
-phasorpy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-phasorpy/utils.py,sha256=lDX4s1u3lHC96A358znupGX2kPwaSodcSanRb_vCNZM,2114
-phasorpy/version.py,sha256=dCgRcJM149CfpwC5ESqQEENkLTbCktaTidh3IYOX7vg,1800
-phasorpy-0.1.dist-info/LICENSE.txt,sha256=bxzmxrql9vHNenjAb0m7dSkLbEQJW9zJi2E0WjkAI68,1104
-phasorpy-0.1.dist-info/METADATA,sha256=rHsAqZBSUA-KnLkCtxUGhXTdnDCSQx8AXq7_eeCIZZs,3479
-phasorpy-0.1.dist-info/WHEEL,sha256=0ZjvOlAkRhiFz0IEm5kQrC9Db9zGCLzyOcgLl0kpzxU,101
-phasorpy-0.1.dist-info/entry_points.txt,sha256=VRhsl3qGiIKwtMraKapmduchTMbdReUi1AoVTe9f3ss,47
-phasorpy-0.1.dist-info/top_level.txt,sha256=4Y0uYzya5R2loleAxZ6s2n53_FysUbgFTfFaU0i9rbo,9
-phasorpy-0.1.dist-info/RECORD,,