phasorpy.component#

Component analysis of 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 second component if only one is known (not implemented)
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 histogram (phasor_component_graphical())
calculate mean value coordinates of phasor coordinates 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)
calculate phasor coordinates from fractional intensities of components (phasor_from_component())

phasorpy.component.phasor_component_fit(mean, real, imag, component_real, component_imag, /, **kwargs)[source]#

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 fit 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) – Additional arguments passed to scipy.linalg.lstsq().

Returns:

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

Return type:

ndarray

Raises:

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

See also

Component analysis

Notes

For now, calculation of fraction of components from different channels or frequencies is not supported. Only one set of components can be analyzed and will be 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

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)[source]#

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, multi-threading 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 – The array shapes of real and imag do not match. The array shapes of component_real and component_imag do not match.

Notes

Calculation of mean value coordinates for different channels, frequencies, or harmonics is not supported. Only one set of components can be analyzed and is broadcast to all channels/frequencies/harmonics.

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

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)[source]#

Return phasor coordinates from fractional intensities of components.

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

Multi-dimensional component arrays are currently not supported.

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 one 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.

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]))