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