conpy.stats.cluster_permutation_test

conpy.stats.cluster_permutation_test(cond1, cond2, cluster_threshold, src, alpha=0.05, tail=0, n_permutations=1024, max_spread=0.013, cluster_method='single', seed=None, return_details=False, n_jobs=1, verbose=None)

Find significant bundles of connections using a permutation test.

This is a variation on the cluster permutation test described in [1].

First, connections are thresholded using a paired 2-sided t-test. Any connections that survive the threshold are grouped into “bundles”. A bundle is a group of connections which start and end points are close together. Then, for each bundle, the sum of the t-values of its connections is evaluated against those obtained from using the same procedure on random permutations of the data. For further information, see [2].

Parameters:

cond1list of VertexConnectivity

For each subject, the connectivity object corresponding to the first experimental condition. Each connectivity object should define the same connections.

cond2list of VertexConnectivity

For each subject, the connectivity object corresponding to the second experimental condition. Each connectivity object should define the same connections.

cluster_thresholdfloat

The threshold to use for forming the intial bundles. Only connections with a t-value that is either higher than cluster_threshold or lower than -cluster_threshold are kept.

tail-1 | 0 | 1

Which “tail” of the distribution of the test statistic to use:

-1: the hypothesis is that cond1 < cond2.

0: the hypothesis is that cond1 != cond2. 1: the hypothesis is that cond1 > cond2.

Defaults to 0, meaning a two-tailed test.

srcinstance of SourceSpace

The source space for which the connectivity is defined.

alphafloat

The p-value to use for null-hypothesis testing. Using random permutations, the distribution of t-values is estimated. Bundles with a t-value in the requested percentile will be deemed significant. Defaults to 0.05.

n_permutationsint

The number of random permutations to use to estimate the distribution of t-values. Defaults to 1024.

max_spreadfloat

Maximum amount the position (in metres) of the start and end points of the connections may vary in order for them to be considered part of the same “bundle”. Defaults to 0.013.

cluster_methodstr

Linkage method for fclusterdata. Defaults to ‘single’. See documentation for scipy.cluster.hierarchy.fclusterdata for for more information.

seedint | None

The seed to use for the random number generator. Use this to reproduce a specific result. Defaults to None so a different seed is used every time.

return_detailsbool

Whether to return details about the bundles and the permulation stats. Defaults to False.

n_jobsint

Number of jobs to run in parallel. Note that a copy of cond1 and cond2 will be made for each job in memory. Defaults to 1.

verbosebool | str | int | None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns:

connection_indicesndarray, shape (n_connections,)

Indices of the connections that are part of a significant bundle.

bundleslist of list of int (optional)

For each found bundle, the indices of the connections that are part of the bundle. Only returned when return_details=True is specified.

bundle_tsndarray, shape (n_bundles,) (optional)

For each found bundle, the sum of the t-values for all connections that are part of the bundle. These are the t-values that were used to determine the initial threshold for the connections. They are not indicative of the null-hypothesis. Only returned when return_details=True is specified.

bundle_psndarray, shape (n_bundles,) (optional)

For each found bundle, the p-value based on the permutation test, indicative for the likelyhood that the null-hypothesis holds. Only returned when return_details=True is specified.

H0ndarray, shape (n_permutations,) (optional)

The maximum observed t-value during each random permutation. Only returned when return_details=True is specified.

References

[1]

Maris/Oostenveld (2007), “Nonparametric statistical testing of EEG- and MEG-data” Journal of Neuroscience Methods, Vol. 164, No. 1., pp. 177-190. doi:10.1016/j.jneumeth.2007.03.024.

[2]

van Vliet, M., Liljeström, M., Aro, S., Salmelin, R., & Kujala, J. (2018). Analysis of functional connectivity and oscillatory power using DICS: from raw MEG data to group-level statistics in Python. bioRxiv, 245530, 1-25. https://doi.org/10.1101/245530