metabci.brainda.algorithms.utils.covariance module¶
- class metabci.brainda.algorithms.utils.covariance.Covariance(estimator='cov', n_jobs=1)[source]¶
Bases:
BaseEstimator,TransformerMixinEstimation of covariance matrix.
- Parameters:
estimator (str or callable object, optional) –
Covariance estimator to use (the default is cov, which uses empirical covariance estimator). For regularization, consider lwf or oas.
supported estimators
cov: empirial covariance estimator
lwf: ledoit wolf covariance estimator
oas: oracle approximating shrinkage covariance estimator
mcd: minimum covariance determinant covariance estimator
n_jobs (int or None, optional) – The number of CPUs to use to do the computation (the default is 1, -1 for all processors).
See also
ERPCovariance
- metabci.brainda.algorithms.utils.covariance.covariances(X: ndarray, estimator: str | Callable[[ndarray], ndarray] = 'cov', n_jobs: int = 1) ndarray[source]¶
Estimation of covariance matrix.
- Parameters:
X (ndarray) – EEG signal, shape (…, n_channels, n_samples).
estimator (str or callable object, optional) –
Covariance estimator to use (the default is cov, which uses empirical covariance estimator). For regularization, consider lwf or oas.
supported estimators
cov: empirial covariance estimator
lwf: ledoit wolf covariance estimator
oas: oracle approximating shrinkage covariance estimator
mcd: minimum covariance determinant covariance estimator
n_jobs (int or None, optional) – The number of CPUs to use to do the computation (the default is 1, -1 for all processors).
- Returns:
covmats – covariance matrices, shape (…, n_channels, n_channels)
- Return type:
ndarray
See also
covariances_erp()
- metabci.brainda.algorithms.utils.covariance.expm(Ci: ndarray, n_jobs: int | None = None)[source]¶
Return the matrix exponential of a covariance matrix.
- Parameters:
Ci (ndarray) – Input positive-definite matrix.
- Returns:
Exponential matrix of Ci.
- Return type:
ndarray
Notes
\[\mathbf{C} = \mathbf{V} \exp{(\mathbf{\Lambda})} \mathbf{V}^T\]where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).
- metabci.brainda.algorithms.utils.covariance.invsqrtm(Ci: ndarray, n_jobs: int | None = None)[source]¶
Return the inverse matrix square root of a covariance matrix.
- Parameters:
Ci (ndarray) – Input positive-definite matrix.
- Returns:
Inverse matrix square root of Ci.
- Return type:
ndarray
Notes
\[\mathbf{C} = \mathbf{V} \left( \mathbf{\Lambda} \right)^{-1/2} \mathbf{V}^T\]where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).
- metabci.brainda.algorithms.utils.covariance.isPD(B: ndarray) bool[source]¶
Returns true when input matrix is positive-definite, via Cholesky decompositon method.
- Parameters:
B (ndarray) – Any matrix, shape (N, N)
- Returns:
True if B is positve-definite.
- Return type:
bool
Notes
Use numpy.linalg rather than scipy.linalg. In this case, scipy.linalg has unpredictable behaviors.
- metabci.brainda.algorithms.utils.covariance.logm(Ci: ndarray, n_jobs: int | None = None)[source]¶
Return the matrix logrithm of a covariance matrix.
- Parameters:
Ci (ndarray) – Input positive-definite matrix.
- Returns:
Logrithm matrix of Ci.
- Return type:
ndarray
Notes
\[\mathbf{C} = \mathbf{V} \log{(\mathbf{\Lambda})} \mathbf{V}^T\]where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).
- metabci.brainda.algorithms.utils.covariance.matrix_operator(Ci: ndarray, operator: Callable[[ndarray], ndarray], n_jobs: int | None = None) ndarray[source]¶
Apply operator to any matrix.
- Parameters:
Ci (ndarray) – Input positive definite matrix.
operator (callable object) – Operator function or callable object.
n_jobs (int, optional) – the number of jobs to use.
- Returns:
Co – Operated matrix.
- Return type:
ndarray
- Raises:
ValueError – If Ci is not positive definite.
Notes
\[\begin{split}\mathbf{Ci} = \mathbf{V} \left( \mathbf{\Lambda} \right) \mathbf{V}^T \\ \mathbf{Co} = \mathbf{V} operator\left( \mathbf{\Lambda} \right) \mathbf{V}^T\end{split}\]where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).
- metabci.brainda.algorithms.utils.covariance.nearestPD(A: ndarray) ndarray[source]¶
Find the nearest positive-definite matrix to input.
- Parameters:
A (ndarray) – Any square matrxi, shape (N, N)
- Returns:
A3 – positive-definite matrix to A
- Return type:
ndarray
Notes
A Python/Numpy port of John D’Errico’s nearestSPD MATLAB code [1], which origins at [2].
References
- metabci.brainda.algorithms.utils.covariance.powm(Ci: ndarray, alpha: float, n_jobs: int | None = None)[source]¶
Return the matrix power of a covariance matrix.
- Parameters:
Ci (ndarray) – Input positive-definite matrix.
alpha (float) – Exponent.
- Returns:
Power matrix of Ci.
- Return type:
ndarray
Notes
\[\mathbf{C} = \mathbf{V} \left( \mathbf{\Lambda} \right)^{\alpha} \mathbf{V}^T\]where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).
- metabci.brainda.algorithms.utils.covariance.sqrtm(Ci: ndarray, n_jobs: int | None = None)[source]¶
Return the matrix square root of a covariance matrix.
- Parameters:
Ci (ndarray) – Input positive-definite matrix.
- Returns:
Square root matrix of Ci.
- Return type:
ndarray
Notes
\[\mathbf{C} = \mathbf{V} \left( \mathbf{\Lambda} \right)^{1/2} \mathbf{V}^T\]where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).