# 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 A and B on the manifold of SPD matrices is quantified as [1]:

$\mathrm{classDis}(A, B, p) = \frac{d \left(\bar{X}^{A}, \bar{X}^{B}\right)^p} {\frac{1}{2} \left( \sigma_{X^{A}}^p + \sigma_{X^{B}}^p \right)}$

where $$\bar{X}^{K}$$ is the center of class K, ie the mean of matrices from class K (see pyriemann.utils.mean.mean_covariance()) and $$\sigma_{X^{K}}$$ is the class dispersion, ie the mean of distances between matrices from class K and their center of class $$\bar{X}^{K}$$:

$\sigma_{X^{K}}^p = \frac{1}{m} \sum_{i=1}^m d \left(X_i, \bar{X}^{K}\right)^p$

For more than two classes, it is quantified as:

$\mathrm{classDis}\left(\left\{K_{j}\right\}, p\right) = \frac{\sum_{j=1}^{c} d\left(\bar{X}^{K_{j}}, \tilde{X}\right)^p} {\sum_{j=1}^{c} \sigma_{X^{K_{j}}}^p}$

where $$\tilde{X}$$ is the mean of centers of class of all $$c$$ classes and $$p$$ is the exponentiation of the distance measure named exponent at the input of this function.

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.3.1.

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.