U f{j@s ddlZddlmZmZddlmZddlmZm Z ddl m Z m Z m Z mZmZmZmZmZmZddlmZmZmZdd lmZd[d d Zd d ZddZe red\ddZeddZeddZn eZeZeZeddZ eddZ!eddZ"ddZ#ddZ$d d!Z%d]d"d#Z&d^d$d%Z'd_d'd(Z(d`d*d+Z)d,d-Z*d.d/Z+d0d1Z,d2d3Z-d4d5Z.d6d7Z/d8d9Z0d:d;Z1dadd?Z3d@dAZ4dbdCdDZ5e dcdHdIZ6e dddJdKZ7e dedLdMZ8e dfdNdOZ9dgdPdQZ:e dhdRdSZ;dTdUZsignabs)r1r?t_powerrrr_masked_sum_powermsrDcCst|t|dk|S)Nr)rrA logical_not)datatsteprrr_sum_cluster_datarsrHc Cst|jt}t}|jdkr"dnd}|dkr|g}d||<d}|t|kr||d}t|||||}|||d7}q@t |}| ||q&|S)zForm spatial clusters using neighbor lists. This is equivalent to _get_components with n_times = 1, with a properly reconfigured adjacency matrix (formed as "neighbors" list) rr.r) ronesshapeboolr4sizer$r:extendr<r6) rrrclustersr2t_indsicountr%rrrr_get_clusters_spatialws     rQcCsL||||k<t||d||df||d<tjgtd||d<dS)zReassign cluster numbers.rdtypeN)r concatenatearrayr/)checkrNbasenumrrr _reassigns   rYcs\t|t|}d}tj|ftd}t}t|D]\\}t||}t|D]\}} |||| f<qN|t|7}fdd|D}||7}q4t|dd|dd|ddD]\} } }|| || |dk} | | } | | }t|}|D]P}| ||k}t |}t|||kD]}t | |||q"t | |||qqdd|D}|S) a Directly calculate clusters. This uses knowledge that time points are only adjacent to immediate neighbors for data organized as time x space. This algorithm time increases linearly with the number of time points, compared to with the square for the standard (graph) algorithm. This algorithm creates clusters for each time point using a method more efficient than the standard graph method (but otherwise equivalent), then combines these clusters across time points in a reasonable way. rrRcsg|]}|qSrr.0clr7n_srcrr sz*_get_clusters_st_1step..Nr.rcSsg|]}t|dkr|qSrr$rZrrrr_s ) r$rzerosr/r4 enumeraterQzipuniquer#rY)keepersrn_timesZ enum_offsetrVrNkr?cir\Zcheck1Zcheck2r&Zcheck1_dnZnextsrXZprevsrWprrr]r_get_clusters_st_1steps2    .   rlcCslt|}t|}t}|dt|D].\}}|||||<|||t|q(t|}t|}|}t||\} } tj| j t d} t} t |d||} | j dkrdnd}|dkrh|g}d| |<d}|t|krP||d}t | | || | ||}| || ||| |d}t| | || ||}|||7}|d7}qt| }| ||q| S)a,Directly calculate clusters. This uses knowledge that time points are only adjacent to immediate neighbors for data organized as time x space. This algorithm time increases linearly with the number of time points, compared to with the square for the standard (graph) algorithm. rrRr.Fr)r$r4r6rcrrUrTdivmodrIrJrKarangerLr;r:r<)rfrr)r^rgr(Zkirhvr'rrrNr&r2rOrPr%r,Z these_indsrrrr_get_clusters_st_multisteps:         rpc Cs(t|}|j|}t|d}t|dkr tjgtdg|}t|||f\}}dg} t|trt|g}|g}nLt|} || }|| }| tt |dkdd 7} | t|t | dd| ddD]"\} } t || | ||| <q|dkrt||St|||SngSdS)z"Choose the most efficient version.rrRrNr.)r$rLrrrUr/ unravel_index isinstanceZargsortdiffrr6rdsortrlrp) x_inrr)r^rgZcl_goodsrfrowcolZlimsorderr*endrrr_get_clusters_sts.   $"  rzTcCsrddlm}|dkr$tt|}nddlm}t||j||j }|j |}|j|}|j |} |j } t |d} t || f}t | | f} t |tjt| |jdf}|j||| ff| d}||\} }|rjt|} t|}ddt| |d d D}tjt|td}t|D],\}}|||||||7<q$d dt||D}|S|Sd S) z.rcSsg|]\}}|rt|qSrrrU)r[rhmrrrr_5sN)scipyr|rrnr$Zscipy.sparse.csgraphr} logical_andrvrwrFrJrrTrIrS coo_matrixr#r"r5rbrKrcr6rd)ru adjacencyZ return_listr| componentsr}maskrFrvrwrJidx_r*r+Z comp_listr7comprNrrr_get_componentss4        rFc  sddlm} td|dddgt|}tsttsFtdt fddd Dsdt d d } |t |} | j dkrt d |dkrĈd dkrtdddkrtdt| } n,|dkrt| } ntt| t|  } ~ td | dt} dd}dd}|d krtt| dkrPtdd | fn$tdt| | d| d||ft|j }n g} d} |dkrtj|jtd}|dkrt t| dkstd|dkrt t| dkstdtt}t| D]^\}}t|dkrHt||k|t|| k|g}n0|dkrft||k|g}nt||k|g}|D]@}t |r|t!||||||| }|d7|"|dq|| r |dkrt#|}nt#|| |d}||}D]n}t|t$r|j%|j&}n6t|t'r,t|}n |j(tkrDt)|}nt|}|||||7<qq |r|t*|nt+g}| rt|j |dks|dkr|j,dkrddDnfddt-tDnd dD|}|fS)!aFind all clusters which are above/below a certain threshold. When doing a two-tailed test (tail == 0), only points with the same sign will be clustered together. Parameters ---------- x : 1D array Data threshold : float | dict Where to threshold the statistic. Should be negative for tail == -1, and positive for tail == 0 or 1. Can also be an dict for threshold-free cluster enhancement. tail : -1 | 0 | 1 Type of comparison adjacency : scipy.sparse.coo_matrix, None, or list Defines adjacency between features. The matrix is assumed to be symmetric and only the upper triangular half is used. If adjacency is a list, it is assumed that each entry stores the indices of the spatial neighbors in a spatio-temporal dataset x. Default is None, i.e, a regular lattice adjacency. False means no adjacency. max_step : int If adjacency is a list, this defines the maximal number of steps between vertices along the second dimension (typically time) to be considered adjacent. include : 1D bool array or None Mask to apply to the data of points to cluster. If None, all points are used. partitions : array of int or None An array (same size as X) of integers indicating which points belong to each partition. t_power : float 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 nodes in each cluster, t_power == 1 will weight each node by its statistical score. show_info : bool If True, display information about thresholds used (for TFCE). Should only be done for the standard permutation. Returns ------- clusters : list of slices or list of arrays (boolean masks) We use slices for 1D signals and mask to multidimensional arrays. sums : array Sum of x values in clusters. r)ndimagetailr.rzLthreshold must be a number, or a dict for threshold-free cluster enhancementc3s|]}|kVqdSr=r)r[key) thresholdrr wsz!_find_clusters..)r*stepz9threshold, if dict, must have at least "start" and "step"Tz7No finite values found in the observed statistic valuesr*z.threshold["start"] must be <= 0 for tail == -1rz,threshold["step"] must be < 0 for tail == -1h_powerre_power?zWthreshold["start"] (%s) is more extreme than data statistics with most extreme value %sz[Using %d thresholds from %0.2f to %0.2f for TFCE computation (h_power=%0.2f, e_power=%0.2f)FNrR)rrz+Thresholds must be monotonically increasingz+Thresholds must be monotonically decreasingcSsg|]}t||dqSrslicer[r?rrrr_sz"_find_clusters..csg|]}|kqSr)ravel)r[r7)rNrrr_scSsg|]}t|gqSrrrrrrr_s).rrrrZ asanyarrayZisscalarrrdict TypeErrorallKeyErrorisfiniterL RuntimeError ValueErrorr#r"rnfloatgetr$r r inforbrIrJrKrsr4rcrany_find_clusters_1dir_partsr6rBrr+r*tuplerSr>rTrUndimr5)r1rrrr)include partitionsrC show_inforZtfceZuse_xr+Z thresholdsrrZscoressumstiZthreshZx_insruouthr?Zlen_cr)rNrr_find_clusters;s3                                 rc Cs|dkr t||||||\}}njt}t}tt|dD]@} t||| k} t|| ||||} || d7}|| dq>t|}||fS)z?Deal with partitions, and pass the work to _find_clusters_1dir.Nrr)_find_clusters_1dirr4r5rr"rr6rT) r1rurr)rrCrrNrpZx_irrrrrs      rcsddlm}|dkr||\}}jdkr|||} | sFt} nPttd|d} dkrr|j|| d} n$|jt t || d} n~t} t |} t|D]d} || dk} | | dkrt| | | <qtt | t | | | <qnjdkr,tdt||jsD|dkrPt||} n"t|trjt|||} ntddkrfd d | D} nfd d | D} | t| fS) z'Actually call the clustering algorithm.rr{Nr)indexz.csg|]}t|qSr)rDrrCr1rrr_#s)rr|labelrZ find_objectsr4r5r>rrArBemptyr6r ExceptionrrZspmatrixrrzrZ atleast_1d)r1rurr)rCrr|labelsZn_labelsrNrrrr?rrrrsF           rcCs4t|D]&\}}tj|td||<d|||<q|S)>Convert to the old format of clusters, which were bool arrays.rRT)rcrrbrK)rZn_totrir?rrr_cluster_indices_to_mask(srcCst|D]\}}t|tjr2t||||<qt|trRt|j|j ||<qt|t sht t |t |}t|D]:\}}t|trt|j|j ||<qxt|d||<qxt |||<q|S)rr)rcrrrndarrayrreshaperrnr*r+rAssertionErrortyper4)rrJrir?r7ccrrr_cluster_mask_to_indices0s   rcs`|dkr"tfdd|D}n:|dkrDtfdd|D}ntfdd|D}|S)zGet p-values from stats values given an H0 distribution. For each stat compute a p-value as percentile of its statistics within all statistics in surrogate data r.csg|]}t|kqSrrmeanr[r'H0rrr_Ksz(_pval_from_histogram..rcsg|]}t|kqSrrrrrrr_Mscs"g|]}ttt|kqSr)rrrBrrrrr_Osr)TrrZpvalrrr_pval_from_histogramCs rcsddlm}|stdjd|kr6njt|jd\}}||ksZ|dkrptdjd|ffddt t j dDS)Nrr{z?If adjacency matrix is given, it must be a SciPy sparse matrix.aadjacency (len %d) must be of the correct size, i.e. be equal to or evenly divide the number of tests (%d). If adjacency was computed for a source space, try using the fwd["src"] or inv["src"] as some original source space vertices can be excluded during forward computationcs*g|]"}jj|j|dqSr)rindptrrrrrr_gsz$_setup_adjacency..r) rr|issparserrJZtocoormZ transposeZtocsrr5r$r)rn_testsrgr|Z got_timesmodrrr_setup_adjacencyTs"     rc sj\}}dk r|krdtjt| tjd}dk rNfdd|D}t| D]<\}dk sltfdd|D}dkrfdd|D}||}ntj|jd}td|D]p}t |||}t|D]0\}}||||f||ddd|f<q||}|d|||||<q|dkr@| |_t |||||||| d}|d}t|dkr~t |||<nd||<| |dqV|S) NrRcs(g|] }tjt|fjdqS)rR)rrr$rSr[r)X_full buffer_sizerrr_zsz$_do_permutations..csg|] }|qSrrr)rxrrr_scsg|]}|ddfqSr=r)r[r)rrrr_srrrr)rrrrCr) rJrrr$doublercrrSr5r#rr"update)rslicesrrrstat_funr)rrrCorders sample_shaper progress_barn_sampn_varsmax_cluster_sumsZX_bufferseed_idxZidx_shuffle_listZX_shuffle_list t_obs_surrpos n_var_looprrtmprperm_clusters_sumsr)rrrxr_do_permutationsmsJ     rc Cs|j\}}|dkst| dk r*|| kr*d} tjt| tjd}| dk rZtj|| f|jd}t| D]\}}t|tj s|t|j |kstd|dddf t d}t tt|dstd| dkr|jjr||9}||}||9}n |||}ntj||jd}td|| D]d}t|| ||}||dd|||f|ddd|f<||}|d|||||<q|dkr| |_t|||||||| d}|d}t|dkrtt|}||||<nd||<| |dqb|S)NrRrrzsigns from rng must be +/- 1rr)rJrrrr$rrSrcrrrrLastyper/requalrBrflagsZ writeabler5r#rr0r)Xrrrrrr)rrrCrrrrrrrZ X_flip_bufferrrxsignsrrrrrrZidx_maxrrr_do_1samp_permutationssT     rcCsd|}t||ft|}|||d}|||ddf<td|D]:}|ddd|df}||d||f<|||d|f<qH|S)aNdim permutations with repetitions of (a,b). Returns an array with all the possible permutations with repetitions of (0,1) in ndim dimensions. The array is shaped as (2**ndim,ndim), and is ordered with the last index changing fastest. For examble, for ndim=3: Examples -------- >>> bin_perm_rep(3) array([[0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 1, 1], [1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 1, 1]]) rNrr)rrrfillr5)rabZnpermsZpermsZ half_pointjZhalf_colrrr bin_perm_reps rc s<d|dkd}d}t|tr6|dkr2td|}t|}||kr`d}td|d}n҈dkr|j||dd d }fd d |D}nt|dft}i}d}|dk} ||dkr2t|j | d dk t} | |kr| ||d| f<|dkr | dkr d||||<d|| <|d7}q|||fS)zGet the 1samp orders.rrrrz(n_permutations as a string must be "all"z (exact test)F)replacecs&g|]}tjt|dtdqS)rrR)rZfromiterZ binary_reprr/r n_samplesrrr_'sz%_get_1samp_orders..)rLrN) rrstrrr/rchoicerrbruniformr) rn_permutationsrrngZ max_permsextrarhashesr7Z use_samplesrrrr_get_1samp_orderss8    rc(std| ddgtddddgttsttdkrDdksddkrTdksddkrtdkrttdfd d |D}|djd}|djd}|djdd  |D]}|jdd  krtd qd d |D}|djd}d k rdk rt||| d k r.| j|ks.td |}t|t j dt dt |t |fd k rt |}td|D]* fdd |D|<qt ||kstdd |jt  krtd|j fd ksdkr |_| d k r t | }nd }| dkrNd k rNdk rNt|nd t dt|| dd }|\}} |_ttr||jt |}t dt|dt|d k rdk r| dkrt||}n| dkrt||j}d}t|~t|dkrFt}|dd t||\}}}nrt |}t!}t j"|dddd |D}t #dgt $| fdd tt|D fdd t|dD}t%||dd\}}t|dkrtd |t &gt &gt &gfSd}d}d } d}!|dkr|d k rD| d k r>t '|| n|n| t(tt|d!|d"@| fd#d$t)||dd%D}"W5QRXdkr| }#n dkr|}#n t*|}#|"+d|#gt "|"}"t ,d&t-||"}$t .|$| kd}%|%j|}|%j}t j/|t0d'} |%D]}&d| ||&<q>d krldk rl | _|!d7}!| dkr|!dkrd(nd}'t d)|!||'t|fqt1| }|||$|"fS)*zAux Function. Note. X is required to be a list. Depending on the length of X either a 1 sample t-test or an F test / more sample permutation scheme is elicited. out_typerrrr.rrz4incompatible tail and threshold signs, got %s and %scSs,g|]$}|jdkr$|ddtjfn|qS)rN)rrZnewaxisr[r1rrrr_Tsz-_permutation_cluster_test..Nz#All samples mush have the same sizecSs"g|]}t||jddfqS)rr.)rrrJrrrrr_^sFz&exclude must be the same shape as X[0]zreturn value of stat_funzstat_fun(H1): min=%f max=%fcs$g|]}|ddfqSr=rr)rrrrr_rszVProvided stat_fun does not treat variables independently. Setting buffer_size to None.zQt_obs.shape %s provided by stat_fun %s is not compatible with the sample shape %sTuRunning initial clustering …)r)rrrCrzFound z clusterrZaxiscSsg|]}|jdqSr`r~rrrrr_scs"g|]}t||dqSrr)r[rh) splits_idxrrr_scsg|]}tqSr)Z permutationr$)r[r)rrrrr_s)r z?No clusters found, returning empty H0, clusters, and cluster_pvZ Permuting)iterableZmesgc3s:|]2\}}    ||VqdSr=)Zsubset)r[rrx)rrrr)my_do_perm_funcrrrrrrCr this_includerrrrs z,_permutation_cluster_test..)rzComputing cluster p-valuesrRz additional z[Step-down-in-jumps iteration #%i found %i %scluster%s to exclude from subsequent iterations)2rrrrrrrJrrLrrrr rr#r"Z zeros_liker5Zalltruer prodrE_get_partitions_from_adjacencyrrrAr$rrrrrrr/rrTr6ZcumsumrrUrr r rBinsertdebugrrrIrK_reshape_clusters)(rrrrrrn_jobsseedr)exclude step_down_prCrcheck_disjointrrrgr1rt_obsZ t_obs_bufferrrrNZ cluster_statsrZ do_perm_funcrZn_samples_per_conditionparallelZ n_removedZ total_removedZstep_down_includeZ n_step_downsrorigZ cluster_pvZ to_removerZa_textr)rrrr)rrrrrrrrrrCrrrr_permutation_cluster_test@s$                            &             rwithinc CsTddlm}|dkr|jj}|dkr|dk rB|tk rBtd|fdd|dk}t|}|||d }t|dkr~| }t d ||dkrtn|}n|d kst |j j}|dkr:|dk r|tk rtd |fn|dkrtd d}t|d} td d |Dt|} |d|| | }t d ||dkrHtn|}||fS)z(Check the stat_fun and threshold values.r)statsrNzQAutomatic threshold is only valid for stat_fun=None (or ttest_1samp_no_p), got %s皙?rzUsing a threshold of {:.6f}betweenzIAutomatic threshold is only valid for stat_fun=None (or f_oneway), got %sz4Ignoring argument "tail", performing 1-tailed F-testcSsg|] }t|qSrrarrrrr_sz_check_fun..?)rrr'ppfrr r$rrAr rformatrfrr>) rrrrkindrrp_threshrdfnZdfdrrr _check_funs>    rrcCs:t||||d\}}t|||||||||| | | | | |dS)aCluster-level statistical permutation test. For a list of :class:`NumPy arrays ` of data, calculate some statistics corrected for multiple comparisons using permutations and cluster-level correction. Each element of the list ``X`` should contain the data for one group of observations (e.g., 2D arrays for time series, 3D arrays for time-frequency power values). Permutations are generated with random partitions of the data. For details, see :footcite:p:`MarisOostenveld2007,Sassenhagen2019`. Parameters ---------- X : list of array, shape (n_observations, p[, q][, r]) 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; remaining dimensions comprise the size of a single observation. For example if ``X = [X1, X2]`` with ``X1.shape = (20, 50, 4)`` and ``X2.shape = (17, 50, 4)``, then ``X`` has 2 groups with respectively 20 and 17 observations in each, and each data point is of shape ``(50, 4)``. Note: that the *last dimension* of each element of ``X`` should correspond to the dimension represented in the ``adjacency`` parameter (e.g., spectral data should be provided as ``(observations, frequencies, channels/vertices)``). %(threshold_clust_f)s %(n_permutations_clust_int)s %(tail_clust)s %(stat_fun_clust_f)s %(adjacency_clust_n)s %(n_jobs)s %(seed)s %(max_step_clust)s %(exclude_clust)s %(step_down_p_clust)s %(f_power_clust)s %(out_type_clust)s %(check_disjoint_clust)s %(buffer_size_clust)s %(verbose)s Returns ------- F_obs : array, shape (p[, q][, r]) Statistic (F by default) observed for all variables. clusters : list List type defined by out_type above. cluster_pv : array P-value for each cluster. H0 : array, shape (n_permutations,) Max cluster level stats observed under permutation. Notes ----- %(threshold_clust_f_notes)s References ---------- .. footbibliography:: rrrrrrrrrr)r r rCrr rrrrrrrrrrrr)r r rCrr rr rrrpermutation_cluster_test$s$Ar!cCs:t||||\}}t|g||||||||| | | | | |dS)a Non-parametric cluster-level paired t-test. For details, see :footcite:p:`MarisOostenveld2007,Sassenhagen2019`. Parameters ---------- X : array, shape (n_observations, p[, q][, r]) The data to be clustered. The first dimension should correspond to the difference between paired samples (observations) in two conditions. The subarrays ``X[k]`` can be 1D (e.g., time series), 2D (e.g., time series over channels), or 3D (e.g., time-frequencies over channels) associated with the kth observation. For spatiotemporal data, see also :func:`mne.stats.spatio_temporal_cluster_1samp_test`. %(threshold_clust_t)s %(n_permutations_clust_all)s %(tail_clust)s %(stat_fun_clust_t)s %(adjacency_clust_1)s %(n_jobs)s %(seed)s %(max_step_clust)s %(exclude_clust)s %(step_down_p_clust)s %(t_power_clust)s %(out_type_clust)s %(check_disjoint_clust)s %(buffer_size_clust)s %(verbose)s Returns ------- t_obs : array, shape (p[, q][, r]) T-statistic observed for all variables. clusters : list List type defined by out_type above. cluster_pv : array P-value for each cluster. H0 : array, shape (n_permutations,) Max cluster level stats observed under permutation. Notes ----- From an array of paired observations, e.g. a difference in signal amplitudes or power spectra in two conditions, calculate if the data distributions in the two conditions are significantly different. The procedure uses a cluster analysis with permutation test for calculating corrected p-values. Randomized data are generated with random sign flips. See :footcite:`MarisOostenveld2007` for more information. Because a 1-sample t-test on the difference in observations is mathematically equivalent to a paired t-test, internally this function computes a 1-sample t-test (by default) and uses sign flipping (always) to perform permutations. This might not be suitable for the case where there is truly a single observation under test; see :ref:`disc-stats`. %(threshold_clust_t_notes)s If ``n_permutations`` exceeds the maximum number of possible permutations given the number of observations, then ``n_permutations`` and ``seed`` will be ignored since an exact test (full permutation test) will be performed (this is the case when ``n_permutations >= 2 ** (n_observations - (tail == 0))``). If no initial clusters are found because all points in the true distribution are below the threshold, then ``clusters``, ``cluster_pv``, and ``H0`` will all be empty arrays. References ---------- .. footbibliography:: rrr rrrpermutation_cluster_1samp_testns$Mr"cCsX| dk r.tt|jdd|jd| d}nd}t||||||||||| | | | |dS)uNon-parametric cluster-level paired t-test for spatio-temporal data. This function provides a convenient wrapper for :func:`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 :footcite:p:`MarisOostenveld2007,Sassenhagen2019`. Parameters ---------- X : array, 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. %(threshold_clust_t)s %(n_permutations_clust_all)s %(tail_clust)s %(stat_fun_clust_t)s %(adjacency_clust_st1)s %(n_jobs)s %(seed)s %(max_step_clust)s spatial_exclude : list of int or None List of spatial indices to exclude from clustering. %(step_down_p_clust)s %(t_power_clust)s %(out_type_clust)s %(check_disjoint_clust)s %(buffer_size_clust)s %(verbose)s Returns ------- t_obs : array, shape (p[, q], n_vertices) T-statistic observed for all variables. clusters : list List type defined by out_type above. cluster_pv : array P-value for each cluster. H0 : array, shape (n_permutations,) Max cluster level stats observed under permutation. Notes ----- %(threshold_clust_t_notes)s References ---------- .. footbibliography:: Nrr.Trrrrrrrr)r r rCrr r)_st_mask_from_s_indsrrrJr"rrrrrrrrr)Zspatial_excluder rCrr rr r rrr"spatio_temporal_cluster_1samp_tests2<r&cCs`| dk r6tt|djdd|djd| d}nd}t||||||||||| | | | |dS)uGNon-parametric cluster-level test for spatio-temporal data. This function provides a convenient wrapper for :func:`mne.stats.permutation_cluster_test`, for use with data organized in the form (observations × time × space), (observations × time × space), or optionally (observations × time × frequencies × space). For more information, see :footcite:p:`MarisOostenveld2007,Sassenhagen2019`. Parameters ---------- X : list of array, shape (n_observations, p[, q], 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 second, and optionally third, dimensions correspond to the time or time-frequency data. And, the last dimension should be spatial. All dimensions except the first should match across all groups. %(threshold_clust_f)s %(n_permutations_clust_int)s %(tail_clust)s %(stat_fun_clust_f)s %(adjacency_clust_stn)s %(n_jobs)s %(seed)s %(max_step_clust)s spatial_exclude : list of int or None List of spatial indices to exclude from clustering. %(step_down_p_clust)s %(f_power_clust)s %(out_type_clust)s %(check_disjoint_clust)s %(buffer_size_clust)s %(verbose)s Returns ------- F_obs : array, shape (p[, q], n_vertices) Statistic (F by default) observed for all variables. clusters : list List type defined by out_type above. cluster_pv: array P-value for each cluster. H0 : array, shape (n_permutations,) Max cluster level stats observed under permutation. Notes ----- %(threshold_clust_f_notes)s References ---------- .. footbibliography:: Nrrr.Tr#)r$rrrJr!r%rrrspatio_temporal_cluster_test s2> r'cCs@tj||ftd}d|dd|f<|}|dkrfdd|D}nfdd|D}|S)z.csg|]}t|qSr)rrqrr,rrr_s)r$rrrrrSrK)rNrrr,rrs rrr fsaveragecCst|dttfd|dkr4tdtdg}t}nDt|trbtttt d|j }dd|D}nttd t |t }t dd |D}|\}} } } |j\} } | |krtd | d |d t| |kd }t |d krtdt| | f}t| t |df}t|D]X\}}|d | |\}}|||f|||f<tj t||dd|dd|df<qtj |dd|ddd f<||||||S)aSAssemble summary SourceEstimate from spatiotemporal cluster results. This helps visualizing results from spatio-temporal-clustering permutation tests. Parameters ---------- clu : tuple The output from clustering permutation tests. p_thresh : float The significance threshold for inclusion of clusters. tstep : float The time step between samples of the original :class:`STC `, in seconds (i.e., ``1 / stc.sfreq``). Defaults to ``1``, which will yield a colormap indicating cluster duration measured in *samples* rather than *seconds*. tmin : float | int The time of the first sample. subject : str The name of the subject. vertices : list of array | instance of SourceSpaces | None The vertex numbers associated with the source space locations. Defaults to None. If None, equals ``[np.arange(10242), np.arange(10242)]``. Can also be an instance of SourceSpaces to get vertex numbers from. .. versionchanged:: 0.21 Added support for SourceSpaces. Returns ------- out : instance of SourceEstimate A summary of the clusters. The first time point in this SourceEstimate object is the summation of all the clusters. Subsequent time points contain each individual cluster. The magnitude of the activity corresponds to the duration spanned by the cluster (duration units are determined by ``tstep``). .. versionchanged:: 0.21 Added support for volume and mixed source estimates. Nr)i()ZsurfacevolumemixedcSsg|] }|dqS)Zvertnorrrrrr_sz*summarize_clusters_stc..)rrcss|]}t|VqdSr=ra)r[rorrrrsz)summarize_clusters_stc..zNumber of cluster vertices (z') did not match the provided vertices ()rzcNo significant clusters available. Please adjust your threshold or check your statistical analysis.rr)rr4rrrnrrrrrrrrr$r>rJrrrrbrcrrH)ZclurrGZtminsubjectr)klassZn_vertices_needr rNZ clu_pvalsrrgr(Zgood_cluster_indsrFZ data_summaryr7Z cluster_indrOZv_indsrrrsummarize_clusters_stcsN*       r3)N)N)r)r)T)rNrNNrF)rr)rr)NrrNNNNrNrrrFrN)NrrNNNNrNrrrFrN)NrrNNNNrNrrrFrN)NrrNNNNrNrrrFrN)T)N)rrrr-N)>numpyrZ parametricrrr rfixesrrutilsr r r r r rrrrZsource_estimaterrrZ source_spacerr r-r3r:r;r<r@rDrHrQrYrlrprzrrrrrrrrrrrrrrr!r"r&r'r$rrr3rrrr s ,           0 0   )1?G $)C " I U H J