dyson_equalizer.dyson_equalizer module#

The dyson_equalizer.dyson_equalizer module contains the class DysonEqualizer that can be used to easily compute the Dyson Equalizer.

class dyson_equalizer.dyson_equalizer.DysonEqualizer(Y: ndarray)[source]#

Bases: object

This class can be used to compute the Dyson Equalizer [1]_ and store all associated results.

Attributes:

Y: (m, n) numpy.ndarray: The original data matrix
x_hat: (m) numpy.ndarray: The normalizing factors for the rows
y_hat: (n) numpy.ndarray: The normalizing factors for the columns
Y_hat: (m, n) numpy.ndarray: The normalized data matrix so that the variance of the error is 1
X_bar: (m, n) numpy.ndarray: The estimated signal matrix. It has rank r_hat
r_hat: int: The estimated rank of the signal matrix
S: (m) numpy.ndarray: The principal values of the data matrix Y
S_hat: (m) numpy.ndarray: The principal values of the normalized data matrix Y_hat

Methods

`compute`([use_Y_hat])	Computes the Dyson Equalizer and stores the results.
`plot_mp_density_Y`([show_only_significant, ax])	Plots the density of eigenvalues of ¹⁄ₙYYᵀ and compares to the Marchenko-Pastur distribution
`plot_mp_density_Y_hat`([...])	Plots the density of eigenvalues of ¹⁄ₙŶŶᵀ and compares to the Marchenko-Pastur distribution
`plot_mp_eigenvalues_Y`([eigenvalues_to_show, ...])	Plots the eigenvalues of ¹⁄ₙYYᵀ and compares to the Marchenko-Pastur threshold
`plot_mp_eigenvalues_Y_hat`([...])	Plots the eigenvalues of ¹⁄ₙŶŶᵀ and compares to the Marchenko-Pastur threshold
`plot_mp_eigenvalues_and_densities`([...])	Plots the eigenvalues of ¹⁄ₙYYᵀ of ¹⁄ₙŶŶᵀ and their densities.

See also

dyson_equalizer.algorithm.compute_scaling_factors
dyson_equalizer.algorithm.compute_low_rank_approximation_mp

S: ndarray = None[source]#: The principal values of the data matrix Y

S_hat: ndarray = None[source]#: The principal values of the data matrix Y_hat

X_bar: ndarray = None[source]#: The estimated signal matrix. It has rank r_hat

Y: ndarray[source]#: The original data matrix

Y_hat: ndarray = None[source]#: The normalized data matrix so that the variance of the error is 1

compute(use_Y_hat: bool = False) → Self[source]#

Computes the Dyson Equalizer and stores the results.

Parameters:

use_Y_hat: bool, optional: if True uses Y_hat instead of the original matrix as input. This option may be used iteratively to improve the low rank approximation in some cases

Returns:

selfDysonEqualizer: A reference to this instance

plot_mp_density_Y(show_only_significant: int = None, ax: Axes | None = None) → None[source]#

Plots the density of eigenvalues of ¹⁄ₙYYᵀ and compares to the Marchenko-Pastur distribution

This function assumes the input are the eigenvalues of a covariance matrix of a random matrix whose entries have variance 1. These eigenvalues follow the Marchenko-Pastur distribution.

Parameters:

show_only_significant: int, optional: Set this value to show only a small number of significant eigenvalues (defaults to None) This option is useful is some of the signal eigenvalues are much bigger than the noise.
ax: plt.Axes, optional: A matplotlib Axes object. If none is provided, a new figure is created.

See also

dyson_equalizer.plots.plot_mp_density

plot_mp_density_Y_hat(show_only_significant: int = None, ax: Axes | None = None) → None[source]#

Plots the density of eigenvalues of ¹⁄ₙŶŶᵀ and compares to the Marchenko-Pastur distribution

This function assumes the input are the eigenvalues of a covariance matrix of a random matrix whose entries have variance 1. These eigenvalues follow the Marchenko-Pastur distribution.

Parameters:

show_only_significant: int, optional: Set this value to show only a small number of significant eigenvalues (defaults to None) This option is useful is some of the signal eigenvalues are much bigger than the noise.
ax: plt.Axes, optional: A matplotlib Axes object. If none is provided, a new figure is created.

See also

dyson_equalizer.plots.plot_mp_density

plot_mp_eigenvalues_Y(eigenvalues_to_show: int = 100, log_y: bool = True, ax: Axes | None = None) → None[source]#

Plots the eigenvalues of ¹⁄ₙYYᵀ and compares to the Marchenko-Pastur threshold

Parameters:

eigenvalues_to_show: int, optional: The number of eigenvalues to show in the plot (defaults to 100)
log_y: bool, optional: Whether the y-axis should be logarithmic (defaults to True)
ax: plt.Axes, optional: A matplotlib Axes object. If none is provided, a new figure is created.

Returns:

See also

dyson_equalizer.plots.plot_mp_eigenvalues

plot_mp_eigenvalues_Y_hat(eigenvalues_to_show: int = 100, log_y: bool = True, ax: Axes | None = None) → None[source]#

Plots the eigenvalues of ¹⁄ₙŶŶᵀ and compares to the Marchenko-Pastur threshold

Parameters:

eigenvalues_to_show: int, optional: The number of eigenvalues to show in the plot (defaults to 100)
log_y: bool, optional: Whether the y-axis should be logarithmic (defaults to True)
ax: plt.Axes, optional: A matplotlib Axes object. If none is provided, a new figure is created.

See also

dyson_equalizer.plots.plot_mp_eigenvalues

plot_mp_eigenvalues_and_densities(log_eigenvalues: bool = True, eigenvalues_to_show: int = 100, show_only_significant: int = 2, figsize: tuple[int, int] = (12, 8)) → None[source]#

Plots the eigenvalues of ¹⁄ₙYYᵀ of ¹⁄ₙŶŶᵀ and their densities.

and compares to the Marchenko-Pastur threshold

Parameters:

eigenvalues_to_show: int, optional: The number of eigenvalues to show in the eigenvalue plots (defaults to 100)
log_eigenvalues: bool, optional: Whether the y-axis should be logarithmic in the eigenvalue plots (defaults to True)
show_only_significant: int = None,: Set this value to show only a small number of significant eigenvalues in the density plots This option is useful is some of the signal eigenvalues are much bigger than the noise.
figsize: int, int: The figure size

See also

plot_mp_eigenvalues_Y
plot_mp_eigenvalues_Y_hat
plot_mp_density_Y
plot_mp_density_Y_hat

r_hat: int = None[source]#: The estimated rank of the signal matrix

x_hat: ndarray = None[source]#: The normalizing factors for the rows

y_hat: ndarray = None[source]#: The normalizing factors for the columns