phasorpy 0.11__tar.gz → 0.12__tar.gz

{phasorpy-0.11/src/phasorpy.egg-info → phasorpy-0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phasorpy
-Version: 0.11
+Version: 0.12
 Summary: Analysis of luminescence lifetime and hyperspectral images using the phasor approach
 Author: PhasorPy Contributors
 License-Expression: MIT
@@ -37,11 +37,12 @@ Requires-Dist: tqdm
 Provides-Extra: all
 Requires-Dist: czifile>=2026.4.11; extra == "all"
 Requires-Dist: fbdfile>=2025.9.18; extra == "all"
-Requires-Dist: lfdfiles>=2026.4.30; extra == "all"
+Requires-Dist: lfdfiles>=2026.6.24; extra == "all"
 Requires-Dist: liffile>=2025.2.10; extra == "all"
 Requires-Dist: ptufile>=2024.9.14; extra == "all"
 Requires-Dist: sdtfile>=2024.5.24; extra == "all"
 Requires-Dist: pawflim>=1.0.4; extra == "all"
+Requires-Dist: brighteyes-mcs-reader>=0.1.0; extra == "all"
 Requires-Dist: imagecodecs==2026.6.6; (sys_platform == "darwin" and platform_machine == "x86_64") and extra == "all"
 Dynamic: license-file
 

{phasorpy-0.11 → phasorpy-0.12}/docs/_static/switcher.json

@@ -1,15 +1,20 @@
 [
   {
     "name": "dev",
-    "version": "0.12",
+    "version": "0.13",
     "url": "https://www.phasorpy.org/docs/dev/"
   },
   {
-    "name": "0.11 (stable)",
-    "version": "0.11",
+    "name": "0.12 (stable)",
+    "version": "0.12",
     "url": "https://www.phasorpy.org/docs/stable/",
     "preferred": true
   },
+  {
+    "name": "0.11",
+    "version": "0.11",
+    "url": "https://www.phasorpy.org/docs/v0.11/"
+  },
   {
     "name": "0.10",
     "version": "0.10",

phasorpy-0.12/docs/about.rst

@@ -0,0 +1,83 @@
+About PhasorPy
+==============
+
+The PhasorPy project's mission is to advance and democratize phasor analysis
+through the open-source PhasorPy library.
+
+.. _funding:
+
+Founding and funding
+--------------------
+
+The PhasorPy project was established in 2023 by the
+`Advanced Bioimaging Unit <https://www.uba.uy>`_
+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.
+
+The project was supported 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).
+
+Project goals
+-------------
+
+The original goals were to create an open-source Python library based on
+sound software engineering principles, establish a community of users
+and developers, and reimplement core phasor-based functionality of the
+discontinued closed-source
+`Globals for Images - SimFCS <https://www.lfd.uci.edu/globals/>`_
+software by Enrico Gratton.
+
+The current goals are to improve community sustainability and to advance the
+PhasorPy library toward a stable, extensible platform that supports
+large-scale automated workflows, AI-assisted analysis, and robust integration
+with the scientific Python ecosystem, while continuing to serve as a reliable
+base for graphical applications and training resources.
+
+.. _governance:
+
+.. _contributors:
+
+Governance and contributors
+---------------------------
+
+PhasorPy is developed collaboratively by
+`contributors to the PhasorPy repository
+<https://github.com/phasorpy/phasorpy/graphs/contributors?all=1>`_
+and governed by
+`members of the PhasorPy organization
+<https://github.com/orgs/phasorpy/people>`_.
+
+Technical direction is developed through open discussion and
+consensus-building in issues, pull requests, and community meetings.
+Members of the PhasorPy organization make final technical and release
+decisions.
+
+Infrastructure hosting, funded activities, and institutional partnerships are
+coordinated through the `Advanced Bioimaging Unit <https://www.uba.uy>`__.
+
+See the :doc:`Contributing guide <contributing>` to get involved.
+
+Acknowledgments
+---------------
+
+We thank the PhasorPy user community for feedback, bug reports, feature
+suggestions, and data files that have helped improve the library.
+
+We acknowledge the open-source scientific Python ecosystem that PhasorPy
+builds on, including Python, NumPy, SciPy, Matplotlib, and scikit-learn,
+the microscopy file-format stack (including tifffile, ptufile, and related
+tools), and the documentation toolchain based on Sphinx and Sphinx-Gallery.
+
+We also acknowledge GitHub for providing a platform for collaborative
+development and hosting documentation, PyPI and conda-forge for package
+distribution, and Zenodo for hosting sample data.
+
+Citation
+--------
+
+If PhasorPy contributes to research that leads to a publication, please cite
+`doi: 10.5281/zenodo.13862586 <https://doi.org/10.5281/zenodo.13862586>`_.

phasorpy-0.12/docs/acknowledgments.rst

@@ -0,0 +1,3 @@
+:orphan:
+
+See :doc:`about`

{phasorpy-0.11 → phasorpy-0.12}/docs/conf.py

@@ -47,7 +47,6 @@ extensions = [
     # don't enable intersphinx since tutorials are getting littered with links
     # 'sphinx.ext.intersphinx',
     # 'numpydoc',
-    'sphinx_inline_tabs',
     'sphinx_copybutton',
     'sphinx_click',
     'sphinx_issues',
@@ -148,9 +147,6 @@ sphinx_gallery_conf = {
     # 'backreferences_dir': None,
 }
 
-# TODO: remove MathJax 3 link once scroll bar issue is resolved
-mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'
-
 
 class TutorialOrder:
     """Order tutorials in gallery subsections."""

{phasorpy-0.11 → phasorpy-0.12}/docs/contributing.rst

@@ -61,9 +61,9 @@ and include the following items in the bug report:
   output of::
 
     $ python -m phasorpy versions
-    Python-3.14.1
-    phasorpy-0.8
-    numpy-2.3.5
+    Python-3.14.6
+    phasorpy-0.11
+    numpy-2.5.1
     ...
 
 Contribute code or documentation
@@ -88,6 +88,30 @@ The PhasorPy project loosely follows the
 `pyOpenSci <https://www.pyopensci.org/python-package-guide/>`_
 development guidelines.
 
+The PhasorPy project follows and adapts the `SciPy AI policy
+<https://scipy.github.io/devdocs/dev/conduct/ai_policy.html>`_.
+
+Copyright
+.........
+
+All code in PhasorPy is released under the :doc:`license`.
+Contributors license their code under the same license when submitting it
+to PhasorPy's version control repository.
+That means contributors must have the right to submit the code to PhasorPy
+and must comply with the terms of any MIT-compatible open-source license
+associated with submitted code.
+
+Accountability
+..............
+
+Contributors are responsible for all code submitted to the PhasorPy repository.
+They must understand it and be able to explain it, regardless of whether it
+was manually written or AI-generated.
+
+Contributors must disclose whether AI has been used to assist in the
+development of code or documentation. If so, specify the tool(s) used,
+how they were used, and which code or text is AI-generated.
+
 Fork the repository
 ...................
 
@@ -195,7 +219,7 @@ must conform to certain styles, which can be checked and applied with
 
     $ python -m pre_commit run --all-files
 
-User-facing classes and functions must use
+Tests and user-facing classes and functions must use
 `type hints <https://peps.python.org/pep-0484/>`_
 and pass verification with the
 `MyPy <https://mypy.readthedocs.io>`_

{phasorpy-0.11 → phasorpy-0.12}/docs/index.rst

@@ -19,14 +19,14 @@ classes of the library.
 The :doc:`release/index` list recent bug fixes, feature enhancements,
 documentation, and maintenance changes.
 
-The :doc:`contributing` explains how to get support, report bugs,
-submit fixes, and improve the documentation.
+The :doc:`Contributing guide <contributing>` explains how to get support,
+report bugs, submit fixes, and improve the documentation.
 
 The :doc:`code_of_conduct` applies to everyone participating in the
 PhasorPy community.
 
-The :doc:`acknowledgments` list individuals and organizations that
-contributed to the development of PhasorPy.
+The :doc:`About <about>` page describes the project's history, goals,
+funding, and governance.
 
 The PhasorPy library and documentation are released under the permissive
 :doc:`license`.
@@ -62,8 +62,8 @@ Contents
     api/index
     release/index
     contributing
-    acknowledgments
     license
+    about
 
 Indices and tables
 ------------------

{phasorpy-0.11 → phasorpy-0.12}/docs/phasor_approach.rst

@@ -148,6 +148,7 @@ luminescence time-resolved or spectral images:
 
    * - **Library**
      - :ref:`PhasorPy <phasorpy>`,
+       :ref:`PyFLI <pyfli>`,
        :ref:`tttrlib <tttrlib>`,
        :ref:`FLIMLib <flimlib>`:sup:`2`,
        :ref:`BrightEyes <brighteyes>`:sup:`2`,
@@ -156,10 +157,12 @@ luminescence time-resolved or spectral images:
    * - **Desktop**
      - :ref:`SimFCS <simfcs>`:sup:`3,4`,
        :ref:`FLIM Playground <flim_playground>`:sup:`1`,
+       :ref:`FLIMKit <flimkit>`:sup:`1`,
        :ref:`FLUTE <flute>`,
        :ref:`FLIMPA <flimpa>`,
        :ref:`GSLab <gslab>`,
        :ref:`AlliGator <alligator>`,
+       :ref:`Spectral Phasors Analysis <spectral_phasors_analysis>`:sup:`2`,
        :ref:`HySP <hysp>`:sup:`3,4`,
        :ref:`FlimFast <flimfast>`:sup:`3,4`
    * - **Napari**
@@ -316,6 +319,22 @@ Details:
   The software is written in Python, is web deployable, and is distributed
   under the MIT license.
 
+-
+  .. _flimkit:
+
+  `FLIMKit <https://github.com/alex1075/FLIMKit>`__
+  is an open-source Python toolkit focused on PTU-based FLIM data. It includes
+  a phasor analysis workflow and is distributed under the MIT license.
+
+-
+  .. _pyfli:
+
+  `PyFLI <https://github.com/vkp217/pyfli-pkg>`__
+  is an open-source Python platform for Fluorescence Lifetime Imaging
+  (FLI) data simulation, processing and visualization, including phasor
+  analysis.
+  The library is distributed under the CC BY-NC-ND 4.0 license.
+
 -
   .. _flim_tools:
 
@@ -333,6 +352,14 @@ Details:
   and correcting phasor coordinates. The library is distributed under the
   BSD license.
 
+-
+  .. _spectral_phasors_analysis:
+
+  `Spectral Phasors Analysis <https://github.com/DBP008/spectral-phasors-analysis>`__
+  is a Python application to explore spectral phasors through simulations and
+  analyze experimental data. The software is distributed under the AGPL-3.0
+  license.
+
 -
   .. _phasor_analysis:
 

{phasorpy-0.11 → phasorpy-0.12}/pyproject.toml

@@ -60,11 +60,12 @@ all = [
     # sync with [dependency-groups.optional]
     "czifile>=2026.4.11",
     "fbdfile>=2025.9.18",
-    "lfdfiles>=2026.4.30",
+    "lfdfiles>=2026.6.24",
     "liffile>=2025.2.10",
     "ptufile>=2024.9.14",
     "sdtfile>=2024.5.24",
     "pawflim>=1.0.4",
+    "brighteyes-mcs-reader>=0.1.0",
     "imagecodecs==2026.6.6; sys_platform == 'darwin' and platform_machine == 'x86_64'",
     # "mkl-fft>=2.1.1",
 ]
@@ -87,11 +88,12 @@ optional = [
     # optional runtime dependencies; sync with [project.optional-dependencies]
     "czifile>=2026.4.11",
     "fbdfile>=2025.9.18",
-    "lfdfiles>=2026.4.30",
+    "lfdfiles>=2026.6.24",
     "liffile>=2025.2.10",
     "ptufile>=2024.9.14",
     "sdtfile>=2024.5.24",
     "pawflim>=1.0.4",
+    "brighteyes-mcs-reader>=0.1.0",
     "imagecodecs==2026.6.6; sys_platform == 'darwin' and platform_machine == 'x86_64'",
 ]
 minimal = [
@@ -106,11 +108,12 @@ minimal = [
     # optional
     "czifile==2026.4.11; python_version == \"3.12\"",
     "fbdfile==2025.9.18; python_version == \"3.12\"",
-    "lfdfiles==2026.4.30; python_version == \"3.12\"",
+    "lfdfiles==2026.6.24; python_version == \"3.12\"",
     "liffile==2025.2.10; python_version == \"3.12\"",
     "ptufile==2024.9.14; python_version == \"3.12\"",
     "sdtfile==2024.5.24; python_version == \"3.12\"",
     "pawflim==1.0.4; python_version == \"3.12\"",
+    "brighteyes-mcs-reader==0.1.0; python_version == \"3.12\""
 ]
 build = [
     # build requirements
@@ -140,7 +143,6 @@ docs = [
     "sphinx",
     "sphinx-copybutton",
     "sphinx-design",
-    "sphinx-inline-tabs",
     "sphinx-issues",
     "sphinx_click",
     "sphinx_gallery",
@@ -260,7 +262,7 @@ typing-modules = ["_typing"]
 "__init__.py" = ["F401", "F403"]
 "conftest.py" = ["ARG001"]
 "setup.py" = ["T201"]
-"tests/*" = ["ANN", "D", "INP001", "PT011", "SLF001", "S101"]
+"tests/*" = ["INP001", "PT011", "SLF001", "TC001"]
 "tools/*" = ["ANN", "INP001", "T201"]
 "tutorials/*" = ["ANN", "D", "E402", "INP001", "T201", "S101", "ERA001"]
 "docs/conf.py" = ["A001", "ANN204", "D102", "E402", "INP001", "RUF012"]
@@ -332,7 +334,7 @@ ND2 = "ND2"
 OIF = "OIF"
 
 [tool.mypy]
-packages = ["phasorpy"]
+packages = ["phasorpy", "tests"]
 mypy_path = "$MYPY_CONFIG_FILE_DIR/src"
 plugins = []
 enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
@@ -341,11 +343,13 @@ warn_unreachable = true
 
 [[tool.mypy.overrides]]
 module = [
+    "_conftest",
     "phasorpy._phasorpy",
     "pooch.*",
     "scipy.*",
     "mkl_fft.*",
     "sklearn.*",
+    "h5py.*",
 ]
 ignore_missing_imports = true
 
@@ -403,21 +407,22 @@ norecursedirs = [
 
 [tool.cibuildwheel]
 skip = [
-    "cp38*",
     "cp39*",
     "cp310*",
     "cp311*",
     "cp313*",
     "cp314-*",
+    "cp315*",
     "*musllinux*",
     "*i686*",
     "*ppc64le*",
     "*s390x*",
 ]
 test-command = "pytest {project}/tests"
-test-skip = ["cp314t*"]
+test-skip = ["cp314t*", "cp315t*"]
 test-requires = [
     # sync with [dependency-groups.optional]
+    "brighteyes-mcs-reader",
     "czifile>=2026.4.11",
     "fbdfile",
     "lfdfiles",

{phasorpy-0.11 → phasorpy-0.12}/src/phasorpy/__init__.py

@@ -5,5 +5,5 @@ from __future__ import annotations
 __all__ = ['__version__']
 
 
-__version__ = '0.11'
+__version__ = '0.12'
 """PhasorPy version string."""

{phasorpy-0.11 → phasorpy-0.12}/src/phasorpy/_phasorpy.pyx

@@ -413,6 +413,7 @@ def _gaussian_signal(
     float_t[::1] signal,
     const double mean,
     const double stdev,
+    ssize_t folds = -1
 ):
     """Return normal distribution, wrapped around at borders.
 
@@ -420,21 +421,28 @@ def _gaussian_signal(
     ----------
     signal : memoryview of `float32` or `float64`
         Writable buffer where calculated signal samples are stored.
+        Must be initialized.
     mean : float
         Mean of normal distribution.
     stdev : float
         Standard deviation of normal distribution.
+    folds : int, optional, default=-1
+        Number of times to wrap around distribution at borders.
+        If negative (default), it is automatically calculated based on
+        `stdev` and the size of `signal` (number of samples).
 
     """
     cdef:
         ssize_t samples = signal.shape[0]
-        ssize_t folds = 1  # TODO: calculate from stddev and samples
         ssize_t i
         double t, c
 
     if samples < 1:
         return
 
+    if folds < 0:
+        folds = <ssize_t> (-floor(-6.0 * stdev / <double> samples))
+
     with nogil:
         if isnan(mean) or isnan(stdev) or stdev <= 0.0:
             for i in range(samples):
@@ -2748,7 +2756,7 @@ def _median_filter_2d(
         ssize_t rows = image.shape[0]
         ssize_t cols = image.shape[1]
         ssize_t k = kernel_size // 2
-        ssize_t i, j, r, di, dj, ki, kj, valid_count
+        ssize_t i, j, _r, di, dj, ki, kj, valid_count
         float_t element
         float_t* kernel
 
@@ -2766,7 +2774,7 @@ def _median_filter_2d(
             with gil:
                 raise MemoryError('failed to allocate kernel')
 
-        for r in range(repeat):
+        for _r in range(repeat):
             for i in prange(rows):
                 for j in range(cols):
                     if isnan(image[i, j]):
@@ -2846,7 +2854,7 @@ def _flimlabs_mean(
     cdef:
         float_t[::] mean_
         list channels, pixels
-        ssize_t c, i, h, count
+        ssize_t c, i, _h, count
         double sum
 
     if channel < 0:
@@ -2856,7 +2864,7 @@ def _flimlabs_mean(
             i = 0
             for pixels in channels:
                 sum = 0.0
-                for h, count in pixels:
+                for _h, count in pixels:
                     sum += <double> count
                 mean_[i] = <float_t> (sum / 256.0)
                 i += 1
@@ -2866,7 +2874,77 @@ def _flimlabs_mean(
         mean_ = mean[0]
         for pixels in data[channel]:
             sum = 0.0
-            for h, count in pixels:
+            for _h, count in pixels:
                 sum += <double> count
             mean_[i] = <float_t> (sum / 256.0)
             i += 1
+
+
+###############################################################################
+# Synthesize spectra
+
+
+@cython.ufunc
+cdef float_t _signal_from_dho(
+    float_t wavelength,
+    float_t origin,
+    float_t sigma,
+    float_t hr_factor,
+    float_t vib_frequency,
+    float_t scale,
+    float_t offset,
+    int absorption,
+) noexcept nogil:
+    """Return DHO model intensity for emission or absorption.
+
+    Using the area-normalized Displaced Harmonic Oscillator (DHO) model.
+
+    """
+    cdef:
+        double wavenumber, gaussian, nu_0, nu_n, poisson_factor
+        double intensity_nu = 0.0
+        double weight = 1.0  # w[0] = hr_factor^0 / 0! = 1
+        double sign = 1.0 if absorption else -1.0
+        ssize_t max_n = 6  # N=5 in math notation; error <1% for S<=1.65
+        ssize_t n
+
+    if (
+        wavelength <= 0.0
+        or origin <= 0.0
+        or sigma <= 0.0
+        or hr_factor < 0.0
+        or vib_frequency < 0.0
+    ):
+        return <float_t> NAN
+
+    # convert to wavenumber domain (cm^-1)
+    wavenumber = 1e7 / wavelength
+    nu_0 = 1e7 / origin  # 0->0 electronic origin
+
+    # Poisson PMF normalization factor exp(-S); sum of weights over all n is ~1
+    poisson_factor = exp(-hr_factor)
+
+    for n in range(max_n):
+        if n > 0:
+            weight = weight * hr_factor / n  # Iterative w[n] = hr_factor^n/n!
+
+        # In emission, vibronic sidebands go to lower energy
+        #   (red-shifted) -> subtract frequency
+        # In absorption, sidebands go to HIGHER energy
+        #   (blue-shifted) -> add frequency
+        nu_n = nu_0 + sign * n * vib_frequency
+
+        gaussian = exp(
+            -((wavenumber - nu_n) * (wavenumber - nu_n))
+            / (2.0 * sigma * sigma)
+        )
+
+        intensity_nu += weight * poisson_factor * gaussian
+
+    # normalize the Gaussian peak heights in wavenumber space,
+    # transform coordinates to wavelength space via the Jacobian: 1e7/lambda^2,
+    # and apply affine transformation
+    return <float_t> (
+        (intensity_nu / (sigma * sqrt(2.0 * M_PI)))
+        * (1e7 / (wavelength * wavelength))
+    ) * scale + offset

{phasorpy-0.11 → phasorpy-0.12}/src/phasorpy/cli.py

@@ -156,6 +156,129 @@ def lifetime(
         plot.show()
 
 
+@main.command(help='Start interactive spectral plots.')
+@click.argument(
+    'number_spectra',
+    default=1,
+    type=click.IntRange(1, 4),
+    required=False,
+)
+@click.option(
+    '-o',
+    '--origin',
+    type=float,
+    multiple=True,
+    required=False,
+    help='Origin wavelength.',
+)
+@click.option(
+    '-s',
+    '--sigma',
+    type=float,
+    multiple=True,
+    required=False,
+    help='Spectral broadening factor.',
+)
+@click.option(
+    '-a',
+    '--fraction',
+    type=float,
+    multiple=True,
+    required=False,
+    help='Fractional intensity of component.',
+)
+@click.option(
+    '--hr-factor',
+    type=float,
+    default=0.4,
+    show_default=True,
+    help='Huang-Rhys factor.',
+)
+@click.option(
+    '--vib-frequency',
+    type=float,
+    default=1200.0,
+    show_default=True,
+    help='Vibrational frequency.',
+)
+@click.option(
+    '--wavelength-min',
+    type=float,
+    default=450.0,
+    show_default=True,
+    help='Minimum wavelength to display.',
+)
+@click.option(
+    '--wavelength-max',
+    type=float,
+    default=650.0,
+    show_default=True,
+    help='Maximum wavelength to display.',
+)
+@click.option(
+    '--samples',
+    type=int,
+    default=128,
+    show_default=True,
+    help='Number of wavelength samples.',
+)
+@click.option(
+    '--dho',
+    default=False,
+    is_flag=True,
+    type=click.BOOL,
+    help='Use Displaced Harmonic Oscillator model.',
+)
+@click.option(
+    '--hide',
+    default=False,
+    is_flag=True,
+    type=click.BOOL,
+    help='Do not show interactive plot.',
+)
+def spectral(
+    *,
+    number_spectra: int,
+    origin: tuple[float, ...],
+    sigma: tuple[float, ...],
+    fraction: tuple[float, ...],
+    hr_factor: float,
+    vib_frequency: float,
+    wavelength_min: float,
+    wavelength_max: float,
+    samples: int,
+    dho: bool,
+    hide: bool,
+) -> None:
+    """Start interactive spectral plots."""
+    from .plot import SpectralPlots
+
+    _default_origins = {
+        1: (518.0,),
+        2: (490.0, 570.0),
+        3: (480.0, 530.0, 590.0),
+        4: (470.0, 510.0, 560.0, 620.0),
+    }
+
+    if not origin:
+        n = min(number_spectra, 2 if dho else 4)
+        origin = _default_origins[n]
+
+    plot = SpectralPlots(
+        origin,
+        sigma or None,
+        fraction if len(fraction) > 0 else None,
+        hr_factor=hr_factor,
+        vib_frequency=vib_frequency,
+        wavelength_range=(wavelength_min, wavelength_max),
+        samples=samples,
+        dho=dho,
+        interactive=True,
+    )
+    if not hide:
+        plot.show()
+
+
 if __name__ == '__main__':
     import sys