pyriemann.utils.covariance.covariance_mest¶
- pyriemann.utils.covariance.covariance_mest(X, m_estimator, *, init=None, tol=0.01, n_iter_max=50, assume_centered=False, q=0.9, nu=5, norm='trace')¶
Robust M-estimators.
Robust M-estimator based covariance matrix [1], computed by fixed point algorithm.
For an input time series \(X \in \mathbb{R}^{c \times t}\), composed of \(c\) channels and \(t\) time samples,
\[C = \frac{1}{t} \sum_i \varphi(X[:,i]^H C^{-1} X[:,i]) X[:,i] X[:,i]^H\]where \(\varphi()\) is a function allowing to weight the squared Mahalanobis distance depending on the M-estimator type: Huber, Student-t or Tyler.
- Parameters:
- Xndarray, shape (n_channels, n_times)
Multi-channel time-series, real or complex-valued.
- m_estimator{“hub”, “stu”, “tyl”}
Type of M-estimator:
- initNone | ndarray, shape (n_channels, n_channels), default=None
A matrix used to initialize the algorithm. If None, the sample covariance matrix is used.
- tolfloat, default=10e-3
The tolerance to stop the fixed point estimation.
- n_iter_maxint, default=50
The maximum number of iterations.
- assume_centeredbool, default=False
If True, data will not be centered before computation. Useful when working with data whose mean is almost, but not exactly zero. If False, data will be centered before computation.
- qfloat, default=0.9
Using Huber’s M-estimator, q is the percentage in (0, 1] of inputs deemed uncorrupted, while (1-q) is the percentage of inputs treated as outliers w.r.t a Gaussian distribution. This estimator is a trade-off between Tyler’s estimator (q=0) and the sample covariance matrix (q=1).
- nuint, default=5
Using Student-t’s M-estimator, degree of freedom for t-distribution (strictly positive). This estimator is a trade-off between Tyler’s estimator (nu->0) and the sample covariance matrix (nu->inf).
- norm{“trace”, “determinant”}, default=”trace”
Using Tyler’s M-estimator, the type of normalization:
“trace”: trace of covariance matrix is
n_channels
;“determinant”: determinant of covariance matrix is 1.
- Returns:
- covndarray, shape (n_channels, n_channels)
Robust M-estimator based covariance matrix.
Notes
Added in version 0.4.
References
[1]Complex Elliptically Symmetric Distributions: Survey, New Results and Applications E. Ollila, D.E. Tyler, V. Koivunen, H.V. Poor. IEEE Transactions on Signal Processing, 2012.
[2]Robust antenna array processing using M-estimators of pseudo-covariance E. Ollila, V. Koivunen. PIMRC, 2003.
[3]Influence functions for array covariance matrix estimators E. Ollila, V. Koivunen. IEEE SSP, 2003.
[4]A distribution-free M-estimator of multivariate scatter D.E. Tyler. The Annals of Statistics, 1987.