phasorpy.component

Analyze components in phasor coordinates.

The phasorpy.component module provides functions to:

• calculate fractions of two known components by projecting onto the line between the components (phasor_component_fraction())

• calculate phasor coordinates of a second component if only one is known (not implemented yet)

• calculate fractions of multiple known components by using higher-harmonic information (phasor_component_fit())

• calculate fractions of two or three known components by resolving graphically with a histogram (phasor_component_graphical())

• calculate mean value coordinates of phasors with respect to three or more components (phasor_component_mvc())

• blindly resolve fractions of multiple components by using harmonic information (phasor_component_blind(), not implemented yet)

• calculate phasor coordinates from fractional intensities of components (phasor_from_component())

• calculate absolute concentrations of two components from phasor coordinates and calibration (phasor_component_concentration())

phasorpy.component.phasor_component_concentration(mean, real, imag, component_real, component_imag, /, reference_mean, reference_real, reference_imag, reference_concentration, *, brightness_ratio=None)

Return concentrations of two components from phasor coordinates.

Calculate the absolute concentration of the first component and, optionally, the second component of a two-component system from phasor coordinates, using an intensity calibration based on a solution of known concentration according to [4].

The algorithm uses geometric line-line intersections in phasor space to determine fractional contributions and scale them to absolute concentrations.

Parameters:

• mean (array_like) – Mean intensity of phasor coordinates.

• real (array_like) – Real component of phasor coordinates.

• imag (array_like) – Imaginary component of phasor coordinates.

• component_real (array_like, shape (2,)) – Real coordinates of the two components. The first component is the calibrated component, whose pure solution is used as the reference;

• component_imag (array_like, shape (2,)) – Imaginary coordinates of the two components.

• reference_mean (float) – Mean fluorescence intensity of calibration solution. The calibration solution must contain only the first component at a known concentration.

• reference_real (float) – Real coordinate of calibration solution phasor.

• reference_imag (float) – Imaginary coordinate of calibration solution phasor.

• reference_concentration (float) – Known concentration of calibration solution. Same units as the returned concentrations.

• brightness_ratio (float, optional) – Ratio of molecular brightness of second to first component. If provided, the second-component concentration is also returned.

Returns:

• conc_first (ndarray) – Absolute concentration of first component.

• conc_second (ndarray) – Absolute concentration of second component. Only returned when brightness_ratio is provided.

Raises:

ValueError – If component_real values are equal (degenerate component line). If component_real or component_imag do not have shape (2,). If reference_mean is zero (cannot normalize). If reference_concentration is not positive. If brightness_ratio is not positive.

See also

phasorpy.component.phasor_component_fraction, NADH absolute concentration

Notes

The algorithm is based on the concandfrac procedure from SimFCS and the method described in [4]. The implementation has been validated against the published cellular NADH concentration, but no independent theoretical or cross-instrument validation has been performed. Users applying the method to other analytes or instrument platforms are encouraged to verify results against known standards.

The calibration solution must contain only component 0 (no component 1) at a precisely known concentration (reference_concentration). It must be acquired under identical instrument settings as the sample (same laser power, detector gain, acquisition time, and objective), because the algorithm relates pixel mean intensities directly to the calibration mean intensity. The mean intensity of the calibration solution should be comparable to the typical pixel mean intensities of the sample.

The calibration factor \(k\) relates the component-0 phasor position to an absolute concentration:

\[k = c_\text{ref} \cdot \frac{g_0 - g_\text{cal}} {g_\text{cal}}\]

where \(g_0\) is the real coordinate of the component-0 phasor, \(g_\text{cal}\) is the intersection of the line from \(g_0\) through the origin with the line connecting the component-1 phasor scaled by \(m=0.5\) and the calibration phasor scaled by \(m=0.5\), and \(c_\text{ref}\) is the reference concentration.

For each pixel, a normalized intensity is computed:

\[m = \frac{I}{I_\text{ref} + I}\]

where \(I\) is the pixel mean intensity and \(I_\text{ref} = 2 \cdot \text{reference_mean}\) is twice the fluorescence-only mean intensity of the calibration solution.

The component-0 concentration is then:

\[c_0 = \left| \frac{g_\text{pix} \cdot k}{g_0 - g_\text{pix}} \right|\]

where \(g_\text{pix}\) is the real coordinate of the intersection of the line from \(g_0\) through the origin with the line from the intensity-scaled component-1 phasor \(g_1 \cdot m\) through the measured phasor. Note: The absolute value in the \(c_0\) formula is required for phasor geometries where \(g_\text{pix}\) falls outside the interval \([0, g_0]\) (as is typical for NADH), but has not been validated for other analytes or geometries.

When brightness_ratio \(\varepsilon = \varepsilon_1 / \varepsilon_0\) is provided, the component-0 fraction \(f_0\) at each pixel is determined by the intersection \(g_\text{frac}\) of the line from the origin through the measured phasor with the component line:

\[f_0 = \frac{g_1 - g_\text{frac}} {g_1 - g_0}\]

The component-1 concentration and total concentration are then:

\[ \begin{align}\begin{aligned}c_1 &= c_0 \cdot \frac{1 - f_0}{f_0 \cdot \varepsilon}\\c_\text{total} &= c_0 + c_1\end{aligned}\end{align} \]

References

[4] (1,2)

Ma N, Digman M A, Malacrida L, and Gratton E. Measurements of absolute concentrations of NADH in cells using the phasor FLIM method. Biomed Opt Express, 7(7): 2441-2452 (2016)

Examples

Verify the calibration self-consistency: when mean = 2 * reference_mean (intensity modulation m = 0.5) and the pixel phasor equals the reference phasor scaled by 0.5, the result equals reference_concentration:

>>> phasor_component_concentration(
...     1000.0, 0.4, 0.05, [0.6, 0.2], [0.1, 0.4], 500.0, 0.8, 0.1, 100.0
... )
array(100)

phasorpy.component.phasor_component_fit(mean, real, imag, component_real, component_imag, /, **kwargs)

Return fractions of multiple components from phasor coordinates.

Component fractions are obtained from the least-squares solution of a linear matrix equation that relates phasor coordinates from one or multiple harmonics to component fractions according to [2].

Up to 2 * number harmonics + 1 components can be fitted to multi-harmonic phasor coordinates, that is up to three components for single harmonic phasor coordinates.

Parameters:

• mean (array_like) – Intensity of phasor coordinates.

• real (array_like) – Real component of phasor coordinates. Harmonics, if any, must be in the first dimension.

• imag (array_like) – Imaginary component of phasor coordinates. Harmonics, if any, must be in the first dimension.

• component_real (array_like) – Real coordinates of components. Must be one or two-dimensional with harmonics in the first dimension.

• component_imag (array_like) – Imaginary coordinates of components. Must be one or two-dimensional with harmonics in the first dimension.

• **kwargs – Optional arguments passed to scipy.linalg.lstsq().

Returns:

fractions – Component fractions. Fractions may not exactly add up to 1.0.

Return type:

ndarray

Raises:

ValueError – If the array shapes of real and imag do not match. If the array shapes of component_real and component_imag do not match. If the number of harmonics in the components does not match the ones in the phasor coordinates. If the system is underdetermined; the component matrix having more columns than rows.

See also

Component analysis, Multi-component fit

Notes

Calculation of fractions of components from different channels or frequencies is not supported yet. Only one set of components can be analyzed and is broadcast to all channels/frequencies.

The method builds a linear matrix equation, \(A\mathbf{x} = \mathbf{b}\), where \(A\) consists of the phasor coordinates of individual components, \(\mathbf{x}\) are the unknown fractions, and \(\mathbf{b}\) represents the measured phasor coordinates in the mixture. The least-squares solution of this linear matrix equation yields the fractions.

References

[2]

Vallmitjana A, Lepanto P, Irigoin F, and Malacrida L. Phasor-based multi-harmonic unmixing for in-vivo hyperspectral imaging. Methods Appl Fluoresc, 11(1): 014001 (2022)

Examples

>>> phasor_component_fit(
...     [1, 1, 1], [0.6, 0.5, 0.4], [0.4, 0.3, 0.2], [0.2, 0.9], [0.4, 0.3]
... )
array([[0.4644, 0.5356, 0.6068],
       [0.5559, 0.4441, 0.3322]])

phasorpy.component.phasor_component_fraction(real, imag, component_real, component_imag, /)

Return fraction of first of two components from phasor coordinates.

Return the relative distance (normalized by the distance between the two components) to the second component for each phasor coordinate projected onto the line between two components.

Parameters:

• real (array_like) – Real component of phasor coordinates.

• imag (array_like) – Imaginary component of phasor coordinates.

• component_real (array_like, shape (2,)) – Real coordinates of first and second components.

• component_imag (array_like, shape (2,)) – Imaginary coordinates of first and second components.

Returns:

fraction – Fractions of first component.

Return type:

ndarray

Raises:

ValueError – If the real or imaginary coordinates of the known components are not of size 2. If the two components have identical coordinates. If the component coordinates contain NaN or infinite values.

See also

Component analysis

Notes

The fraction of the second component is 1.0 - fraction.

Calculation of fractions of components from different channels or frequencies is not supported yet. Only one pair of components can be analyzed and is broadcast to all channels/frequencies.

Examples

>>> phasor_component_fraction(
...     [0.6, 0.5, 0.4], [0.4, 0.3, 0.2], [0.2, 0.9], [0.4, 0.3]
... )
array([0.44, 0.56, 0.68])

phasorpy.component.phasor_component_graphical(real, imag, component_real, component_imag, /, *, radius=0.05, fractions=None)

Return fractions of two or three components from phasor coordinates.

The graphical method is based on moving circular cursors along the line between pairs of components and quantifying the phasors for each fraction.

Parameters:

• real (array_like) – Real component of phasor coordinates.

• imag (array_like) – Imaginary component of phasor coordinates.

• component_real (array_like, shape (2,) or (3,)) – Real coordinates for two or three components.

• component_imag (array_like, shape (2,) or (3,)) – Imaginary coordinates for two or three components.

• radius (float, optional, default: 0.05) – Radius of cursor.

• fractions (array_like or int, optional) – Number of equidistant fractions, or 1D array of fraction values. Fraction values must be in the range [0.0, 1.0]. If an integer, numpy.linspace(0.0, 1.0, fractions) fraction values are used. By default, the number of fractions is determined from the longest distance between any pair of components and the radius of the cursor (see Notes below).

Returns:

counts – Counts along each line segment connecting components. Ordered 0-1 (2 components) or 0-1, 0-2, 1-2 (3 components). Shaped (number fractions,) (2 components) or (3, number fractions) (3 components).

Return type:

ndarray

Raises:

ValueError – If the array shapes of real and imag, or component_real and component_imag do not match. If the number of components is not 2 or 3. If the radius is not positive. If the component coordinates contain NaN or infinite values. If fractions values are out of range [0, 1].

See also

Component analysis

Notes

Calculation of fractions of components from different channels or frequencies is not supported yet. Only one set of components can be analyzed and is broadcast to all channels/frequencies.

The graphical method was first introduced in [1].

If no fractions are provided, the number of fractions (\(N\)) used is determined from the longest distance between any pair of components (\(D\)) and the radius of the cursor (\(R\)):

\[N = \frac{2 \cdot D}{R} + 1\]

The fractions can be retrieved by:

fractions = numpy.linspace(0.0, 1.0, len(counts[0]))

References

[1]

Ranjit S, Datta R, Dvornikov A, and Gratton E. Multicomponent analysis of phasor plot in a single pixel to calculate changes of metabolic trajectory in biological systems. J Phys Chem A, 123(45): 9865-9873 (2019)

Examples

Count the number of phasors between two components:

>>> phasor_component_graphical(
...     [0.6, 0.3], [0.35, 0.38], [0.2, 0.9], [0.4, 0.3], fractions=6
... )
array([0, 0, 1, 0, 1, 0], dtype=uint8)

Count the number of phasors between the combinations of three components:

>>> phasor_component_graphical(
...     [0.4, 0.5],
...     [0.2, 0.3],
...     [0.0, 0.2, 0.9],
...     [0.0, 0.4, 0.3],
...     fractions=6,
... )
array([[0, 1, 1, 1, 1, 0],
       [0, 1, 0, 0, 0, 0],
       [0, 1, 2, 0, 0, 0]], dtype=uint8)

phasorpy.component.phasor_component_mvc(real, imag, component_real, component_imag, /, *, dtype=None, num_threads=None)

Return mean value coordinates of phasor coordinates from components.

The mean value coordinates of phasor coordinates with respect to three or more components spanning an arbitrary simple polygon are computed using the stable method described in [3]. For three components, mean value coordinates are equivalent to barycentric coordinates.

Parameters:

• real (array_like) – Real component of phasor coordinates.

• imag (array_like) – Imaginary component of phasor coordinates.

• component_real (array_like) – Real coordinates of at least three components.

• component_imag (array_like) – Imaginary coordinates of at least three components.

• dtype (dtype_like, optional) – Floating point data type used for calculation and output values. Either float32 or float64. The default is float64.

• num_threads (int, optional) – Number of OpenMP threads to use for parallelization. By default, multithreading is disabled. If zero, up to half of logical CPUs are used. OpenMP may not be available on all platforms.

Returns:

fractions – Mean value coordinates for each phasor coordinate.

Return type:

ndarray

Raises:

ValueError – If the array shapes of real and imag do not match. If the array shapes of component_real and component_imag do not match.

Notes

Calculation of fractions of components from different channels or frequencies is not supported yet. Only one set of components can be analyzed and is broadcast to all channels/frequencies.

For three components, this function returns the same result as phasor_component_fit(). For more than three components, the system is underdetermined and the mean value coordinates represent one of multiple solutions. However, the special properties of the mean value coordinates make them particularly useful for interpolating and visualizing multi-component data.

References

[3]

Fuda C and Hormann K. A new stable method to compute mean value coordinates. Computer Aided Geometric Design, 111: 102310 (2024)

Examples

Calculate the barycentric coordinates of a phasor coordinate in a triangle defined by three components:

>>> phasor_component_mvc(0.6, 0.3, [0.0, 1.0, 0.0], [1.0, 0.0, 0.0])
array([0.3, 0.6, 0.1])

The barycentric coordinates of phasor coordinates outside the polygon defined by the components may be outside the range [0.0, 1.0]:

>>> phasor_component_mvc(0.6, 0.6, [0.0, 1.0, 0.0], [1.0, 0.0, 0.0])
array([0.6, 0.6, -0.2])

phasorpy.component.phasor_from_component(component_real, component_imag, fraction, /, axis=0, dtype=None)

Return phasor coordinates from fractional intensities of components.

Return the dot products of the fractional intensities with the real and imaginary phasor coordinates of the components.

Multidimensional component arrays are not supported yet.

Parameters:

• component_real (array_like, shape (n,)) – Real coordinates of components. At least two components are required.

• component_imag (array_like, shape (n,)) – Imaginary coordinates of components.

• fraction (array_like) – Fractional intensities of components. Fractions are normalized to sum to 1 along axis.

• axis (int, optional, default: 0) – Axis of components in fraction.

• dtype (dtype_like, optional) – Floating point data type used for calculation and output values. Either float32 or float64. The default is float64.

Returns:

• real (ndarray) – Real component of phasor coordinates.

• imag (ndarray) – Imaginary component of phasor coordinates.

Raises:

ValueError – If dtype is not a floating-point type. If the array shapes of component_real and component_imag do not match. If the fraction array has less than two components along axis. If the component coordinates contain NaN or infinite values.

See also

phasorpy.phasor.phasor_combine

Examples

Calculate phasor coordinates from two components and their fractional intensities:

>>> phasor_from_component(
...     [0.6, 0.4], [0.3, 0.2], [[1.0, 0.2, 0.9], [0.0, 0.8, 0.1]]
... )
(array([0.6, 0.44, 0.58]), array([0.3, 0.22, 0.29]))