Regularised covariance estimators (Ledoit-Wolf, OAS, fixed-diagonal, PCA, Factor Analysis, cross-validated auto-select) matching the MNE-Python compute_covariance() API. More...

#include <sts_cov_estimators.h>

Static Public Member Functions
static std::pair< Eigen::MatrixXd, double >	ledoitWolf (const Eigen::MatrixXd &matData)
	Ledoit-Wolf optimal shrinkage covariance estimator.
static std::pair< Eigen::MatrixXd, double >	oas (const Eigen::MatrixXd &matData)
	Oracle Approximating Shrinkage (OAS) covariance estimator.
static std::pair< Eigen::MatrixXd, double >	diagonalFixed (const Eigen::MatrixXd &matData, double dReg=0.1)
	Fixed diagonal regularisation.
static std::pair< Eigen::MatrixXd, double >	pca (const Eigen::MatrixXd &matData, int iRank=0)
	PCA-based rank-reduced covariance estimator.
static std::pair< Eigen::MatrixXd, double >	factorAnalysis (const Eigen::MatrixXd &matData, int iNFactors=0, int iMaxIter=200, double dTol=1e-6)
	Factor Analysis covariance estimator via EM algorithm.
static std::pair< Eigen::MatrixXd, double >	autoSelect (const Eigen::MatrixXd &matData, int iNFolds=3)
	Auto-select the best covariance estimator via cross-validation.
static double	gaussianLogLikelihood (const Eigen::MatrixXd &matTestData, const Eigen::MatrixXd &matCov)
	Gaussian log-likelihood of held-out data given a covariance model.

Detailed Description

Regularised covariance estimators (Ledoit-Wolf, OAS, fixed-diagonal, PCA, Factor Analysis, cross-validated auto-select) matching the MNE-Python compute_covariance() API.

Covariance matrix estimators.

Provides multiple regularised covariance estimation methods matching MNE-Python's compute_covariance() API. Each method takes zero-mean data (n_channels x n_samples) and returns a pair of (covariance, parameter).

Definition at line 78 of file sts_cov_estimators.h.

Member Function Documentation

◆ autoSelect()

std::pair< MatrixXd, double > StsCovEstimators::autoSelect	(	const Eigen::MatrixXd &	matData,
		int	iNFolds = 3 )

static

Auto-select the best covariance estimator via cross-validation.

Runs all available estimators (empirical, shrunk/LW, OAS, diagonal_fixed, PCA, factor_analysis) and selects the one with the highest average Gaussian log-likelihood on held-out folds.

Parameters

[in]	matData	Zero-mean data, n_channels x n_samples.
[in]	iNFolds	Number of cross-validation folds (default 3).

Returns: std::pair containing the best covariance matrix and the index of the winning method (0=empirical, 1=shrunk, 2=oas, 3=diagonal_fixed, 4=pca, 5=factor_analysis).

Definition at line 194 of file sts_cov_estimators.cpp.

◆ diagonalFixed()

std::pair< MatrixXd, double > StsCovEstimators::diagonalFixed	(	const Eigen::MatrixXd &	matData,
		double	dReg = 0.1 )

static

Fixed diagonal regularisation.

Computes the sample covariance and adds a fixed fraction of the mean eigenvalue to the diagonal: C_reg = C + reg * trace(C)/p * I.

Parameters

[in]	matData	Zero-mean data, n_channels x n_samples.
[in]	dReg	Regularisation fraction (default 0.1).

Returns: std::pair containing the regularised covariance and dReg.

Definition at line 93 of file sts_cov_estimators.cpp.

◆ factorAnalysis()

std::pair< MatrixXd, double > StsCovEstimators::factorAnalysis	(	const Eigen::MatrixXd &	matData,
		int	iNFactors = 0,
		int	iMaxIter = 200,
		double	dTol = 1e-6 )

static

Factor Analysis covariance estimator via EM algorithm.

Decomposes covariance as C = W*W^T + Psi, where W is a low-rank loading matrix and Psi is a diagonal noise matrix. Uses the EM algorithm from Rubin & Thayer (1982).

Parameters

[in]	matData	Zero-mean data, n_channels x n_samples.
[in]	iNFactors	Number of latent factors (default: min(p,n)/2).
[in]	iMaxIter	Maximum EM iterations (default 200).
[in]	dTol	Convergence tolerance on log-likelihood (default 1e-6).

Returns: std::pair containing the Factor Analysis covariance and the final log-likelihood.

Definition at line 152 of file sts_cov_estimators.cpp.

◆ gaussianLogLikelihood()

double StsCovEstimators::gaussianLogLikelihood	(	const Eigen::MatrixXd &	matTestData,
		const Eigen::MatrixXd &	matCov )

static

Gaussian log-likelihood of held-out data given a covariance model.

Computes: -0.5 * (p * log(2π) + log|Σ| + trace(Σ^{-1} * S_test)) where S_test is the sample covariance of the test data.

Parameters

[in]	matTestData	Zero-mean test data, n_channels x n_test_samples.
[in]	matCov	Covariance model, n_channels x n_channels.

Returns: Average log-likelihood per sample.

Definition at line 165 of file sts_cov_estimators.cpp.

◆ ledoitWolf()

std::pair< MatrixXd, double > StsCovEstimators::ledoitWolf ( const Eigen::MatrixXd & matData )

static

Ledoit-Wolf optimal shrinkage covariance estimator.

Computes the shrinkage coefficient analytically using the formula from Ledoit & Wolf (2004) "A well-conditioned estimator for large-dimensional covariance matrices" (Journal of Multivariate Analysis, 88(2), 365-411).

Parameters

[in] matData Zero-mean data, n_channels x n_samples.

Returns: std::pair containing the shrunk covariance matrix (n_channels x n_channels) and the shrinkage coefficient alpha in [0,1].

Definition at line 73 of file sts_cov_estimators.cpp.

◆ oas()

std::pair< MatrixXd, double > StsCovEstimators::oas ( const Eigen::MatrixXd & matData )

static

Oracle Approximating Shrinkage (OAS) covariance estimator.

Implements the OAS formula from Chen, Wiesel, Eldar & Hero (2010) "Shrinkage Algorithms for MMSE Covariance Estimation" (IEEE Transactions on Signal Processing, 58(10), 5016-5029).

Parameters

[in] matData Zero-mean data, n_channels x n_samples.

Returns: std::pair containing the shrunk covariance matrix and the shrinkage coefficient rho in [0,1].

Definition at line 83 of file sts_cov_estimators.cpp.

◆ pca()

std::pair< MatrixXd, double > StsCovEstimators::pca	(	const Eigen::MatrixXd &	matData,
		int	iRank = 0 )

static

PCA-based rank-reduced covariance estimator.

Computes covariance in the subspace of the top-k principal components. Components beyond rank are zeroed. If iRank <= 0, the rank is estimated from the eigenvalue spectrum.

Parameters

[in]	matData	Zero-mean data, n_channels x n_samples.
[in]	iRank	Number of principal components to retain (0 = auto).

Returns: std::pair containing the rank-reduced covariance and the effective rank used.

Definition at line 111 of file sts_cov_estimators.cpp.

The documentation for this class was generated from the following files:

src/libraries/sts/sts_cov_estimators.h
src/libraries/sts/sts_cov_estimators.cpp

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ autoSelect()

◆ diagonalFixed()

◆ factorAnalysis()

◆ gaussianLogLikelihood()

◆ ledoitWolf()

◆ oas()

◆ pca()