phasorpy · bruno-pannunzio · Apr 25, 2024 · Jan 16, 2024 · Feb 2, 2024 · Feb 26, 2024
diff --git a/docs/api/components.rst b/docs/api/components.rst
@@ -0,0 +1,5 @@
+phasorpy.components
+-------------------
+
+.. automodule:: phasorpy.components
+    :members:
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -14,6 +14,7 @@ PhasorPy library version |version|.
 
     phasorpy
     phasor
+    components
     plot
     io
     color

diff --git a/src/phasorpy/_utils.py b/src/phasorpy/_utils.py
@@ -17,6 +17,7 @@
     'phasor_from_polar_scalar',
     'circle_line_intersection',
     'circle_circle_intersection',
+    'project_phasor_to_line',
 ]
 
 import math
@@ -260,3 +261,62 @@ def circle_line_intersection(
             y + (-dd * dx - abs(dy) * rdd) / dr,
         ),
     )
+
+
+def project_phasor_to_line(
+    real: ArrayLike,
+    imag: ArrayLike,
+    real_components: ArrayLike,
+    imag_components: ArrayLike,
+    /,
+    *,
+    clip: bool = True,
+    axis: int = -1,
+) -> tuple[NDArray, NDArray]:
+    """Return projected phasor coordinates to the line that joins two phasors.
+
+    By default, the points are clipped to the line segment between components
+    and the projection is done into the last axis.
+
+    >>> project_phasor_to_line(
+    ...     [0.6, 0.5, 0.4], [0.4, 0.3, 0.2], [0.2, 0.9], [0.4, 0.3]
+    ... )  # doctest: +NUMBER
+    (array([0.592, 0.508, 0.424]), array([0.344, 0.356, 0.368]))
+
+    """
+    real = numpy.copy(real)
+    imag = numpy.copy(imag)
+    real_components = numpy.asarray(real_components)
+    imag_components = numpy.asarray(imag_components)
+    if real_components.shape != (2,):
+        raise ValueError(f'{real_components.shape=} != (2,)')
+    if imag_components.shape != (2,):
+        raise ValueError(f'{imag_components.shape=} != (2,)')
+    first_component_phasor = numpy.array(
+        [real_components[0], imag_components[0]]
+    )
+    second_component_phasor = numpy.array(
+        [real_components[1], imag_components[1]]
+    )
+    total_distance_between_components = math.sqrt(
+        (second_component_phasor[0] - first_component_phasor[0]) ** 2
+        + (second_component_phasor[1] - first_component_phasor[1]) ** 2
+    )
+    if math.isclose(total_distance_between_components, 0, abs_tol=1e-6):
+        raise ValueError('components must have different coordinates')
+    line_vector = second_component_phasor - first_component_phasor
+    line_length = numpy.linalg.norm(line_vector)
+    line_direction = line_vector / line_length
+    projected_points = (
+        numpy.stack((real, imag), axis=axis) - first_component_phasor
+    )
+    projection_lengths = numpy.dot(projected_points, line_direction)
+    if clip:
+        projection_lengths = numpy.clip(projection_lengths, 0, line_length)
+    projected_points = (
+        first_component_phasor
+        + numpy.expand_dims(projection_lengths, axis=axis) * line_direction
+    )
+    projected_points_real = projected_points[..., 0]
+    projected_points_imag = projected_points[..., 1]
+    return projected_points_real, projected_points_imag
diff --git a/src/phasorpy/components.py b/src/phasorpy/components.py
@@ -0,0 +1,116 @@
+"""Component analysis of phasor coordinates.
+
+The ``phasorpy.components`` module provides functions to:
+
+- calculate fractions of two components of known location by projecting to
+  line between components:
+
+  - :py:func:`two_fractions_from_phasor`
+
+- calculate phasor coordinates of second component if only one is
+  known (not implemented)
+
+- calculate fractions of three or four known components by using higher
+  harmonic information (not implemented)
+
+- calculate fractions of two or three components of known location by
+  resolving graphically with histogram (not implemented)
+
+- blindly resolve fractions of n components by using harmonic
+  information (not implemented)
+
+"""
+
+from __future__ import annotations
+
+__all__ = ['two_fractions_from_phasor']
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._typing import Any, ArrayLike, NDArray
+
+import math
+
+import numpy
+
+from ._utils import project_phasor_to_line
+
+
+def two_fractions_from_phasor(
+    real: ArrayLike,
+    imag: ArrayLike,
+    real_components: ArrayLike,
+    imag_components: ArrayLike,
+    /,
+) -> tuple[NDArray[Any], NDArray[Any]]:
+    """Return fractions of two components from phasor coordinates.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    real_components: array_like
+        Real coordinates of the first and second components.
+    imag_components: array_like
+        Imaginary coordinates of the first and second components.
+
+    Returns
+    -------
+    fraction_of_first_component : ndarray
+        Fractions of the first component.
+    fraction_of_second_component : ndarray
+        Fractions of the second component.
+
+    Notes
+    -----
+    For the moment, calculation of fraction of components from different
+    channels or frequencies is not supported. Only one pair of components can
+    be analyzed and will be broadcasted to all channels/frequencies.
+
+    Raises
+    ------
+    ValueError
+        If the real and/or imaginary coordinates of the known components are
+        not of size 2.
+        If the two components have the same coordinates.
+
+    Examples
+    --------
+    >>> two_fractions_from_phasor(
+    ...     [0.6, 0.5, 0.4], [0.4, 0.3, 0.2], [0.2, 0.9], [0.4, 0.3]
+    ... ) # doctest: +NUMBER
+    (array([0.44, 0.56, 0.68]), array([0.56, 0.44, 0.32]))
+
+    """
+    real_components = numpy.asarray(real_components)
+    imag_components = numpy.asarray(imag_components)
+    if real_components.shape != (2,):
+        raise ValueError(f'{real_components.shape=} != (2,)')
+    if imag_components.shape != (2,):
+        raise ValueError(f'{imag_components.shape=} != (2,)')
+    first_component_phasor = numpy.array(
+        [real_components[0], imag_components[0]]
+    )
+    second_component_phasor = numpy.array(
+        [real_components[1], imag_components[1]]
+    )
+    total_distance_between_components = math.sqrt(
+        (second_component_phasor[0] - first_component_phasor[0]) ** 2
+        + (second_component_phasor[1] - first_component_phasor[1]) ** 2
+    )
+    if math.isclose(total_distance_between_components, 0, abs_tol=1e-6):
+        raise ValueError('components must have different coordinates')
+    projected_real, projected_imag = project_phasor_to_line(
+        real, imag, real_components, imag_components
+    )
+    distances_to_first_component = numpy.sqrt(
+        (numpy.array(projected_real) - first_component_phasor[0]) ** 2
+        + (numpy.array(projected_imag) - first_component_phasor[1]) ** 2
+    )
+    fraction_of_second_component = (
+        distances_to_first_component / total_distance_between_components
+    )
+    return 1 - fraction_of_second_component, fraction_of_second_component
diff --git a/src/phasorpy/plot.py b/src/phasorpy/plot.py
@@ -943,19 +943,20 @@ def __init__(
             background_real=background_real,
             background_imag=background_imag,
         )
-        acceptor_trajectory_real, acceptor_trajectory_imag = (
-            phasor_from_fret_acceptor(
-                frequency,
-                donor_lifetime,
-                acceptor_lifetime,
-                fret_efficiency=self._fret_efficiencies,
-                donor_freting=donor_freting,
-                donor_bleedthrough=donor_bleedthrough,
-                acceptor_bleedthrough=acceptor_bleedthrough,
-                acceptor_background=acceptor_background,
-                background_real=background_real,
-                background_imag=background_imag,
-            )
+        (
+            acceptor_trajectory_real,
+            acceptor_trajectory_imag,
+        ) = phasor_from_fret_acceptor(
+            frequency,
+            donor_lifetime,
+            acceptor_lifetime,
+            fret_efficiency=self._fret_efficiencies,
+            donor_freting=donor_freting,
+            donor_bleedthrough=donor_bleedthrough,
+            acceptor_bleedthrough=acceptor_bleedthrough,
+            acceptor_background=acceptor_background,
+            background_real=background_real,
+            background_imag=background_imag,
         )
 
         # add plots
@@ -1259,19 +1260,20 @@ def _on_changed(self, value: Any) -> None:
             background_real=background_real,
             background_imag=background_imag,
         )
-        acceptor_trajectory_real, acceptor_trajectory_imag = (
-            phasor_from_fret_acceptor(
-                frequency,
-                donor_lifetime,
-                acceptor_lifetime,
-                fret_efficiency=self._fret_efficiencies,
-                donor_freting=donor_freting,
-                donor_bleedthrough=donor_bleedthrough,
-                acceptor_bleedthrough=acceptor_bleedthrough,
-                acceptor_background=acceptor_background,
-                background_real=background_real,
-                background_imag=background_imag,
-            )
+        (
+            acceptor_trajectory_real,
+            acceptor_trajectory_imag,
+        ) = phasor_from_fret_acceptor(
+            frequency,
+            donor_lifetime,
+            acceptor_lifetime,
+            fret_efficiency=self._fret_efficiencies,
+            donor_freting=donor_freting,
+            donor_bleedthrough=donor_bleedthrough,
+            acceptor_bleedthrough=acceptor_bleedthrough,
+            acceptor_background=acceptor_background,
+            background_real=background_real,
+            background_imag=background_imag,
         )
 
         if donor_background > 0.0:

diff --git a/tests/test__utils.py b/tests/test__utils.py
@@ -12,6 +12,7 @@
     parse_kwargs,
     phasor_from_polar_scalar,
     phasor_to_polar_scalar,
+    project_phasor_to_line,
     scale_matrix,
     sort_coordinates,
     update_kwargs,
@@ -132,3 +133,36 @@ def test_circle_circle_intersection():
         1e-3,
     )
     assert not circle_line_intersection(0.6, 0.4, 0.2, 0.0, 0.0, 0.6, 0.1)
+
+
+def test_project_phasor_to_line():
+    """Test project_phasor_to_line function."""
+    assert_allclose(
+        project_phasor_to_line(
+            [0.7, 0.5, 0.3], [0.3, 0.4, 0.3], [0.2, 0.9], [0.4, 0.3]
+        ),
+        (
+            [0.704, 0.494, 0.312],
+            [0.328, 0.358, 0.384],
+        ),
+    )
+    assert_allclose(
+        project_phasor_to_line([0.1, 1.0], [0.5, 0.5], [0.2, 0.9], [0.4, 0.3]),
+        ([0.2, 0.9], [0.4, 0.3]),
+    )
+    assert_allclose(
+        project_phasor_to_line(
+            [0.1, 1.0], [0.5, 0.5], [0.2, 0.9], [0.4, 0.3], clip=False
+        ),
+        ([0.088, 0.97], [0.416, 0.29]),
+    )
+    with pytest.raises(ValueError):
+        project_phasor_to_line([0], [0], [0.1, 0.1], [0.2, 0.2])
+    with pytest.raises(ValueError):
+        project_phasor_to_line([0], [0], [0.3], [0.1, 0.2])
+    with pytest.raises(ValueError):
+        project_phasor_to_line([0], [0], [0.1, 0.2], [0.3])
+    with pytest.raises(ValueError):
+        project_phasor_to_line([0], [0], [0.1], [0.3])
+    with pytest.raises(ValueError):
+        project_phasor_to_line([0], [0], [0.1, 0.1, 0, 1], [0.1, 0, 2])
diff --git a/tests/test_components.py b/tests/test_components.py
@@ -0,0 +1,61 @@
+"""Tests for the phasorpy.components module."""
+
+import pytest
+from numpy.testing import assert_allclose
+
+from phasorpy.components import two_fractions_from_phasor
+
+
+def test_two_fractions_from_phasor():
+    """Test two_fractions_from_phasor function."""
+    assert_allclose(
+        two_fractions_from_phasor(
+            [0.2, 0.5, 0.7],
+            [0.2, 0.4, 0.3],
+            [0.0582399, 0.79830002],
+            [0.23419652, 0.40126936],
+        ),
+        (
+            [0.82766281, 0.38389704, 0.15577992],
+            [0.17233719, 0.61610296, 0.84422008],
+        ),
+    )
+    assert_allclose(
+        two_fractions_from_phasor(
+            [0.0, 0.5, 0.9],
+            [0.4, 0.4, 0.6],
+            [0.0582399, 0.79830002],
+            [0.23419652, 0.40126936],
+        ),
+        (
+            [1.0, 0.38389704, 0.0],
+            [0.0, 0.61610296, 1.0],
+        ),
+    )
+    with pytest.raises(ValueError):
+        two_fractions_from_phasor([0], [0], [0.1, 0.1], [0.2, 0.2])
+    with pytest.raises(ValueError):
+        two_fractions_from_phasor([0], [0], [0.3], [0.1, 0.2])
+    with pytest.raises(ValueError):
+        two_fractions_from_phasor([0], [0], [0.1, 0.2], [0.3])
+    with pytest.raises(ValueError):
+        two_fractions_from_phasor([0], [0], [0.1], [0.3])
+    with pytest.raises(ValueError):
+        two_fractions_from_phasor([0], [0], [0.1, 0.1, 0, 1], [0.1, 0, 2])
+
+
+@pytest.mark.xfail
+def test_two_fractions_from_phasor_channels():
+    """Test two_fractions_from_phasor function for multiple channels."""
+    assert_allclose(
+        two_fractions_from_phasor(
+            [[[0.1, 0.2, 0.3]]],
+            [[[0.1, 0.2, 0.3]]],
+            [[0.2, 0.2, 0.2], [0.9, 0.9, 0.9]],
+            [[0.4, 0.4, 0.4], [0.3, 0.3, 0.3]],
+        ),
+        (
+            [[[1.0, 0.96, 0.84]]],
+            [[[0.0, 0.04, 0.16]]],
+        ),
+    )
-Original file line number
+Diff line change
@@ Expand Up / @@ -14,6 +14,7 @@ PhasorPy library version |version|. @@
         phasorpy
         phasor
+        components
         plot
         io
         color
@@ Expand Down @@