Package: scikit-rmt
scikit-rmt: Random Matrix Theory Python packageRandom Matrix Theory, or RMT, is the field of Statistics that analyses
matrices that their entries are random variables.This package offers classes, methods and functions to give support to RMT
in Python. Includes a wide range of utils to work with different random
matrix ensembles, random matrix spectral laws and estimation of covariance
matrices. See documentation or visit thehttps://github.com/AlejandroSantorum/scikit-rmtof the project for further information on the features included in the package.DocumentationThe documentation is available athttps://scikit-rmt.readthedocs.io/en/latest/,
which includes detailed information of the different modules, classes and methods of
the package, along with several examples showing different funcionalities.InstallationUsing a virtual environment is recommended to minimize the chance of conflicts.
However, the global installationshouldwork properly as well.Local installation usingvenv(recommended)Navigate to your project directory.cdMyProjectCreate a virtual environment (you can change the name "env").python3-mvenvenvActivate the environment "env".sourceenv/bin/activateInstall usingpip.pipinstallscikit-rmtYou may need to usepip3.pip3installscikit-rmtGlobal installationJust install it usingpiporpip3.pipinstallscikit-rmtRequirementsscikit-rmtdepends on the following packages:numpy- The fundamental package for scientific computing with Pythonmatplotlib- Plotting with Pythonscipy- Scientific computation in PythonCheck the pinned versions in therequirements.txtfile.Main featuresscikit-rmtprovides support to analyze, study and simulate Random Matrix Theory properties and results:Samplingof the following random matrix ensembles:Gaussian Ensemble (GOE, GUE and GSE; for beta=1, 2 and 4 respectively): classGaussianEnsemble.Wishart Ensemble (WRE, WCE and WQE; for beta=1, 2 and 4 respectively): classWishartEnsemble.Manova Ensemble (MRE, MCE and MQE; for beta=1, 2 and 4 respectively): classManovaEnsemble.Circular Ensemble (COE, CUE, CSE; for beta=1, 2 and 4 respectively): classCircularEnsemble.Eigenvalue computationfor the previous ensembles using the class methodeigvals.Computation of thejoint eigenvalue probability density functiongiven the random matrix eigenvalues, using the class methodjoint_eigval_pdf.Computation of theempirical spectral histogramby executing the class methodeigval_hist.Plotting of the empirical spectral histogramusing the class methodplot_eigval_hist.Computation and plotting of the followingspectral laws(spectral_lawsub-module), including the calculation and plotting of the corresponding probability density functions (PDFs) and cumulative distribution functions (CDFs):Wigner Semicircle law: describes the limiting distribution of the eigenvalues of Wigner matrices (in particular, random matrices from the Gaussian Ensemble). Implemented by classWignerSemicircleDistribution.Tracy-Widom law: describes the limiting distribution of the largest eigenvalue of Wigner matrices (in particular, random matrices from the Gaussian Ensemble). Implemented by classTracyWidomDistribution.Marchenko-Pastur law: describes the limiting distribution of the eigenvalues of Wishart matrices (random matrices from the Wishart Ensemble). Implemented by classMarchenkoPasturDistribution.Manova Spectrum law: introduced and proved by K. W. Wachter (1980), it describes the limiting distribution of the eigenvalues of Manova matrices (random matrices from the Manova Ensemble). Implemented by classManovaSpectrumDistribution.Covariance matrix estimationusing different matrix smoothing and estimation methods (covariancemodule).Estimation of sample covariance matrix usingsample_estimatorfunction.Finite-sample Optimal (FSOpt) estimator byfsopt_estimatorfunction.Empirical Bayesian estimator byempirical_bayesian_estimatorfunction. Haff in"Estimation of a covariance matrix under Stein’s loss"(1985).Minimax estimator byminimax_estimatorfunctionLinear shrinkage estimator bylinear_shrinkage_estimatorfunction. Ledoit and Wolf in"A well-conditioned estimator for large-dimensional covariance matrices"(2004).Analytical shrinkage estimator byanalytical_shrinkage_estimatorfunction. Ledoit and Wolf in"Analytical nonlinear shrinkage of large-dimensional covariance matrices"(2020).A brief tutorialFirst of all, several random matrix ensembles can be sampled:Gaussian Ensembles,Wishart Ensembles,Manova EnsemblesandCircular Ensembles. As an example, the following code shows how to sample
aGaussian Orthogonal Ensemble (GOE)random matrix.fromskrmt.ensemble.gaussian_ensembleimportGaussianEnsemble# sampling a GOE (beta=1) matrix of size 3x3goe=GaussianEnsemble(beta=1,n=3)print(goe.matrix)[[0.34574696-0.108023850.38245343][-0.10802385-0.601139630.28624612][0.382453430.28624612-0.96503739]]Its spectral density can be easily plotted:# sampling a GOE matrix of size 1000x1000goe=GaussianEnsemble(beta=1,n=1000)# plotting its spectral distribution in the interval (-2,2)goe.plot_eigval_hist(bins=80,interval=(-2,2),density=True)If we sample anon-symmetric/non-hermitianrandom matrix, its eigenvalues do not need to be real,
so a2D complex histogramhas been implemented in order to study spectral density of these type
of random matrices. It would be the case, for example, ofCircular Symplectic Ensemble (CSE).fromskrmt.ensemble.circular_ensembleimportCircularEnsemble# sampling a CSE (beta=4) matrix of size 2000x2000cse=CircularEnsemble(beta=4,n=1000)cse.plot_eigval_hist(bins=80)We canboost histogram representationusing the results described by A. Edelman and I. Dumitriu
inMatrix Models for Beta Ensemblesand by J. Albrecht, C. Chan, and A. Edelman inSturm Sequences and Random Eigenvalue Distributions(check references). Sampling certain
random matrices (Gaussian EnsembleandWishart Ensemblematrices) in itstridiagonal formwe can speed up histogramming procedure. The following graphical simulation using GOE matrices
tries to illustrate it.On the other hand, for all the supported ensembles, thejoint eigenvalue probability density functioncan be computed by using the class methodjoint_eigval_pdf(eigvals=None). By default, the method computes the joint eigenvalue PDF of the eigenvalues of the sampled random matrix. However, the method can be called using a pre-computed array of eigenvalues, and the joint eigenvalue PDF of these eigenvalues is returned. AS an example, we can simulate sampling and histogramming many eigenvalues of GOE random matrices of size 2x2, as well as illustrating the joint eigenvalue PDF for GOE matrices 2x2. This simulation is shown in the figure below.In addition, several spectral laws can be analyzed using this library, such as Wigner's Semicircle Law,
Marchenko-Pastur Law and Tracy-Widom Law. The analytical probability density function can also be plotted
by using theplot_law_pdf=Trueargument.Plot ofWigner's Semicircle Law, sampling 100000independenteigenvalues of a GOE matrix:fromskrmt.ensemble.spectral_lawimportWignerSemicircleDistributionwsd=WignerSemicircleDistribution(beta=1)wsd.plot_empirical_pdf(sample_size=100000,bins=80,density=True)fromskrmt.ensemble.spectral_lawimportWignerSemicircleDistributionwsd=WignerSemicircleDistribution(beta=1)wsd.plot_empirical_pdf(sample_size=100000,bins=80,density=True,plot_law_pdf=True)Plot ofMarchenko-Pastur Law, sampling 100000independenteigenvalues of a WRE matrix:fromskrmt.ensemble.spectral_lawimportMarchenkoPasturDistributionmpd=MarchenkoPasturDistribution(beta=1,ratio=1/3)mpd.plot_empirical_pdf(sample_size=100000,bins=80,density=True)fromskrmt.ensemble.spectral_lawimportMarchenkoPasturDistributionmpd=MarchenkoPasturDistribution(beta=1,ratio=1/3)mpd.plot_empirical_pdf(sample_size=100000,bins=80,density=True,plot_law_pdf=True)Plot ofTracy-Widom Law, sampling 30000 maximum eigenvalues of GOE matrices:fromskrmt.ensemble.spectral_lawimportTracyWidomDistributiontwd=TracyWidomDistribution(beta=1)twd.plot_empirical_pdf(sample_size=30000,bins=80,density=True)fromskrmt.ensemble.spectral_lawimportTracyWidomDistributiontwd=TracyWidomDistribution(beta=1)twd.plot_empirical_pdf(sample_size=30000,bins=80,density=True,plot_law_pdf=True)The proposed packagescikit-rmtalso provides support forcomputing and analyzingtheprobability density function (PDF)andcumulative distribution function (CDF)of the main random matrix ensembles. In particular, the following classes are implemented in theensemble.spectral_lawmodule:WignerSemicircleDistributioninskrmt.ensemble.spectral_law.MarchenkoPasturDistributioninskrmt.ensemble.spectral_law.TracyWidomDistributioninskrmt.ensemble.spectral_law.ManovaSpectrumDistributioninskrmt.ensemble.spectral_law.For example,WignerSemicircleDistributioncan be used to plot theWigner's Semicircle Law PDF:importnumpyasnpimportmatplotlib.pyplotaspltfromskrmt.ensemble.spectral_lawimportWignerSemicircleDistributionx1=np.linspace(-5,5,num=1000)x2=np.linspace(-10,10,num=2000)fig,(ax1,ax2)=plt.subplots(1,2,figsize=(12,4))forsigmain[0.5,1.0,2.0,4.0]:wsd=WignerSemicircleDistribution(beta=1,center=0.0,sigma=sigma)y1=wsd.pdf(x1)y2=wsd.pdf(x2)ax1.plot(x1,y1,label=f"$\sigma$ ={sigma}(R = ${wsd.radius}$)")ax2.plot(x2,y2,label=f"$\sigma$ ={sigma}(R = ${wsd.radius}$)")ax1.legend()ax1.set_xlabel("x",fontweight="bold")ax1.set_xticks([-5,-4,-3,-2,-1,0,1,2,3,4,5])ax1.set_ylabel("density",fontweight="bold")ax2.legend()ax2.set_xlabel("x",fontweight="bold")ax2.set_xticks([-10,-8,-6,-4,-2,0,2,4,6,8,10])ax2.set_ylabel("density",fontweight="bold")fig.suptitle("Wigner Semicircle probability density function (PDF)",fontweight="bold")plt.show()Similarly,MarchenkoPasturDistributioncan be used to plot theMarchenko-Pastur Law PDF:importnumpyasnpimportmatplotlib.pyplotaspltfromskrmt.ensemble.spectral_lawimportMarchenkoPasturDistributionx1=np.linspace(0,4,num=1000)x2=np.linspace(0,5,num=2000)fig,(ax1,ax2)=plt.subplots(1,2,figsize=(12,4))forratioin[0.2,0.4,0.6,1.0,1.4]:mpl=MarchenkoPasturDistribution(beta=1,ratio=ratio,sigma=1.0)y1=mpl.pdf(x1)y2=mpl.pdf(x2)ax1.plot(x1,y1,label=f"$\lambda$ ={ratio}")ax2.plot(x2,y2,label=f"$\lambda$ ={ratio}")ax1.legend()ax1.set_ylim(0,1.4)ax1.set_xlabel("x",fontweight="bold")ax1.set_ylabel("density",fontweight="bold")ax2.legend()ax2.set_ylim(0,1.4)ax2.set_xlim(0,1)ax2.set_xlabel("x",fontweight="bold")ax2.set_ylabel("density",fontweight="bold")fig.suptitle("Marchenko-Pastur probability density function (PDF)",fontweight="bold")plt.show()In the following example, we show how we can plot thePDF and CDF of the Tracy-Widom distributionusing the classTracyWidomDistribution:importnumpyasnpimportmatplotlib.pyplotaspltfromskrmt.ensemble.spectral_lawimportTracyWidomDistributionx=np.linspace(-5,2,num=1000)fig,(ax1,ax2)=plt.subplots(1,2,figsize=(12,4))forbetain[1,2,4]:twd=TracyWidomDistribution(beta=beta)y_pdf=twd.pdf(x)y_cdf=twd.cdf(x)ax1.plot(x,y_pdf,label=f"$\\beta$ ={beta}")ax2.plot(x,y_cdf,label=f"$\\beta$ ={beta}")ax1.legend()ax1.set_xlabel("x",fontweight="bold")ax1.set_ylabel("density",fontweight="bold")ax1.set_title("Probability density function")ax2.legend()ax2.set_xlabel("x",fontweight="bold")ax2.set_ylabel("distribution",fontweight="bold")ax2.set_title("Cumulative distribution function")fig.suptitle("Tracy Widom Law",fontweight="bold")plt.show()The other module of this library implementsseveral covariance matrix estimators:Sample estimator.Finite-sample optimal estimator (FSOpt estimator).Non-linear shrinkage analytical estimator (Ledoit & Wolf, 2020).Linear shrinkage estimator (Ledoit & Wolf, 2004).Empirical Bayesian estimator (Haff, 1980).Minimax estimator (Stain, 1982).For certain problems, sample covariance matrix is not the best estimation for the
population covariance matrix.The following code illustrates the usage of the estimators.fromskrmt.covarianceimportanalytical_shrinkage_estimator# load dataset with your own/favorite function (such as pandas.read_csv)X=load_dataset('dataset_file.data')# get estimationSigma=analytical_shrinkage_estimator(X)# ... Do something with Sigma. For example, PCA.For more information or insight about the usage of the library, you can visit the officialdocumentationhttps://scikit-rmt.readthedocs.io/en/latest/or the directorynotebooks, that contains severalPython notebookswithtutorialsand plenty ofexamples.LicenseThe package is licensed under the BSD 3-Clause License. A copy of thelicensecan be found along with the code.Main referencesJames Albrecht, Cy Chan, and Alan Edelman,
"Sturm Sequences and Random Eigenvalue Distributions",Foundations of Computational Mathematics,
vol. 9 iss. 4 (2009), pp 461-483.[pdf][doi]Ioana Dumitriu and Alan Edelman,
"Matrix Models for Beta Ensembles",Journal of Mathematical Physics,
vol. 43 no. 11 (2002), pp. 5830-5547arXiv:math-ph/0206043Rowan Killip and Rostyslav Kozhan,
"Matrix Models and Eigenvalue Statistics for Truncations of Classical Ensembles of Random Unitary Matrices",Communications in Mathematical Physics, vol. 349 (2017) pp. 991-1027.arxiv.org/pdf/1501.05160.pdfOlivier Ledoit and Michael Wolf,
"Analytical Nonlinear Shrinkage of Large-dimensional Covariance Matrices",Annals of Statistics, vol. 48, no. 5 (2020) pp. 3043–3065.[pdf]Olivier Ledoit and Michael Wolf,
"A Well-conditioned Estimator for Large-dimensional Covariance Matrices",Journal of Multivariate Analysis, vol. 88 (2004) pp. 365–411.[pdf]AttributionThis project has been developed by Alejandro Santorum Varela (2021) as part of the final degree project
in Computer Science (Autonomous University of Madrid), supervised by Alberto Suárez González.If you happen to usescikit-rmtin your work or research, please cite its GitHub repository:A. Santorum, "scikit-rmt",https://github.com/AlejandroSantorum/scikit-rmt, 2021. GitHub repository.The corresponding BibTex entry is@misc{Santorum2021,
  author = {A. Santorum},
  title = {scikit-rmt},
  year = {2021},
  howpublished = {\url{https://github.com/AlejandroSantorum/scikit-rmt}},
  note = {GitHub repository}
}