mne.stats.spatio_temporal_cluster_test

mne.stats.spatio_temporal_cluster_test(X, threshold=None, n_permutations=1024, tail=0, stat_fun=None, connectivity=None, verbose=None, n_jobs=1, seed=None, max_step=1, spatial_exclude=None, step_down_p=0, t_power=1, out_type='indices', check_disjoint=False, buffer_size=1000)[source]

Non-parametric cluster-level test for spatio-temporal data.

This function provides a convenient wrapper for mne.stats.permutation_cluster_test(), for use with data organized in the form (observations × time × space). See 1 for more information.

Parameters
Xlist of array, shape (n_observations, n_times, n_vertices)

The data to be clustered. Each array in X should contain the observations for one group. The first dimension of each array is the number of observations from that group (and may vary between groups); the remaining dimensions (times and vertices) should match across all groups.

thresholdfloat | dict | None

If numeric, vertices with data values more extreme than threshold will be used to form clusters. If threshold is None, an F-threshold will be chosen automatically that corresponds to a p-value of 0.05 for the given number of observations (only valid when using an F-statistic). If threshold is a dict (with keys 'start' and 'step') then threshold-free cluster enhancement (TFCE) will be used (see the TFCE example and 2).

n_permutationsint

The number of permutations to compute.

tailint

If tail is 1, the statistic is thresholded above threshold. If tail is -1, the statistic is thresholded below threshold. If tail is 0, the statistic is thresholded on both sides of the distribution.

stat_funcallable() | None

Function called to calculate the test statistic. Must accept 1D-array as input and return a 1D array. If None (the default), uses mne.stats.f_oneway().

connectivityscipy.sparse.spmatrix | None | False

Defines connectivity between locations in the data, where “locations” can be spatial vertices, frequency bins, etc. If False, assumes no connectivity (each location is treated as independent and unconnected). If None, a regular lattice connectivity is assumed, connecting each spatial location to its neighbor(s) along the last dimension of each group X[k]. If connectivity is a matrix, it is assumed to be symmetric (only the upper triangular half is used) and must be square with dimension equal to X[k].shape[-1] (n_vertices) or X[k].shape[-1] * X[k].shape[-2] (n_times * n_vertices). If spatial connectivity is uniform in time, it is recommended to use a square matrix with dimension X[k].shape[-1] (n_vertices) to save memory and computation, and to use max_step to define the extent of temporal adjacency to consider when clustering.

verbosebool, str, int, or None

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

n_jobsint

The number of jobs to run in parallel (default 1). Requires the joblib package.

seedNone | int | instance of RandomState

If seed is an int, it will be used as a seed for RandomState. If None, the seed will be obtained from the operating system (see RandomState for details). Default is None.

max_stepint

Maximum distance along the second dimension (typically this is the “time” axis) between samples that are considered “connected”. Only used when connectivity has shape (n_vertices, n_vertices).

spatial_excludelist of int or None

List of spatial indices to exclude from clustering.

step_down_pfloat

To perform a step-down-in-jumps test, pass a p-value for clusters to exclude from each successive iteration. Default is zero, perform no step-down test (since no clusters will be smaller than this value). Setting this to a reasonable value, e.g. 0.05, can increase sensitivity but costs computation time.

t_powerfloat

Power to raise the statistical values (usually F-values) by before summing (sign will be retained). Note that t_power=0 will give a count of locations in each cluster, t_power=1 will weight each location by its statistical score.

out_type‘mask’ | ‘indices’

Output format of clusters. If 'mask', returns boolean arrays the same shape as the input data, with True values indicating locations that are part of a cluster. If 'indices', returns a list of lists, where each sublist contains the indices of locations that together form a cluster. Note that for large datasets, 'indices' may use far less memory than 'mask'. Default is 'indices'.

check_disjointbool

Whether to check if the connectivity matrix can be separated into disjoint sets before clustering. This may lead to faster clustering, especially if the second dimension of X (usually the “time” dimension) is large.

buffer_sizeint | None

Block size to use when computing test statistics. This can significantly reduce memory usage when n_jobs > 1 and memory sharing between processes is enabled (see mne.set_cache_dir()), because X will be shared between processes and each process only needs to allocate space for a small block of locations at a time.

Returns
t_obsarray, shape (n_times * n_vertices,)

Statistic (t by default) observed for all variables.

clusterslist

List type defined by out_type above.

cluster_pv: array

P-value for each cluster.

H0array, shape (n_permutations,)

Max cluster level stats observed under permutation.

References

1

Eric Maris and Robert Oostenveld. Nonparametric statistical testing of EEG- and MEG-data. Journal of Neuroscience Methods, 164(1):177–190, 2007. doi:10.1016/j.jneumeth.2007.03.024.

2

Stephen M. Smith and Thomas E. Nichols. Threshold-free cluster enhancement: addressing problems of smoothing, threshold dependence and localisation in cluster inference. NeuroImage, 44(1):83–98, 2009. doi:10.1016/j.neuroimage.2008.03.061.