phasorpy 0.6__cp312-cp312-win_arm64.whl → 0.8__cp312-cp312-win_arm64.whl

phasorpy/{cursors.py → cursor.py}

@@ -1,8 +1,8 @@
 """Select regions of interest (cursors) from phasor coordinates.
 
-The ``phasorpy.cursors`` module provides functions to:
+The ``phasorpy.cursor`` module provides functions to:
 
-- create masks for regions of interests in the phasor space:
+- create masks for regions of interest in the phasor space:
 
   - :py:func:`mask_from_circular_cursor`
   - :py:func:`mask_from_elliptic_cursor`
@@ -26,10 +26,7 @@ __all__ = [
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ._typing import (
-        ArrayLike,
-        NDArray,
-    )
+    from ._typing import ArrayLike, Literal, NDArray
 
 import numpy
 
@@ -80,12 +77,12 @@ def mask_from_circular_cursor(
     ------
     ValueError
         The array shapes of `real` and `imag` do not match.
-        The array shapes of `center_*` or `radius` have more than
-        one dimension.
+        The array shapes of `center_real`, `center_imag`, or `radius` have
+        more than one dimension.
 
     See Also
     --------
-    :ref:`sphx_glr_tutorials_api_phasorpy_cursors.py`
+    :ref:`sphx_glr_tutorials_api_phasorpy_cursor.py`
 
     Examples
     --------
@@ -139,8 +136,7 @@ def mask_from_elliptic_cursor(
     *,
     radius: ArrayLike = 0.05,
     radius_minor: ArrayLike | None = None,
-    angle: ArrayLike | None = None,
-    align_semicircle: bool = False,
+    angle: ArrayLike | Literal['phase', 'semicircle'] | str | None = None,
 ) -> NDArray[numpy.bool_]:
     """Return masks for elliptic cursors of phasor coordinates.
 
@@ -159,21 +155,18 @@ def mask_from_elliptic_cursor(
     radius_minor : array_like, optional, shape (n,)
         Radii of ellipses along semi-minor axis.
         By default, the ellipses are circular.
-    angle : array_like, optional, shape (n,)
-        Rotation angles of semi-major axes of ellipses in radians.
-        By default, the ellipses are automatically oriented depending on
-        `align_semicircle`.
-    align_semicircle : bool, optional
-        Determines orientation of ellipses if `angle` is not provided.
-        If true, align the minor axes of the ellipses with the closest tangent
-        on the universal semicircle, else the unit circle (default).
+    angle : array_like or {'phase', 'semicircle'}, optional
+        Rotation angle of semi-major axis of elliptic cursors in radians.
+        If None or 'phase', align the minor axes of the ellipses with
+        the closest tangent on the unit circle.
+        If 'semicircle', align the ellipses with the universal semicircle.
 
     Returns
     -------
     masks : ndarray
         Boolean array of shape `(n, *real.shape)`.
-        The first dimension is omitted if `center*`, `radius*`, and `angle`
-        are scalars.
+        The first dimension is omitted if `center_real`, `center_imag`,
+        `radius`, `radius_minor`, and `angle` are scalars.
         Values are True if phasor coordinates are inside elliptic cursor,
         else False.
 
@@ -181,12 +174,12 @@ def mask_from_elliptic_cursor(
     ------
     ValueError
         The array shapes of `real` and `imag` do not match.
-        The array shapes of `center*`, `radius*`, or `angle` have more than
-        one dimension.
+        The array shapes of `center_real`, `center_imag`, `radius`,
+        `radius_minor`, or `angle` have more than one dimension.
 
     See Also
     --------
-    :ref:`sphx_glr_tutorials_api_phasorpy_cursors.py`
+    :ref:`sphx_glr_tutorials_api_phasorpy_cursor.py`
 
     Examples
     --------
@@ -220,12 +213,17 @@ def mask_from_elliptic_cursor(
         angle = 0.0
     else:
         radius_b = numpy.asarray(radius_minor)
+
     if angle is None:
-        # TODO: vectorize align_semicircle?
-        if align_semicircle:
+        angle = numpy.arctan2(center_imag, center_real)
+    elif isinstance(angle, str):
+        # TODO: vectorize str type
+        if angle == 'phase':
+            angle = numpy.arctan2(center_imag, center_real)
+        elif angle == 'semicircle':
             angle = numpy.arctan2(center_imag, center_real - 0.5)
         else:
-            angle = numpy.arctan2(center_imag, center_real)
+            raise ValueError(f'invalid {angle=}')
 
     angle_sin = numpy.sin(angle)
     angle_cos = numpy.cos(angle)
@@ -320,10 +318,10 @@ def mask_from_polar_cursor(
 
     See Also
     --------
-    :ref:`sphx_glr_tutorials_api_phasorpy_cursors.py`
+    :ref:`sphx_glr_tutorials_api_phasorpy_cursor.py`
 
-    Example
-    -------
+    Examples
+    --------
     Create mask from a single polar cursor:
 
     >>> mask_from_polar_cursor([0.2, 0.5], [0.4, 0.5], 1.1, 1.2, 0.4, 0.5)
@@ -423,10 +421,10 @@ def pseudo_color(
 
     See Also
     --------
-    :ref:`sphx_glr_tutorials_api_phasorpy_cursors.py`
+    :ref:`sphx_glr_tutorials_api_phasorpy_cursor.py`
 
-    Example
-    -------
+    Examples
+    --------
     Create pseudo-color image from single mask:
 
     >>> pseudo_color([True, False, True])  # doctest: +NUMBER

phasorpy/datasets.py

@@ -2,14 +2,13 @@
 
 The ``phasorpy.datasets`` module provides a :py:func:`fetch` function to
 download data files from remote repositories and cache them in a local
-directory. The cache location can be changed by setting the
-``PHASORPY_DATA_DIR`` environment variable.
+directory.
 
 Datasets from the following repositories are available:
 
-- `PhasorPy tests <https://zenodo.org/record/8417894>`_
-- `LFD Workshop <https://zenodo.org/record/8411056>`_
-- `FLUTE <https://zenodo.org/record/8046636>`_
+- `PhasorPy tests <https://zenodo.org/records/8417894>`_
+- `LFD Workshop <https://zenodo.org/records/8411056>`_
+- `FLUTE <https://zenodo.org/records/8046636>`_
 - `napari-flim-phasor-plotter
   <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
@@ -19,10 +18,18 @@ Datasets from the following repositories are available:
   <https://zenodo.org/records/14026720>`_
 - `Convallaria FLIM dataset in FLIM LABS JSON format
   <https://zenodo.org/records/15007900>`_
+- `FLIM and spectral dataset for GSLab
+  <https://figshare.com/articles/dataset/FLIM_dataset_for_GSLab/28067108>`_
+- `Hyperspectral and FLIM dataset of LAURDAN-stained NIH-3T3 cells
+  <https://zenodo.org/records/16894639>`_
 
 The implementation is based on the `Pooch <https://www.fatiando.org/pooch>`_
 library.
 
+The default cache location is determined by the Pooch library, but can be
+overridden by setting the ``PHASORPY_DATA_DIR`` environment variable to
+a custom directory path.
+
 """
 
 from __future__ import annotations
@@ -397,6 +404,60 @@ FLIMLABS = pooch.create(
     },
 )
 
+FIGSHARE_28067108 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/figshare_28067108'
+    ),
+    env=ENV,
+    registry={
+        '38_Hoechst_Golgi_Mito_Lyso_CellMask_mixture.lsm': (
+            'sha256:'
+            '092ac050edf55e26dcda8cba10122408c6f1b81d19accf07214385d6eebfcf3e'
+        ),
+        '38_Hoechst_Golgi_Mito_Lyso_CellMask_mixture.lsm.zip': (
+            'sha256:'
+            '19298d12b16a58c1de3f532398c154d89df3f2286a1a6ee38a29f1fbefac78fc'
+        ),
+        '40x800fov19LP500p30_4dyes_a1_$CG0T_ch1_h1_h2.R64': (
+            'sha256:'
+            'ad1bae8c3624eecb8927283e333ab5ea3fb864d6c5bb0f155da83c7a8aa40df3'
+        ),
+        '40x800fov19LP500p30_AcO_a4_$CG0T_ch1_h1_h2.R64': (
+            'sha256:'
+            'd1de46652fbed0626ae6ad6334c41baafb0a5ae9e0e15e49221eb540a666d7e7'
+        ),
+        '40x800fov19LP500p30_EtBr_a5_$CG0T_ch1_h1_h2.R64': (
+            'sha256:'
+            '9f4dd2d328877d2b18e064a3fb20d2a5318c833caa5a3cea15bafbf8df5d588a'
+        ),
+        '40x800fov19LP500p30_NucB_a6_$CG0T_ch1_h1_h2.R64': (
+            'sha256:'
+            '74e378ddae84f6532d7ac05f8639feb42541eecb278c842e9a18565c201242f8'
+        ),
+        '40x800fov19LP500p30_RoseBx100_a1_$CG0T_ch1_h1_h2.R64': (
+            'sha256:'
+            '898e0e7e96f8b6c2ee83940f94026dd9006e6fc46bb7e56c62dd22855079e279'
+        ),
+        'Coumarin6.txt': (
+            'sha256:'
+            '6a3ae0f886b512c26cea8bc4b4cd9027ee8d4b7dd437a1eeb9621947e19c3c88'
+        ),
+        'Hoechst_Lyso_Golgi_MitoTracker_CellMask.csv': (
+            'sha256:'
+            '1d000ae6268e6d290ab1cfdf2d31d840f27183cba75b380f116e1049696bb3a4'
+        ),
+        'Mosaic04_10x3_FOV600_z95_32A1_t06_uncalibrated.ref': (
+            'sha256:'
+            '3c23ca9a21a3ef762765fc81591dd0cf9bdaf3e77fa4faa3bf60da69e6ab1127'
+        ),
+        'Mosaic04_10x3_FOV600_z95_32A1_t06_uncalibrated.ref.zip': (
+            'sha256:'
+            '001a472d81b3d348ac4680c73de877ee809c2f229f882ef015225e208a7273fb'
+        ),
+    },
+)
+
 FIGSHARE_22336594 = pooch.create(
     path=pooch.os_cache('phasorpy'),
     base_url=(
@@ -447,6 +508,34 @@ FIGSHARE_22336594_EXPORTED = pooch.create(
     },
 )
 
+ZENODO_16894639 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_16894639'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.16894639'
+    ),
+    env=ENV,
+    registry={
+        '04 NIH3T3LAURDAN8meanspectra.lsm': (
+            'sha256:'
+            '27173be5b57a1a0f40ad6e89df1fd1d6d20bdd1e0a80e469acb47cf0bc103a1c'
+        ),
+        '04NIH3T3_LAURDAN_000$CC0Z.fbd': (
+            'sha256:'
+            '9c8e7d79ef6ce4cce7366c843d34f5b4544f4123fe88307b8df5954a1fe4a799'
+        ),
+        'cumarinech1_780LAURDAN_000$CC0Z.fbd': (
+            'sha256:'
+            '1b7b513680973c79df697b9cefdf2104f5d32346e24c9071336f76a7b82e9313'
+        ),
+        'cumarinech2_780LAURDAN_000$CC0Z.fbd': (
+            'sha256:'
+            '5c9cf9694652cc9c344e67b5650fd49683fa7fdcec39e56ccbf0bdd2f7dadf15'
+        ),
+    },
+)
+
 MISC = pooch.create(
     path=pooch.os_cache('phasorpy'),
     base_url='https://github.com/phasorpy/phasorpy-data/raw/main/misc',
@@ -469,11 +558,18 @@ REPOSITORIES: dict[str, pooch.Pooch] = {
     'zenodo-14976703': ZENODO_14976703,
     'convallaria-fbd': CONVALLARIA_FBD,
     'flimlabs': FLIMLABS,
+    'figshare_28067108': FIGSHARE_28067108,
     'figshare_22336594': FIGSHARE_22336594,
     'figshare_22336594_exported': FIGSHARE_22336594_EXPORTED,
+    'zenodo-16894639': ZENODO_16894639,
     'misc': MISC,
 }
-"""Pooch repositories."""
+"""Dictionary mapping repository names to Pooch repository objects.
+
+Each repository provides access to a specific collection of sample data files
+that can be fetched using the :py:func:`fetch` function.
+
+"""
 
 
 def fetch(
@@ -489,21 +585,35 @@ def fetch(
 
     Parameters
     ----------
-    *args : str or iterable of str, optional
+    *args : str, iterable of str, or pooch.Pooch
         Name(s) of file(s) or repositories to fetch from local storage.
+        Can be:
+
+        - File names (for example, 'simfcs.r64')
+        - Repository names (for example, 'tests', 'flute')
+        - Pooch repository objects
+        - Iterables of the above
+
         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
-        Additional arguments passed to ``pooch.fetch()``.
+        Optional arguments passed to :py:func:`pooch.fetch`.
         For example, ``progressbar=True``.
 
     Returns
     -------
     str or tuple of str
         Absolute path(s) of file(s) in local storage.
+        Returns a single string if only one file and `return_scalar=True`,
+        otherwise returns a tuple of strings.
+
+    Raises
+    ------
+    ValueError
+        If specified file is not found in any repository.
 
     Examples
     --------

phasorpy/experimental.py

@@ -11,26 +11,18 @@ 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 ._typing import Any, NDArray, ArrayLike
 
 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(
@@ -68,7 +60,6 @@ def anscombe_transform(
 
     References
     ----------
-
     .. [1] Anscombe FJ.
        `The transformation of Poisson, binomial and negative-binomial data
        <https://doi.org/10.2307/2332343>`_.
@@ -124,19 +115,18 @@ def anscombe_transform_inverse(
         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}
+          + 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).
+       *IEEE Trans Image Process*, 20(9): 2697-8 (2011)
 
-    .. [3] Makitalo M, and Foi A
+    .. [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>`_,
@@ -156,157 +146,3 @@ def anscombe_transform_inverse(
             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