The MATLAB toolbox RegularizedSCM is a collection of Matlab functions that can be used to compute different regularized sample covariance matrix (RSCM) estimators such as the Ell-RSCM estimators proposed by Ollila and Raninen (2018) or Ledoit and Wolf (2004).

The toolbox also contains functions and various examples on how the RSCM estimators can be utilized in various data analysis tasks such as classification based on regularized linear and quadratic discriminant analysis or portfolio optimization in finance using global minimum variance portfolio allocation.

We include examples of portfolio optimization on real data sets which reproduce the results that were reported in Ollila and Raninen (2018). We also include a supervised classification example using regularized discriminant analysis. The analysis results are described in the supplementary material

Contents

Compatibility

The code is tested on Matlab R2017b, but should work on other versions of Matlab with no or little changes as well as all platforms (Windows 64-bit, Linux 64-bit, or Mac 64-bit).

Installation for Matlab version >= 2014b

Download the Matlab toolbox installation file RegularizedSCM.mltbx. Double click the downloaded file and the Matlab installs the toolbbox. If it does not work follow the instructions below for installation for Matlab version < 2014b.

Installation for Matlab version < 2014b

  1. Extract the ZIP File RegularizedSCM.zip to a local folder. It creates RegularizedSCM directory to your local path.
  2. Add the RegularizedSCM folder to the Matlab search path as follows. Start Matlab and go to the RegularizedSCM folder, and execute the lines:
addpath(pwd) %<-- Add the toolbox to the Matlab path
save path  %<-- Save the path %

How to cite

If you use this toolbox or any of its function, please cite the software itself along with the publication:

  • Esa Ollila and Elias Raninen, "Matlab RegularizedSCM Toolbox Version 1.0," Available online: http://users.spa.aalto.fi/esollila/regscm/, August 2018.
  • Esa Ollila and Elias Raninen, "Optimal shrinkage covariance matrix estimation under random sampling from elliptical distributions," arXiv:1808.10188 [stat.ME], Submitted to IEEE Transactions on Signal Processing, Aug. 2018. https://arxiv.org/abs/1808.10188

Now you are good to go!

Getting started

To get help of individual functions, type help followed by the function name in Matlab command window, e.g., to get help on regscm function, type:

help regscm

  REGSCM Computes different regularized (shrinkage SCM) estimators given a
  data matrix X (rows are observations)
  [RSCM, invRSCM, stats] = regscm(X,...) 
 
  REGSCM can be called with numerous optional arguments. Optional
  arguments are given in parameter pairs, so that first argument is
  the name of the parameter and the next argument is the value for
  that parameter. Optional parameter pairs can be given in any order.
 
  Optional Parameters:
 
  Parameter name        Values and description
 ==========================================================================
  --Basic parameter is the choise of the estimator to use
 
  'approach'            (string) which estimate of the MMSE shrinkage pe- 
                        nalty parameter beta to use
                        'ell1' (default)    uses ELL1-RSCM estimator
                        'ell2'              uses ELL2-RSCM estimator
                        'lw'                uses Ledoit-Wolf approach
 ==========================================================================
  -- It is also possible to give other values for the parameters that are
  needed by Ell1- and Ell2-RSCM estimators. For example, it is possible to
  specify the value of elliptical kurtosis parameter if one has some a
  priori knowledge of its value (e.g., for Gaussian-like data, one
  case set kappa to a value equal to 0) or if the value of the elliptical
  kurtosis has been computed previously using *ellkurt* function.
  
  'kappa'               (number) elliptical kurtosis parameter to use. Must
                        be larger than kappa_lowerb = -2/(p+2)
  'gamma'               (number) sphericity measure to use. Must be a value
                        between [1,p]. If gamma is not given, then approach 
                        parameter determines the sphericity estimator used  
  'inverse'             (logical) true or false. If true then one computes 
                        also the inverse of the regularized SCM. Computation 
                        of the inverse is optimized for speed and computed 
                        via SVD when p > 10*n, i.e., when p is order(s) of 
                        magnitude larger than the sample size. 
  'verbose'             (string) Either 'on' (default) or 'off'. When 'on' 
                        then prints progress of the function in text format.
  'centered'            (logical) if true then X is already centered, and
                        omits centering of the data. If false (default), 
                        then the data will be centered. 
 
  See also ELLKURT, COMPUTE_ETAS
 
  toolbox: RegularizedSCM
  authors: Copyright by Esa Ollila and Elias Raninen. 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

to have a quick acces to the provided demo examples in the toolbox simply type

demo RegularizedSCM

An example

Below is an example of how to use the regscm function. The simulation follows the AR(1) covariance matrix set-up that is explained in Section V.A of Ollila and Raninen (2018)

p = 100; % dimension of the data
n = 30;  % sample lenth
rho = 0.1; % correlation of the AR(1) covariance matrix

rng(0);
% generate the mean vector and the covariance matrix
tmp     = abs(repmat(1:p,p,1) - repmat(1:p,p,1)');
M       = rho.^tmp; % covariance = correlation matrix
Msqrt   = sqrtm(M);
mu      = 2*randn(1,p); % random mean vector

% data matrix generation
X0 = randn(n,p);
X  = X0*Msqrt + repmat(mu,n,1);

% compute Ell1-RSCM and the MSE
[RSCM1,~, stat] = regscm(X,'approach','ell1','verbose','off');
MSEell1 = norm(RSCM1 - M,'fro')^2

% compute Ell2-RSCM and the MSE
[RSCM2,~, stat2] = regscm(X,'approach','ell2','verbose','off','kappa',stat.kappa);
% above we exploited the fact that elliptical kurtosis value was computed
% earlier and gave it as an additional input parameter
MSEell2  = norm(RSCM2 - M,'fro')^2

% MSE of Ledoit and Wold RSCM estimator
[LWE,~, stat3] = regscm(X,'approach','lw','verbose','off');
MSElwe = norm(LWE - M,'fro')^2

MSEell1 =

    2.7221


MSEell2 =

    2.0014


MSElwe =

    4.1911

Other references

  • O. Ledoit and M. Wolf, "A well-conditioned estimator for large-dimensional covariance matrices,” Journal of Multivariate Analysis, vol. 88, pp. 365–411, 2004.


Published with MATLAB® R2017b