pyriemann.stats.PermutationDistance

class pyriemann.stats.PermutationDistance(n_perms=100, metric='riemann', mode='pairwise', n_jobs=1, random_state=42, estimator=None)

Permutation test based on distance.

Perform a permutation test based on distance. You have the choice of 3 different statistic:

  • ‘pairwise’ :

    the statistic is based on paiwire distance as descibed in [1]. This is the fastest option for low sample size since the pairwise distance matrix does not need to be estimated for each permutation.

  • ‘ttest’ :

    t-test based statistic obtained by the ration of the distance between each riemannian centroid and the group dispersion. The means have to be estimated for each permutation, leading to a slower procedure. However, this can be used for high sample size.

  • ‘ftest’:

    f-test based statistic estimated using the between and within group variability. As for the ‘ttest’ stats, group centroid are estimated for each permutation.

Parameters:
n_permsint, default=100

The number of permutation. The minimum should be 20 for a resolution of 0.05 p-value.

metricstring | dict, default=’riemann’

The type of metric used for centroid and distance estimation. see distance anb 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 metric for the centroid estimation and the distance estimation. Typical usecase is to pass ‘logeuclid’ metric for the mean in order to boost the computional speed and ‘riemann’ for the distance in order to keep the good sensitivity for the classification.

modestring, default=’pairwise’

Type of statistic to use. could be ‘pairwise’, ‘ttest’ of ‘ftest’

n_jobsinteger, default=1

The number of CPUs to use to do the computation. -1 means ‘all CPUs’.

random_stateint, default=42

random state for the permutation test.

estimatorNone or sklearn compatible estimator, default=None

If provided, data are transformed before every permutation. should not be used unless a supervised opperation must be applied on the data. This would be the case for ERP covariance.

See also

PermutationModel

References

[1]

A new method for non-parametric multivariate analysis of variance M. Anderson. Austral ecology, Volume 26, Issue 1, February 2001.

Attributes:
p_value_float

the p-value of the test

scores_list

contain all scores for all permutations. The fist element is the non-permuted score.

__init__(n_perms=100, metric='riemann', mode='pairwise', n_jobs=1, random_state=42, estimator=None)

Init.

plot(nbins=10, range=None, axes=None)

Plot results of the permutation test.

Parameters:
nbinsinteger or array_like or ‘auto’, default=10

If an integer is given, bins + 1 bin edges are returned, consistently with np.histogram() for numpy version >= 1.3. Unequally spaced bins are supported if bins is a sequence.

rangetuple or None, default=None

The lower and upper range of the bins. Lower and upper outliers are ignored. If not provided, range is (x.min(), x.max()). Range has no effect if bins is a sequence. If bins is a sequence or range is specified, autoscaling is based on the specified bin range instead of the range of x.

axesaxes handle, default=None

Axes handle for matplotlib. if None a new figure will be created.

score(X, y, groups=None)

Score of a permutation.

Parameters:
Xarray-like

The data to fit. Can be, for example a list, or an array at least 2d.

yarray-like

The target variable to try to predict in the case of supervised learning.

test(X, y, groups=None, verbose=True)

Performs the permutation test

Parameters:
Xarray-like

The data to fit. Can be, for example a list, or an array at least 2d.

yarray-like

The target variable to try to predict in the case of supervised learning.

verbosebool, default=True

If true, print progress.