mne.stats.spatio_temporal_cluster_1samp_test

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

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

This function provides a convenient wrapper for mne.stats.permutation_cluster_1samp_test(), for use with data organized in the form (observations × time × space), (observations × frequencies × space), or optionally (observations × time × frequencies × space). For details, see [1][2].

Parameters:

Xarray, shape (n_observations, p[, q], n_vertices)

The data to be clustered. The first dimension should correspond to the difference between paired samples (observations) in two conditions. The second, and optionally third, dimensions correspond to the time or time-frequency data. And, the last dimension should be spatial.

thresholdfloat | dict | None

The so-called “cluster forming threshold” in the form of a test statistic (note: this is not an alpha level / “p-value”). If numeric, vertices with data values more extreme than threshold will be used to form clusters. If None, a t-threshold will be chosen automatically that corresponds to a p-value of 0.05 for the given number of observations (only valid when using a t-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 [3]). See Notes for an example on how to compute a threshold based on a particular p-value for one-tailed or two-tailed tests.

n_permutationsint | ‘all’

The number of permutations to compute. Can be ‘all’ to perform an exact test.

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

adjacencyscipy.sparse.spmatrix | None | False

Defines adjacency between locations in the data, where “locations” can be spatial vertices, frequency bins, time points, etc. For spatial vertices (i.e. sensor space data), see mne.channels.find_ch_adjacency() or mne.spatial_inter_hemi_adjacency(). For source space data, see mne.spatial_src_adjacency() or mne.spatio_temporal_src_adjacency(). If False, assumes no adjacency (each location is treated as independent and unconnected). If None, a regular lattice adjacency is assumed, connecting each spatial location to its neighbor(s) along the last dimension of X. If adjacency 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.shape[-1] (n_vertices) or X.shape[-1] * X.shape[-2] (n_times * n_vertices) or (optionally) X.shape[-1] * X.shape[-2] * X.shape[-3] (n_times * n_freqs * n_vertices). If spatial adjacency is uniform in time, it is recommended to use a square matrix with dimension X.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.

n_jobsint | None

The number of jobs to run in parallel. If -1, it is set to the number of CPU cores. Requires the joblib package. None (default) is a marker for ‘unset’ that will be interpreted as n_jobs=1 (sequential execution) unless the call is performed under a joblib.parallel_config context manager that sets another value for n_jobs.

seedNone | int | instance of RandomState

A seed for the NumPy random number generator (RNG). If None (default), the seed will be obtained from the operating system (see RandomState for details), meaning it will most likely produce different output every time this function or method is run. To achieve reproducible results, pass a value here to explicitly initialize the RNG with a defined state.

max_stepint

Maximum distance between samples along the second axis of X to be considered adjacent (typically the second axis is the “time” dimension). Only used when adjacency has shape (n_vertices, n_vertices), that is, when adjacency is only specified for sensors (e.g., via mne.channels.find_ch_adjacency()), and not via sensors and further dimensions such as time points (e.g., via an additional call of mne.stats.combine_adjacency()).

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 t-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 within a list. If 'mask', returns a list of boolean arrays, each with the same shape as the input data (or slices if the shape is 1D and adjacency is None), with True values indicating locations that are part of a cluster. If 'indices', returns a list of tuple of ndarray, where each ndarray contains the indices of locations that together form the given cluster along the given dimension. 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.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

t_obsarray, shape (p[, q], n_vertices)

T-statistic observed for all variables.

clusterslist

List type defined by out_type above.

cluster_pvarray

P-value for each cluster.

H0array, shape (n_permutations,)

Max cluster level stats observed under permutation.

Notes

For computing a threshold based on a p-value, use the conversion from scipy.stats.rv_continuous.ppf():

pval = 0.001  # arbitrary
df = n_observations - 1  # degrees of freedom for the test
thresh = scipy.stats.t.ppf(1 - pval / 2, df)  # two-tailed, t distribution

For a one-tailed test (tail=1), don’t divide the p-value by 2. For testing the lower tail (tail=-1), don’t subtract pval from 1.

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]

Jona Sassenhagen and Dejan Draschkow. Cluster-based permutation tests of meg/eeg data do not establish significance of effect latency or location. Psychophysiology, 56(6):e13335, 2019. doi:10.1111/psyp.13335.

[3]

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.

Examples using mne.stats.spatio_temporal_cluster_1samp_test

Permutation t-test on source data with spatio-temporal clustering

Permutation t-test on source data with spatio-temporal clustering