phasorpy 0.7__cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

phasorpy/cli.py

@@ -0,0 +1,160 @@
+"""PhasorPy package command line interface.
+
+Invoke the command line application with::
+
+    $ python -m phasorpy --help
+
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._typing import Iterable
+
+import click
+
+from . import __version__
+
+
+@click.group(help='PhasorPy package command line interface.')
+@click.version_option(version=__version__)
+def main() -> int:
+    """PhasorPy command line interface."""
+    return 0
+
+
+@main.command(help='Show runtime versions.')
+@click.option(
+    '--verbose',
+    default=False,
+    is_flag=True,
+    type=click.BOOL,
+    help='Show module paths.',
+)
+def versions(verbose: bool) -> None:
+    """Versions command group."""
+    from .utils import versions
+
+    click.echo(versions(verbose=verbose))
+
+
+@main.command(help='Fetch sample files from remote repositories.')
+@click.argument('files', nargs=-1)
+@click.option(
+    '--hideprogress',
+    default=False,
+    is_flag=True,
+    type=click.BOOL,
+    help='Hide progressbar.',
+)
+def fetch(files: Iterable[str], hideprogress: bool) -> None:
+    """Fetch command group."""
+    from . import datasets
+
+    files = datasets.fetch(
+        *files, return_scalar=False, progressbar=not hideprogress
+    )
+    click.echo(f'Cached at {os.path.commonpath(files)}')
+
+
+@main.command(help='Start interactive FRET phasor plot.')
+@click.option(
+    '--hide',
+    default=False,
+    is_flag=True,
+    type=click.BOOL,
+    help='Do not show interactive plot.',
+)
+def fret(hide: bool) -> None:
+    """FRET command group."""
+    from .plot import PhasorPlotFret
+
+    plot = PhasorPlotFret(
+        frequency=60.0,
+        donor_lifetime=4.2,
+        acceptor_lifetime=3.0,
+        fret_efficiency=0.5,
+        interactive=True,
+    )
+    if not hide:
+        plot.show()
+
+
+@main.command(help='Start interactive lifetime plots.')
+@click.argument(
+    'number_lifetimes',
+    default=2,
+    type=click.IntRange(1, 5),
+    required=False,
+    # help='Number of preconfigured lifetimes.',
+)
+@click.option(
+    '-f',
+    '--frequency',
+    type=float,
+    required=False,
+    help='Laser/modulation frequency in MHz.',
+)
+@click.option(
+    '-l',
+    '--lifetime',
+    # default=(4.0, 1.0),
+    type=float,
+    multiple=True,
+    required=False,
+    help='Lifetime in ns.',
+)
+@click.option(
+    '-a',
+    '--fraction',
+    type=float,
+    multiple=True,
+    required=False,
+    help='Fractional intensity of lifetime.',
+)
+@click.option(
+    '--hide',
+    default=False,
+    is_flag=True,
+    type=click.BOOL,
+    help='Do not show interactive plot.',
+)
+def lifetime(
+    number_lifetimes: int,
+    frequency: float | None,
+    lifetime: tuple[float, ...],
+    fraction: tuple[float, ...],
+    hide: bool,
+) -> None:
+    """Lifetime command group."""
+    from .lifetime import phasor_semicircle, phasor_to_normal_lifetime
+    from .plot import LifetimePlots
+
+    if not lifetime:
+        if number_lifetimes == 2:
+            lifetime = (4.0, 1.0)
+        else:
+            real, imag = phasor_semicircle(number_lifetimes + 2)
+            lifetime = phasor_to_normal_lifetime(
+                real[1:-1], imag[1:-1], frequency if frequency else 80.0
+            )  # type: ignore[assignment]
+
+    plot = LifetimePlots(
+        frequency,
+        lifetime,
+        fraction if len(fraction) > 0 else None,
+        interactive=True,
+    )
+    if not hide:
+        plot.show()
+
+
+if __name__ == '__main__':
+    import sys
+
+    sys.exit(main())  # pylint: disable=no-value-for-parameter

phasorpy/cluster.py

@@ -0,0 +1,200 @@
+"""Cluster phasor coordinates.
+
+The `phasorpy.cluster` module provides functions to:
+
+- fit elliptic clusters to phasor coordinates using a
+  Gaussian Mixture Model (GMM):
+
+  - :py:func:`phasor_cluster_gmm`
+
+"""
+
+from __future__ import annotations
+
+__all__ = ['phasor_cluster_gmm']
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._typing import Any, ArrayLike, Literal
+
+import math
+
+import numpy
+
+
+def phasor_cluster_gmm(
+    real: ArrayLike,
+    imag: ArrayLike,
+    /,
+    *,
+    sigma: float = 2.0,
+    clusters: int = 1,
+    sort: Literal['polar', 'phasor', 'area'] | None = None,
+    **kwargs: Any,
+) -> tuple[
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+]:
+    """Return elliptic clusters in phasor coordinates using GMM.
+
+    Fit a Gaussian Mixture Model (GMM) to the provided phasor coordinates and
+    extract the parameters of ellipses that represent each cluster according
+    to [1]_.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    sigma : float, optional
+        Scaling factor for radii of major and minor axes.
+        Defaults to 2.0, which corresponds to the scaling of eigenvalues for
+        a 95% confidence ellipse.
+    clusters : int, optional
+        Number of Gaussian distributions to fit to phasor coordinates.
+        Defaults to 1.
+    sort : {'polar', 'phasor', 'area'}, optional
+        Sorting method for output clusters. Defaults to 'polar'.
+
+        - 'polar': Sort by polar coordinates (phase, then modulation).
+        - 'phasor': Sort by phasor coordinates (real, then imaginary).
+        - 'area': Sort by inverse area of ellipse (-major * minor).
+
+    **kwargs
+        Additional keyword arguments passed to
+        :py:class:`sklearn.mixture.GaussianMixture`.
+
+        Common options include:
+
+        - covariance_type : {'full', 'tied', 'diag', 'spherical'}
+        - max_iter : int, maximum number of EM iterations
+        - random_state : int, for reproducible results
+
+    Returns
+    -------
+    center_real : tuple of float
+        Real component of ellipse centers.
+    center_imag : tuple of float
+        Imaginary component of ellipse centers.
+    radius_major : tuple of float
+        Major radii of ellipses.
+    radius_minor : tuple of float
+        Minor radii of ellipses.
+    angle : tuple of float
+        Rotation angles of major axes in radians, within range [0, pi].
+
+    References
+    ----------
+    .. [1] Vallmitjana A, Torrado B, and Gratton E.
+      `Phasor-based image segmentation: machine learning clustering techniques
+      <https://doi.org/10.1364/BOE.422766>`_.
+      *Biomed Opt Express*, 12(6): 3410-3422 (2021)
+
+    Examples
+    --------
+    Recover the clusters from a synthetic distribution of phasor coordinates
+    with two clusters:
+
+    >>> real1, imag1 = numpy.random.multivariate_normal(
+    ...     [0.2, 0.3], [[3e-3, 1e-3], [1e-3, 2e-3]], 100
+    ... ).T
+    >>> real2, imag2 = numpy.random.multivariate_normal(
+    ...     [0.4, 0.5], [[2e-3, -1e-3], [-1e-3, 3e-3]], 100
+    ... ).T
+    >>> real = numpy.concatenate([real1, real2])
+    >>> imag = numpy.concatenate([imag1, imag2])
+    >>> center_real, center_imag, radius_major, radius_minor, angle = (
+    ...     phasor_cluster_gmm(real, imag, clusters=2)
+    ... )
+    >>> center_real  # doctest: +SKIP
+    (0.2, 0.4)
+
+    """
+    from sklearn.mixture import GaussianMixture
+
+    coords = numpy.stack([real, imag], axis=-1).reshape(-1, 2)
+
+    valid_data = ~numpy.isnan(coords).any(axis=1)
+    coords = coords[valid_data]
+
+    kwargs.pop('n_components', None)
+
+    gmm = GaussianMixture(n_components=clusters, **kwargs)
+    gmm.fit(coords)
+
+    center_real = []
+    center_imag = []
+    radius_major = []
+    radius_minor = []
+    angle = []
+
+    for i in range(clusters):
+        center_real.append(float(gmm.means_[i, 0]))
+        center_imag.append(float(gmm.means_[i, 1]))
+
+        if gmm.covariance_type == 'full':
+            cov = gmm.covariances_[i]
+        elif gmm.covariance_type == 'tied':
+            cov = gmm.covariances_
+        elif gmm.covariance_type == 'diag':
+            cov = numpy.diag(gmm.covariances_[i])
+        else:  # 'spherical'
+            cov = numpy.eye(2) * gmm.covariances_[i]
+
+        eigenvalues, eigenvectors = numpy.linalg.eigh(cov[:2, :2])
+
+        idx = eigenvalues.argsort()[::-1]
+        eigenvalues = eigenvalues[idx]
+        eigenvectors = eigenvectors[:, idx]
+
+        major_vector = eigenvectors[:, 0]
+        current_angle = math.atan2(major_vector[1], major_vector[0])
+
+        if current_angle < 0:
+            current_angle += math.pi
+
+        angle.append(float(current_angle))
+
+        radius_major.append(sigma * math.sqrt(2 * eigenvalues[0]))
+        radius_minor.append(sigma * math.sqrt(2 * eigenvalues[1]))
+
+    if clusters == 1:
+        argsort = [0]
+    else:
+        if sort is None or sort == 'polar':
+
+            def sort_key(i: int) -> Any:
+                return (
+                    math.atan2(center_imag[i], center_real[i]),
+                    math.hypot(center_real[i], center_imag[i]),
+                )
+
+        elif sort == 'phasor':
+
+            def sort_key(i: int) -> Any:
+                return center_imag[i], center_real[i]
+
+        elif sort == 'area':
+
+            def sort_key(i: int) -> Any:
+                return -radius_major[i] * radius_minor[i]
+
+        else:
+            raise ValueError(
+                f"invalid {sort=!r} != 'phasor', 'polar', or 'area'"
+            )
+
+        argsort = sorted(range(len(center_real)), key=sort_key)
+
+    return (
+        tuple(center_real[i] for i in argsort),
+        tuple(center_imag[i] for i in argsort),
+        tuple(radius_major[i] for i in argsort),
+        tuple(radius_minor[i] for i in argsort),
+        tuple(angle[i] for i in argsort),
+    )