pyriemann.classification.class_distinctiveness¶
- pyriemann.classification.class_distinctiveness(X, y, exponent=1, metric='riemann', return_num_denom=False)¶
Measure class distinctiveness between classes of SPD matrices.
For two class problem, the class distinctiveness between class \(K_1\) and \(K_2\) on the manifold of SPD matrices is quantified as [1]:
\[\mathrm{classDis}(K_1, K_2, p) = \frac{d \left( \mathbf{M}_{K_1}, \mathbf{M}_{K_2} \right)^p} {\frac{1}{2} \left( \sigma_{K_1}^p + \sigma_{K_2}^p \right)}\]where \(\mathbf{M}_K\) is the center of class \(K\), ie the mean of matrices from class \(K\) (see
pyriemann.utils.mean.mean_covariance()
); and \(\sigma_K\) is the class dispersion, ie the mean of distances between matrices from class \(K\) and their center of class \(\mathbf{M}_K\):\[\sigma_K^p = \frac{1}{m} \sum_{i=1}^m d \left(X_i, \mathbf{M}_K \right)^p\]and \(p\) is the exponentiation of the distance.
For more than two classes, it is quantified as:
\[\mathrm{classDis} \left( \left\{K_{j} \right\}_{j=1}^c, p \right) = \frac{\sum_{j=1}^c d\left(\mathbf{M}_{K_{j}},\bar{\mathbf{M}}\right)^p} {\sum_{j=1}^c \sigma_{K_{j}}^p}\]where \(\bar{\mathbf{M}}\) is the mean of centers of class of all \(c\) classes.
- Parameters:
- Xndarray, shape (n_matrices, n_channels, n_channels)
Set of SPD matrices.
- yndarray, shape (n_matrices,)
Labels for each matrix.
- exponentint, default=1
Parameter for exponentiation of distances, corresponding to p in the above equations:
exponent = 1 gives the formula originally defined in [1];
exponent = 2 gives the Fisher criterion generalized on the manifold, ie the ratio of the variance between the classes to the variance within the classes.
- metricstring | dict, default=’riemann’
The type of metric used for centroid and distance estimation. See mean_covariance for the list of supported metric. The metric could be a dict with two keys, mean and distance in order to pass different metrics for the centroid estimation and the distance estimation. The original equation of class distinctiveness in [1] uses ‘riemann’ for both the centroid estimation and the distance estimation but you can customize other metrics with your interests.
- return_num_denombool, default=False
Whether to return numerator and denominator of class_dis.
- Returns:
- class_disfloat
Class distinctiveness value.
- numfloat
Numerator value of class_dis. Returned only if return_num_denom is True.
- denomfloat
Denominator value of class_dis. Returned only if return_num_denom is True.
Notes
New in version 0.4.
References
[1] (1,2,3)Defining and quantifying users’ mental imagery-based BCI skills: a first step F. Lotte, and C. Jeunet. Journal of neural engineering, 15(4), 046030, 2018.