phasorpy 0.5__tar.gz → 0.6__tar.gz

{phasorpy-0.5/src/phasorpy.egg-info → phasorpy-0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phasorpy
-Version: 0.5
+Version: 0.6
 Summary: Analysis of fluorescence lifetime and hyperspectral images using the phasor approach
 Author: PhasorPy Contributors
 License-Expression: MIT
@@ -66,7 +66,7 @@ PhasorPy is a community-maintained project.
 in the form of bug reports, bug fixes, feature implementations, documentation,
 datasets, and enhancement proposals are welcome.
 
-This software project is supported in part by the
+This software project was supported in part by the
 [Essential Open Source Software for Science (EOSS)](https://chanzuckerberg.com/eoss/)
 program at
 [Chan Zuckerberg Initiative](https://chanzuckerberg.com/).

{phasorpy-0.5 → phasorpy-0.6}/README.md

@@ -15,7 +15,7 @@ PhasorPy is a community-maintained project.
 in the form of bug reports, bug fixes, feature implementations, documentation,
 datasets, and enhancement proposals are welcome.
 
-This software project is supported in part by the
+This software project was supported in part by the
 [Essential Open Source Software for Science (EOSS)](https://chanzuckerberg.com/eoss/)
 program at
 [Chan Zuckerberg Initiative](https://chanzuckerberg.com/).

{phasorpy-0.5 → phasorpy-0.6}/docs/_static/switcher.json

@@ -1,23 +1,23 @@
 [
   {
     "name": "dev",
-    "version": "0.6",
+    "version": "0.7",
     "url": "https://www.phasorpy.org/docs/dev/"
   },
   {
-    "name": "0.5 (stable)",
-    "version": "0.5",
+    "name": "0.6 (stable)",
+    "version": "0.6",
     "url": "https://www.phasorpy.org/docs/stable/",
     "preferred": true
   },
+  {
+    "name": "0.5",
+    "version": "0.5",
+    "url": "https://www.phasorpy.org/docs/v0.5/"
+  },
   {
     "name": "0.4",
     "version": "0.4",
     "url": "https://www.phasorpy.org/docs/v0.4/"
-  },
-  {
-    "name": "0.3",
-    "version": "0.3",
-    "url": "https://www.phasorpy.org/docs/v0.3/"
   }
 ]

phasorpy-0.6/docs/acknowledgments.rst

@@ -0,0 +1,42 @@
+Acknowledgments
+===============
+
+The PhasorPy project was established by the
+`Advanced Bioimaging Unit <https://pasteur.uy/en/units/advanced-bioimaging>`_
+at the University of the Republic and Institut Pasteur de Montevideo and the
+`Laboratory for Fluorescence Dynamics <https://www.lfd.uci.edu>`_
+at the University of California, Irvine.
+
+PhasorPy was inspired by the
+`Globals for Images · SimFCS <https://www.lfd.uci.edu/globals/>`_ software by
+Enrico Gratton.
+
+This software project was supported in part by the
+`Essential Open Source Software for Science (EOSS)
+<https://chanzuckerberg.com/eoss/>`_ program at
+`Chan Zuckerberg Initiative <https://chanzuckerberg.com/>`_
+(grant number 2022-252604, 2022-2024).
+
+.. _contributors:
+
+Contributors
+------------
+
+PhasorPy is developed by `contributors to the PhasorPy repository
+<https://github.com/phasorpy/phasorpy/graphs/contributors>`_
+and
+`members of the PhasorPy organization
+<https://github.com/orgs/phasorpy/people>`_.
+
+User Community
+--------------
+
+Many thanks to the PhasorPy user community for their feedback, bug reports,
+feature suggestions, and data files that have helped improve the library.
+
+Citation
+--------
+
+If PhasorPy contributes to a project that leads to a publication,
+please cite
+`doi: 10.5281/zenodo.13862586 <https://doi.org/10.5281/zenodo.13862586>`_.

phasorpy-0.6/docs/api/experimental.rst

@@ -0,0 +1,5 @@
+phasorpy.experimental
+---------------------
+
+.. automodule:: phasorpy.experimental
+    :members:

{phasorpy-0.5 → phasorpy-0.6}/docs/api/index.rst

@@ -19,6 +19,7 @@ PhasorPy library version |version|.
     plot
     io
     color
+    experimental
     datasets
     utils
     _utils

{phasorpy-0.5 → phasorpy-0.6}/docs/code_of_conduct.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Code of conduct
 ===============
 
@@ -68,9 +70,8 @@ Enforcement
 -----------
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leader responsible for enforcement:
-
-- `Leonel Malacrida <conduct@phasorpy.org>`_
+reported to `<conduct@phasorpy.org>`_ and `PhasorPy organization members
+<https://github.com/orgs/phasorpy/people>`_.
 
 All complaints will be reviewed and investigated promptly and fairly.
 

{phasorpy-0.5 → phasorpy-0.6}/docs/conf.py

@@ -2,9 +2,10 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 # pylint: skip-file
 
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('../src/'))
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(__file__))
 
 # remove the examples header from HTML tutorials
 import sphinx_gallery.gen_rst
@@ -123,8 +124,41 @@ sphinx_gallery_conf = {
     'gallery_dirs': 'tutorials',
     'reference_url': {'phasorpy': None},
     'matplotlib_animations': True,
+    'within_subsection_order': 'conf.TutorialOrder',
 }
 
+
+class TutorialOrder:
+    """Order tutorials in gallery subsections."""
+
+    tutorials = [
+        'introduction',
+        'lifetime_geometry',
+        'lfd_workshop',
+        # api
+        'io',
+        'phasor_from_lifetime',
+        'multi-harmonic',
+        'filtering',
+        'phasorplot',
+        'cursors',
+        'components',
+        'fret',
+        'lifetime_to_signal',
+        'pca',
+        # applications
+        'component_fit',
+        'fret_efficiency',
+        # benchmarks
+        'phasor_from_signal',
+    ]
+
+    def __init__(self, srcdir: str): ...
+
+    def __call__(self, filename: str) -> int:
+        return self.tutorials.index(filename[9:-3])
+
+
 copybutton_prompt_text = (
     r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
 )

{phasorpy-0.5 → phasorpy-0.6}/docs/contributing.rst

@@ -61,9 +61,9 @@ and include the following items in the bug report:
   of::
 
     $ python -m phasorpy versions
-    Python 3.11.4 ...
-    phasorpy 0.1.dev ...
-    numpy 1.25.2
+    Python-3.13.3
+    phasorpy-0.5
+    numpy-2.2.6
     ...
 
 Contribute code or documentation
@@ -289,4 +289,6 @@ and must pass before code or documentation can be accepted.
 Other PhasorPy developers will review the pull request to check and help
 to improve its implementation, documentation, and style.
 
-Pull requests must be approved by a core team member before merging.
+Pull requests must be approved by a
+`PhasorPy organization member <https://github.com/orgs/phasorpy/people>`_
+before merging.

{phasorpy-0.5 → phasorpy-0.6}/docs/index.rst

@@ -62,7 +62,6 @@ Contents
     api/index
     release
     contributing
-    code_of_conduct
     acknowledgments
     license
 

{phasorpy-0.5 → phasorpy-0.6}/docs/phasor_approach.rst

@@ -200,8 +200,8 @@ approach to analyze fluorescence time-resolved or spectral images:
   microscopy written in MATLAB by Alexander Vallmitjana, released under
   the CC BY 4.0 license.
 
-- `AlliGator <https://alligator-distribution.readthedocs.io>`_
-  is a free, closed-source software for fluorescence lifetime image data
+- `AlliGator <https://github.com/smXplorer/AlliGator>`_
+  is an open-source software for fluorescence lifetime image data
   analysis using the phasor approach and standard nonlinear fitting.
   The software is written in LabVIEW for Windows by Xavier Michalet.
 

{phasorpy-0.5 → phasorpy-0.6}/docs/release.rst

@@ -9,6 +9,70 @@ documentation and maintenance changes.
     The PhasorPy library is still under construction. Backwards-incompatible
     changes may occur between revisions.
 
+0.6 (2025.6.22)
+---------------
+
+This is the sixth alpha release of the PhasorPy library.
+It contains several bug fixes, improvements, and breaking changes.
+
+The new ``phasor_component_fit`` function fits fractions of multiple
+components to phasor coordinates.
+The ``phasor_nearest_neighbor`` function returns nearest neighbors in phasor
+coordinates.
+The ``phasor_to_normal_lifetime`` function returns single lifetimes closest
+to phasor coordinates.
+The ``phasor_semicircle_intersect`` function returns intersections of lines
+with the universal semicircle.
+
+The ``LifetimePlots`` class interactively plots lifetimes in the time domain,
+frequency domain, and phasor plot. It can be invoked from the command line
+with ``python -m phasorpy lifetime``.
+
+The ``two_fractions_from_phasor`` and ``graphical_component_analysis``
+functions are renamed to ``phasor_component_fraction`` and
+``phasor_component_graphical``, respectively.
+The ``versions`` function has moved to the ``phasorpy.utils`` namespace.
+The ``spectral_vector_denoise``, ``anscombe_transform``, and
+``anscombe_transform_inverse`` functions have moved to the
+``phasorpy.experimental`` namespace.
+
+Functions in the ``io`` module now return only the first channel by default.
+
+Three new tutorials are added: "Geometrical interpretation of lifetimes",
+"Multi-component fit", and "FRET efficiency image".
+This release supports Python 3.11 to 3.13.
+
+What's Changed
+..............
+
+* Bump version by @cgohlke in https://github.com/phasorpy/phasorpy/pull/221
+* Bump pypa/cibuildwheel from 2.23.2 to 2.23.3 in the github-actions group by @dependabot in https://github.com/phasorpy/phasorpy/pull/223
+* Update description of AlliGator software by @cgohlke in https://github.com/phasorpy/phasorpy/pull/225
+* Cython 3.1.0 is released by @cgohlke in https://github.com/phasorpy/phasorpy/pull/226
+* Add phasor_to_normal_lifetime function by @cgohlke in https://github.com/phasorpy/phasorpy/pull/228
+* Read first channel from files by default by @cgohlke in https://github.com/phasorpy/phasorpy/pull/229
+* Update acknowledgments by @cgohlke in https://github.com/phasorpy/phasorpy/pull/230
+* Use importlib to get package versions by @cgohlke in https://github.com/phasorpy/phasorpy/pull/231
+* Use Windows Server 2022 in GitHub Actions by @cgohlke in https://github.com/phasorpy/phasorpy/pull/232
+* Add tutorial about geometrical interpretation of lifetimes by @cgohlke in https://github.com/phasorpy/phasorpy/pull/233
+* Update reference phasor_from_signal benchmark results by @cgohlke in https://github.com/phasorpy/phasorpy/pull/234
+* Sort clusters returned by phasor_cluster_gmm by @cgohlke in https://github.com/phasorpy/phasorpy/pull/236
+* Reorganize io module by @cgohlke in https://github.com/phasorpy/phasorpy/pull/235
+* Update pre-commit configuration by @cgohlke in https://github.com/phasorpy/phasorpy/pull/237
+* Fix test failing with numpy 2.3.0 by @cgohlke in https://github.com/phasorpy/phasorpy/pull/239
+* Add phasor_component_fit function by @cgohlke in https://github.com/phasorpy/phasorpy/pull/238
+* Rename functions in components module by @cgohlke in https://github.com/phasorpy/phasorpy/pull/240
+* Add phasor_semicircle_intersect function by @cgohlke in https://github.com/phasorpy/phasorpy/pull/241
+* Add private helper functions to mask universal semicircle by @cgohlke in https://github.com/phasorpy/phasorpy/pull/242
+* Add private _distance_from_semicircle function by @cgohlke in https://github.com/phasorpy/phasorpy/pull/244
+* Reorganize plot module by @cgohlke in https://github.com/phasorpy/phasorpy/pull/245
+* Add interactive LifetimePlots class by @cgohlke in https://github.com/phasorpy/phasorpy/pull/247
+* Reorganize version, utils, and experimental modules by @cgohlke in https://github.com/phasorpy/phasorpy/pull/248
+* Add phasor_nearest_neighbor function by @bruno-pannunzio in https://github.com/phasorpy/phasorpy/pull/243
+* Release v0.6 by @cgohlke in https://github.com/phasorpy/phasorpy/pull/244
+
+**Full Changelog**: https://github.com/phasorpy/phasorpy/compare/v0.5...v0.6
+
 0.5 (2025.4.11)
 ---------------
 

{phasorpy-0.5 → phasorpy-0.6}/pyproject.toml

@@ -2,7 +2,7 @@
 requires = [
     "setuptools>=68",
     "numpy",
-    "cython>=3.1.0b1",
+    "cython>=3.1.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -77,7 +77,7 @@ all = [
 zip-safe = false
 
 [tool.setuptools.dynamic]
-version = { attr = "phasorpy.version.__version__" }
+version = { attr = "phasorpy.__version__" }
 
 [tool.setuptools.package-data]
 phasorpy = ["py.typed"]
@@ -151,7 +151,7 @@ minversion = "7"
 log_cli_level = "INFO"
 # filterwarnings = ["error"]  # breaks debugging tests in VSCode (Sept. 2024)
 xfail_strict = true
-addopts = "-rfEXs --strict-config --strict-markers --doctest-modules --doctest-glob=*.py --doctest-glob=*.rst --ignore=src/phasorpy/_io.py"
+addopts = "-rfEXs --strict-config --strict-markers --doctest-modules --doctest-glob=*.py --doctest-glob=*.rst"
 doctest_optionflags = [
     "NORMALIZE_WHITESPACE",
     "ELLIPSIS",

phasorpy-0.6/src/phasorpy/__init__.py

@@ -0,0 +1,9 @@
+"""PhasorPy package."""
+
+from __future__ import annotations
+
+__all__ = ['__version__']
+
+
+__version__ = '0.6'
+"""PhasorPy version string."""

{phasorpy-0.5 → phasorpy-0.6}/src/phasorpy/_phasorpy.pyx

@@ -50,6 +50,12 @@ ctypedef fused uint_t:
     uint32_t
     uint64_t
 
+ctypedef fused int_t:
+    int8_t
+    int16_t
+    int32_t
+    int64_t
+
 ctypedef fused signal_t:
     uint8_t
     uint16_t
@@ -767,6 +773,33 @@ cdef (float_t, float_t) _phasor_from_apparent_lifetime(
     return <float_t> (mod * cos(phi)), <float_t> (mod * sin(phi))
 
 
+@cython.ufunc
+cdef float_t _phasor_to_normal_lifetime(
+    float_t real,
+    float_t imag,
+    float_t omega,
+) noexcept nogil:
+    """Return normal lifetimes from phasor coordinates."""
+    cdef:
+        double taunorm = INFINITY
+        double t
+
+    if isnan(real) or isnan(imag):
+        return <float_t> NAN
+
+    omega *= omega
+    if omega > 0.0:
+        t = 0.5 * (1.0 + cos(atan2(imag, real - 0.5)))
+        if t <= 0.0:
+            taunorm = INFINITY
+        elif t > 1.0:
+            taunorm = NAN
+        else:
+            taunorm = sqrt((1.0 - t) / (omega * t))
+
+    return <float_t> taunorm
+
+
 @cython.ufunc
 cdef (float_t, float_t) _phasor_from_single_lifetime(
     float_t lifetime,
@@ -1204,6 +1237,44 @@ cdef unsigned char _is_inside_stadium(
 _is_near_segment = _is_inside_stadium
 
 
+@cython.ufunc
+cdef unsigned char _is_inside_semicircle(
+    float_t x,  # point
+    float_t y,
+    float_t r,  # distance
+) noexcept nogil:
+    """Return whether point is inside universal semicircle."""
+    if r < 0.0 or isnan(x) or isnan(y):
+        return False
+    if y < -r:
+        return False
+    if y <= 0.0:
+        if x >= 0.0 and x <= 1.0:
+            return True
+        # near endpoints?
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return x * x + y * y <= r * r
+    return hypot(x - 0.5, y) <= r + 0.5
+
+
+@cython.ufunc
+cdef unsigned char _is_near_semicircle(
+    float_t x,  # point
+    float_t y,
+    float_t r,  # distance
+) noexcept nogil:
+    """Return whether point is near universal semicircle."""
+    if r < 0.0 or isnan(x) or isnan(y):
+        return False
+    if y < 0.0:
+        # near endpoints?
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return x * x + y * y <= r * r
+    return fabs(hypot(x - 0.5, y) - 0.5) <= r
+
+
 @cython.ufunc
 cdef unsigned char _is_near_line(
     float_t x,  # point
@@ -1470,6 +1541,22 @@ cdef float_t _distance_from_line(
     return <float_t> hypot(x, y)
 
 
+@cython.ufunc
+cdef float_t _distance_from_semicircle(
+    float_t x,  # point
+    float_t y,
+) noexcept nogil:
+    """Return distance from universal semicircle."""
+    if isnan(x) or isnan(y):
+        return NAN
+    if y < 0.0:
+        # distance to endpoints
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return <float_t> hypot(x, y)
+    return <float_t> fabs(hypot(x - 0.5, y) - 0.5)
+
+
 @cython.ufunc
 cdef (float_t, float_t, float_t) _segment_direction_and_length(
     float_t x0,  # segment start
@@ -1495,7 +1582,7 @@ cdef (float_t, float_t, float_t) _segment_direction_and_length(
 
 
 @cython.ufunc
-cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
+cdef (float_t, float_t, float_t, float_t) _intersect_circle_circle(
     float_t x0,  # circle 0
     float_t y0,
     float_t r0,
@@ -1541,7 +1628,7 @@ cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
 
 
 @cython.ufunc
-cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
+cdef (float_t, float_t, float_t, float_t) _intersect_circle_line(
     float_t x,  # circle
     float_t y,
     float_t r,
@@ -1583,10 +1670,106 @@ cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
     )
 
 
+@cython.ufunc
+cdef (float_t, float_t, float_t, float_t) _intersect_semicircle_line(
+    float_t x0,  # line start
+    float_t y0,
+    float_t x1,  # line end
+    float_t y1,
+) noexcept nogil:
+    """Return coordinates of intersections of line and universal semicircle."""
+    cdef:
+        double dx, dy, dr, dd, rdd
+
+    if isnan(x0) or isnan(x1) or isnan(y0) or isnan(y1):
+        return NAN, NAN, NAN, NAN
+
+    dx = x1 - x0
+    dy = y1 - y0
+    dr = dx * dx + dy * dy
+    dd = (x0 - 0.5) * y1 - (x1 - 0.5) * y0
+    rdd = 0.25 * dr - dd * dd  # discriminant
+    if rdd < 0.0 or dr <= 0.0:
+        # no intersection
+        return NAN, NAN, NAN, NAN
+    rdd = sqrt(rdd)
+    x0 = <float_t> ((dd * dy - copysign(1.0, dy) * dx * rdd) / dr + 0.5)
+    y0 = <float_t> ((-dd * dx - fabs(dy) * rdd) / dr)
+    x1 = <float_t> ((dd * dy + copysign(1.0, dy) * dx * rdd) / dr + 0.5)
+    y1 = <float_t> ((-dd * dx + fabs(dy) * rdd) / dr)
+    if y0 < 0.0:
+        x0 = NAN
+        y0 = NAN
+    if y1 < 0.0:
+        x1 = NAN
+        y1 = NAN
+    return x0, y0, x1, y1
+
+
+def _nearest_neighbor_2d(
+    int_t[::1] indices,
+    const float_t[::1] x0,
+    const float_t[::1] y0,
+    const float_t[::1] x1,
+    const float_t[::1] y1,
+    const float_t distance_max,
+    const int num_threads
+):
+    """Find nearest neighbors in 2D.
+
+    For each point in the first set of arrays (x0, y0) find the nearest point
+    in the second set of arrays (x1, y1) and store the index of the nearest
+    point in the second array in the indices array.
+    If any coordinates are NaN, or the distance to the nearest point
+    is larger than distance_max, the index is set to -1.
+
+    """
+    cdef:
+        ssize_t i, j, index
+        float_t x, y, dmin
+        float_t distance_max_squared = distance_max * distance_max
+
+    if (
+        indices.shape[0] != x0.shape[0]
+        or x0.shape[0] != y0.shape[0]
+        or x1.shape[0] != y1.shape[0]
+    ):
+        raise ValueError('input array size mismatch')
+
+    with nogil, parallel(num_threads=num_threads):
+        for i in prange(x0.shape[0]):
+            x = x0[i]
+            y = y0[i]
+            if isnan(x) or isnan(y):
+                indices[i] = -1
+                continue
+            index = -1
+            dmin = INFINITY
+            for j in range(x1.shape[0]):
+                x = x0[i] - x1[j]
+                y = y0[i] - y1[j]
+                x = x * x + y * y
+                if x < dmin:
+                    dmin = x
+                    index = j
+            indices[i] = -1 if dmin > distance_max_squared else <int_t> index
+
+
 ###############################################################################
 # Blend ufuncs
 
 
+@cython.ufunc
+cdef float_t _blend_and(
+    float_t a,  # base layer
+    float_t b,  # blend layer
+) noexcept nogil:
+    """Return blended layers using `and` mode."""
+    if isnan(a):
+        return NAN
+    return b
+
+
 @cython.ufunc
 cdef float_t _blend_normal(
     float_t a,  # base layer