phasorpy 0.6__cp313-cp313-win_arm64.whl → 0.7__cp313-cp313-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,8 +585,15 @@ 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.
@@ -504,6 +607,13 @@ def fetch(
     -------
     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

@@ -68,7 +68,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 +123,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>`_,
@@ -186,7 +184,7 @@ def spectral_vector_denoise(
         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
+        Must be of the same shape as `signal` with `axis` removed and an axis
         containing spectral space appended.
         If None (default), phasor coordinates are calculated at specified
         `harmonic`.
@@ -204,10 +202,11 @@ def spectral_vector_denoise(
     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
+        within a 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.
+        Signal intensity along `axis` below which spectra are excluded from
+        denoising.
     dtype : dtype_like, optional
         Data type of output arrays. Either float32 or float64.
         The default is float64 unless the `signal` is float32.
@@ -225,7 +224,6 @@ def spectral_vector_denoise(
 
     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>`_.
@@ -306,7 +304,7 @@ def spectral_vector_denoise(
         denoised, integrated, signal, spectral_vector, sigma, vmin, num_threads
     )
 
-    denoised = denoised.reshape(shape)
+    denoised = denoised.reshape(shape)  # type: ignore[assignment]
     if axis != -1:
         denoised = numpy.moveaxis(denoised, -1, axis)
     return denoised

phasorpy/io/__init__.py

@@ -8,6 +8,7 @@ The ``phasorpy.io`` module provides functions to:
   - :py:func:`signal_from_lif` - Leica LIF and XLEF
   - :py:func:`signal_from_lsm` - Zeiss LSM
   - :py:func:`signal_from_ptu` - PicoQuant PTU
+  - :py:func:`signal_from_pqbin` - PicoQuant BIN
   - :py:func:`signal_from_sdt` - Becker & Hickl SDT
   - :py:func:`signal_from_fbd` - FLIMbox FBD
   - :py:func:`signal_from_flimlabs_json` - FLIM LABS JSON

phasorpy/io/_flimlabs.py

@@ -67,10 +67,13 @@ def phasor_from_flimlabs_json(
 
         - ``'dims'`` (tuple of str):
           :ref:`Axes codes <axes>` for `mean` image dimensions.
-        - ``'harmonic'`` (int):
-          Harmonic of `real` and `imag`.
+        - ``'samples'`` (int):
+          Number of time bins (always 256).
+        - ``'harmonic'`` (int or list of int):
+          Harmonic(s) of `real` and `imag`.
+          Single int if one harmonic, list if multiple harmonics.
         - ``'frequency'`` (float):
-          Fundamental frequency of time-resolved phasor coordinates in MHz.
+          Laser repetition frequency in MHz.
         - ``'flimlabs_header'`` (dict):
           FLIM LABS file header.
 
@@ -231,27 +234,34 @@ def signal_from_flimlabs_json(
         Index of channel to return.
         By default, return the first channel.
         If None, return all channels.
-    dtype : dtype-like, optional, default: uint16
+    dtype : dtype_like, optional, default: uint16
         Unsigned integer type of TCSPC histogram.
         Increase the bit-depth for high photon counts.
 
     Returns
     -------
     xarray.DataArray
-        TCSPC histogram with :ref:`axes codes <axes>` ``'CYXH'`` and
-        type specified in ``dtype``:
+        TCSPC histogram with :ref:`axes codes <axes>` depending on
+        `channel` parameter:
+
+        - Single channel: axes ``'YXH'``
+        - Multiple channels: axes ``'CYXH'``
+
+        Type specified by ``dtype`` parameter.
 
         - ``coords['H']``: delay-times of histogram bins in ns.
+        - ``coords['C']``: channel indices (if multiple channels).
         - ``attrs['frequency']``: laser repetition frequency in MHz.
         - ``attrs['flimlabs_header']``: FLIM LABS file header.
 
     Raises
     ------
     ValueError
-        File is not a FLIM LABS JSON file containing TCSPC histogram.
-        `dtype` is not an unsigned integer.
+        If file is not a valid JSON file.
+        If file is not a FLIM LABS JSON file containing TCSPC histogram.
+        If `dtype` is not an unsigned integer type.
     IndexError
-        Channel out of range.
+        If `channel` is out of range.
 
     See Also
     --------
@@ -271,7 +281,7 @@ def signal_from_flimlabs_json(
     >>> signal.coords['H'].data
     array(...)
     >>> signal.attrs['frequency']  # doctest: +NUMBER
-    40.00
+    40.0
 
     """
     with open(filename, 'rb') as fh:

phasorpy/io/_leica.py

@@ -140,6 +140,8 @@ def lifetime_from_lif(
 
     Leica image files may contain fluorescence lifetime images and metadata
     from the analysis of FLIM measurements.
+    The lifetimes are average photon arrival times ("Fast FLIM") according to
+    the LAS X FLIM/FCS documentation.
 
     Parameters
     ----------
@@ -151,7 +153,7 @@ def lifetime_from_lif(
     Returns
     -------
     lifetime : ndarray
-        Fluorescence lifetime image in ns.
+        Fast FLIM lifetime image in ns.
     intensity : ndarray
         Fluorescence intensity image.
     stddev : ndarray

phasorpy/io/_ometiff.py

@@ -81,15 +81,14 @@ def phasor_to_ometiff(
     harmonic : int or sequence of int, optional
         Harmonics present in the first dimension of `real` and `imag`, if any.
         Write to image series named 'Phasor harmonic'.
-        It is only needed if harmonics are not starting at and increasing by
-        one.
+        Only needed if harmonics are not starting at and increasing by one.
     dims : sequence of str, optional
         Character codes for `mean` image dimensions.
         By default, the last dimensions are assumed to be 'TZCYX'.
         If harmonics are present in `real` and `imag`, an "other" (``Q``)
         dimension is prepended to axes for those arrays.
         Refer to the OME-TIFF model for allowed axes and their order.
-    dtype : dtype-like, optional
+    dtype : dtype_like, optional
         Floating point data type used to store phasor coordinates.
         The default is ``float32``, which has 6 digits of precision
         and maximizes compatibility with other software.