phasorpy.cluster#

Cluster phasor coordinates.

The phasorpy.cluster module provides functions to:

fit elliptical clusters to phasor coordinates using a Gaussian Mixture Model (GMM):
- phasor_cluster_gmm()
assign phasor coordinates to clusters using k-means clustering:
- phasor_cluster_kmeans()

phasorpy.cluster.phasor_cluster_gmm(real, imag, /, *, sigma=2.0, clusters=1, sort=None, **kwargs)[source]#

Return elliptical 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, default: 2) – Scaling factor for radii of major and minor axes. The default 2.0 is commonly used for visualization of confidence ellipses (~98.2%).
clusters (int, optional, default: 1) – Number of Gaussian distributions to fit to phasor coordinates.
sort ({'polar', 'phasor', 'area'}, optional) –
Sorting method for output clusters. By default, use ‘polar’ sorting.
- ’polar’: Sort by polar coordinates (phase, then modulation).
- ’phasor’: Sort by phasor coordinates (imaginary, then real).
- ’area’: Sort by inverse area of ellipse (-major * minor).
**kwargs –
Optional arguments passed to 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].

Raises:

ValueError – If sigma is not positive. If clusters is less than 1. If the array shapes of real and imag do not match. If the number of valid (non-NaN) data points is less than clusters. If sort is not a valid sorting method.

See also

Clusters

Notes

This function operates on single-harmonic, single-channel data only. Multi-harmonic or multi-channel data must be clustered separately.

References

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
(0.2, 0.4)

phasorpy.cluster.phasor_cluster_kmeans(real, imag, /, *, clusters=1, sort=None, **kwargs)[source]#

Return k-means clusters of phasor coordinates.

Partition phasor coordinates into clusters groups using k-means clustering, assigning each phasor coordinate to the cluster with the nearest center.

Parameters:

real (array_like) – Real component of phasor coordinates.
imag (array_like) – Imaginary component of phasor coordinates.
clusters (int, optional, default: 1) – Number of clusters to partition phasor coordinates into.
sort ({'polar', 'phasor', 'size'}, optional) –
Sorting method for output clusters. By default, use ‘polar’ sorting.
- ’polar’: Sort by polar coordinates (phase, then modulation).
- ’phasor’: Sort by phasor coordinates (imaginary, then real).
- ’size’: Sort by decreasing number of coordinates in cluster.
**kwargs –
Optional arguments passed to sklearn.cluster.KMeans or sklearn.cluster.KMeans.fit_predict().

Common options include:
- init : {‘k-means++’, ‘random’}, method of initialization
- n_init : int, number of initializations to perform
- max_iter : int, maximum number of iterations
- random_state : int, for reproducible results
- sample_weight: array_like, weight of each phasor coordinate

Returns:

center_real (tuple of float) – Real component of cluster centers.
center_imag (tuple of float) – Imaginary component of cluster centers.
labels (ndarray) – Zero-based index of cluster each phasor coordinate belongs to. Same shape as real and imag. Values are -1 where real or imag are NaN.

Raises:

ValueError – If clusters is less than 1. If the array shapes of real and imag do not match. If the number of valid (non-NaN) data points is less than clusters. If sort is not a valid sorting method.