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:
objectThis 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.
compute_iteratively([Y_hat_delta_threshold, ...])Computes the Dyson Equalizer iteratively and stores the results.
Computes the p-value of the Kolmogorov–Smirnov test between the density of eigenvalues of ¹⁄ₙYYᵀ
Computes the p-value of the Kolmogorov–Smirnov test between the density of eigenvalues of ¹⁄ₙŶŶᵀ
plot_mp_density_Y([show_only_significant, ...])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
Plots the eigenvalues of ¹⁄ₙYYᵀ of ¹⁄ₙŶŶᵀ and their densities.
See also
- compute(use_Y_hat: bool = False) Self[source]#
Computes the Dyson Equalizer and stores the results.
- Parameters:
- use_Y_hat: bool, optional
if
Trueuses 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
- compute_iteratively(Y_hat_delta_threshold: float = 1e-06, ks_pvalue_unchanged: bool = True, max_iterations: int = 100) Self[source]#
Computes the Dyson Equalizer iteratively and stores the results.
- Parameters:
- Y_hat_delta_threshold: float, optional
Terminates if the average difference between Y_hat entries is below this value
- ks_pvalue_unchanged: bool, optional
Terminates if the KS-pvalue has not changed in the last iteration
- max_iterations: int, optional
The maximum number of iterations
- Returns:
- selfDysonEqualizer
A reference to this instance
- iteration_statistics: list[IterationStatistics] = [IterationStatistics(delta_Y_hat=nan, ks_pvalue=np.float64(0.8108971656895569), x_hat_mean=np.float64(1.821658169097402), y_hat_mean=np.float64(0.7366401689728173)), IterationStatistics(delta_Y_hat=nan, ks_pvalue=np.float64(0.8108971656895569), x_hat_mean=np.float64(1.823016649460319), y_hat_mean=np.float64(0.5615476660102091))][source]#
Statistics on each iteration
- ks_pvalue_Y() float[source]#
- Computes the p-value of the Kolmogorov–Smirnov test between the density of eigenvalues of ¹⁄ₙYYᵀ
and the Marchenko-Pastur distribution
- Returns:
- p-valueDysonEqualizer
The p-value of the Kolmogorov–Smirnov test
- ks_pvalue_Y_hat() float[source]#
- Computes the p-value of the Kolmogorov–Smirnov test between the density of eigenvalues of ¹⁄ₙŶŶᵀ
and the Marchenko-Pastur distribution
- Returns:
- p-valueDysonEqualizer
The p-value of the Kolmogorov–Smirnov test
- plot_mp_density_Y(show_only_significant: int = None, show_only_significant_right_margin: float = 0.3, 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. Set to zero to show only significant eigenvalues within the margin indicated by show_only_significant_right_margin
- show_only_significant_right_margin: float, optional
Specifies the size of the right margin (defaults to 0.3) from the largest eigenvalue selected by the show_only_significant option
- ax: plt.Axes, optional
A matplotlib Axes object. If none is provided, a new figure is created.
- plot_mp_density_Y_hat(show_only_significant: int = None, show_only_significant_right_margin: float = 0.3, 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.
- 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. Set to zero to show only significant eigenvalues within the margin indicated by show_only_significant_right_margin
- show_only_significant_right_margin: float, optional
Specifies the size of the right margin (defaults to 0.3) from the largest eigenvalue selected by the show_only_significant option
- ax: plt.Axes, optional
A matplotlib Axes object. If none is provided, a new figure is created.
- 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:
- 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.
- plot_mp_eigenvalues_and_densities(log_eigenvalues: bool = True, eigenvalues_to_show: int = 100, show_only_significant: int = 2, show_only_significant_right_margin: float = 0.3, 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, 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. Set to zero to show only significant eigenvalues within the margin indicated by show_only_significant_right_margin
- show_only_significant_right_margin: float, optional
Specifies the size of the right margin (defaults to 0.3) from the largest eigenvalue selected by the show_only_significant option
- figsize: int, int
The figure size