U f{j @sddlZddlZddlmZddlmZddlZddl m Z ddl m Z ddl mZddlmZddlmZdd lmZmZmZmZdd lmZdd lmZdd lmZmZmZm Z dd l!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'ddl(m)Z)m*Z*ddl+m,Z,m-Z-m.Z.m/Z/m0Z0m1Z1m2Z2m3Z3m4Z4m5Z5m6Z6m7Z7m8Z8m9Z9m:Z:m;Z;mZ>m?Z?m@Z@mAZAmBZBmCZCddlDmEZEmFZFmGZGddlHmIZIddlJmKZKddZLddZMddZNddZOddZPddZQd}dd ZRd~d!d"ZSdd$d%ZTd&d'ZUGd(d)d)eIZVd*d+ZWe4Gd,d-d-eVZXe4Gd.d/d/eXZYGd0d1d1eVZZGd2d3d3eVZ[e4Gd4d5d5e[Z\e4Gd6d7d7e[eZZ]e4Gd8d9d9eZeXZ^Gd:d;d;eVZ_e4Gdd?d?eZe_Zad@dAZbdBdCZcdDdEZde/ddFdGZee/ddHdIZfe/ddJdKZge/ddLdMZhe/ddNdOZie/ddPdQZje/ddRdSZke/ddTdUZle/ddVdWZme/ddXdYZndZd[Zod\d]d^d]d_d]eod`ZpejqdadbZrdcddZsdedfZtdgdhZudidjZvdkdlZwdmdnZxdod#dpddqdrdsZye/ddpddudvdwZze/dd{d|Z{dS)N) GeneratorType)rescale) Covariance) _get_peak)resample) _safe_svd)_import_nibabel_get_mri_info_data_get_atlas_valuesread_freesurfer_lut)FIFF) pick_types) read_surface_get_ico_surface mesh_edges_project_onto_surface) _ensure_src_get_morph_src_reordering_ensure_src_subject SourceSpaces _get_src_nn_check_volume_labels) _get_trans apply_trans)get_subjects_dir_check_subjectloggerverbose_pl _time_maskwarncopy_function_doc_to_method_docfill_doc _check_option_validate_type_check_src_normal_check_stc_units_check_pandas_installed_check_pandas_index_arguments_convert_times _ensure_int_build_data_frame_check_time_format _path_like sizeof_fmt object_size _check_fname_import_h5io_funcs)plot_source_estimatesplot_vector_source_estimatesplot_volume_source_estimates) TimeMixin)Infoc CsTt|d}|}W5QRXt}d}d}ttj|dd|d|d<|dd<||7}ttj|dd|d|d <|d d<||7}ttj|d d|d}||7}tj|d ||d|d <|||7}ttj|d d|d}||7}|rt|dd|||dkrtd tj|d|||d|d <|d  ||gj |d <|S)z Aux Function.rbr>f4r)dtypecountoffsettmin@@tstep>u4verticeszincorrect stc file sizedata) openreaddictfloatnpZ frombufferintlen ValueErrorreshapeT)filenamefidbufstcr=Z num_bytes vertices_nZdata_nrSR/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/source_estimate.py _read_stc+s@         rUc Cs|t|d}|tjd|dd|tjd|dd|tj|jddd|tj|dd|tj|jddd|tj|jddW5QRXdS) anWrite an STC file. Parameters ---------- filename : string The name of the STC file. tmin : float The first time point of the data in seconds. tstep : float Time between frames in seconds. vertices : array of integers Vertex indices (0 based). data : 2D array The data matrix (nvert * ntime). wbr:r;rrArN)rDwriterHarraytobytesshaperM)rNr>r@rBrCrOrSrSrT _write_stcYs r]cCsFtj|tjddtj}t|ddt|dd|d}|S)zRead 3 byte integer from file.r;r<rr)rHfromfileuint8astypeint32Z left_shift)rOrCoutrSrSrT_read_3ys(rhc Cst|ddd}|dtt|}tj|tjd}tj|tjd}t|D](}t|||<tj |dddd||<qNt }||d <||d <W5QRX|S) aRead a w file. w files contain activations or source reconstructions for a single time point. Parameters ---------- filename : string The name of the w file. Returns ------- data: dict The w structure. It has the following keys: vertices vertex indices (0 based) data The data matrix (nvert long) r8r) bufferingrbrXr:rr_rBrC) rDrErIrhrHzerosrffloat32rangercrF)rNrOrRrBrCiwrSrSrT_read_ws    rocCsNtjdtjd}|d?d@|d<|d?d@|d<|d@|d<||d S) zWrite 3 byte integer to file.r^rXr`rrarrbN)rHrjrdrYr[)rOvalZf_bytesrSrSrT_write_3s  rrc Cst|t|kstt|dn}|tjdtjdt|}t||t |D]2}t||||tj t ||ddqTW5QRXdS)a0Write a w file. w files contain activations or source reconstructions for a single time point. Parameters ---------- filename: string The name of the w file. vertices: array of int Vertex indices (0 based). data: 1D array The data array (nvert). rVrbrXr:N) rJAssertionErrorrDrYrHrjrdr[rrrlrZrG)rNrBrCrOrRrmrSrSrT_write_ws   rtcCsv|}t|ddt|ddd}d}t|r|drsz(read_source_estimate..rr~cSsg|]}t|qSrSrrrSrSrTrsrr-stc.h5z-stczHemisphere missing for %rz(SourceEstimate File(s) not found for: %rrCgr>r@z/Volume source estimate must end with .stc or .wrB? mnepython)titlesrc_typecss(|] }tt|tdkVqdSrN)rHanydiffrerIrvrSrSrT Vsz'read_source_estimate..cSsg|]}t|qSrS)rHZargsort)rvertsrSrSrTrWscSsg|]\}}||qSrSrS)rridxrSrSrTrXsrrsubjectzHprovided subject name "%s" does not match subject name from the file "%sr|discretemixedr^)r%r1rrendswithIOError RuntimeErrorallrrUrorHnewaxisrscopyZr_Z atleast_2drMr2pop isinstancendarrayziprJVolVectorSourceEstimateMixedVectorSourceEstimateVectorSourceEstimatendim _scalar_class)rvrZ fname_argftypeerrZ stc_existZw_existkwargslhrhZ read_hdf5_rBZsidxrCklassrSrSrTread_source_estimates"                         "    *    rcCsd}|dkr|dkrtdnt|t|trBt|dkrBd}qt|tjsdt|trjt|dkrjd}qt|trt|dkrd}n|j}|dkst|S)Nz6src should not be None for a robust guess of stc type.rbr}rr|r)r}r|rr)r!rlistrJrHrkindrs)srcrB warn_textrrSrSrT _get_src_typeps    rFc sfdd} |dkr| n|}|r<|dkr<|dkr.guess_src_typeNr}zNo source vectors supplied.rrzDvertices has to be either a list with one or more arrays or an arraycss|]}t|VqdSNrJrrSrSrTrsz_make_stc..rr^rbr)Zaxes)rCrBr>r@r)rrSourceEstimaterVolSourceEstimaterMixedSourceEstimaterKsumr\rsrJrHrrLmatmulZ transpose) rCrBrr>r@rZvectorZ source_nnrrZKlass n_verticesrSrrT _make_stcsF ,  rcCsd}t|t|kr,tdt|t|ft|jt|jkr`tddt|j|jDr`d}|sltd|j|jkrtd|j|jfdS) zCMake sure two SourceEstimates are compatible for arith. operations.FzCannot combine %s and %s.css|]\}}t||VqdSr)rH array_equal)ravZvvrSrSrTrsz1_verify_source_estimate_compat..Tz`Cannot combine source estimates that do not have the same vertices. Consider using stc.expand().z>source estimates do not have the same subject names, %r and %rN)typerKrJrBrrr)abcompatrSrSrT_verify_source_estimate_compats   rc@s(eZdZdZedtddZddZedud d Zedvd d Z edwddddZ edxdddddZ e e dyd!d"Zed#d$Zed%d&Zd'd(Zedzd)d*Zed{d,d-Zed.d/Zejd0d/Zed1d2Zed3d4Zejd5d4Zed6d7Zejd8d7Zed9d:Zejd;d:Zdd?Zd@dAZdBdCZdDdEZdFdGZ dHdIZ!dJdKZ"dLdMZ#dNdOZ$dPdQZ%dRdSZ&dTdUZ'dVdWZ(dXdYZ)dZd[Z*d\d]Z+d^d_Z,d`daZ-dbdcZ.dddeZ/dfdgZ0dhdiZ1djdkZ2dde3jfdldmZ4d|dndoZ5d}dpdqZ6ed~dddrdsZ7dS)_BaseSourceEstimaterbNc Cs,t|dst|jjt|ds,t|jjt|dsBt|jjd\}}t|trt|dkrhtd|\}}d}|jd|jdkrtd |j|jf|j dkrtd |j ft |t d |j dk rt||j krtd |j t|fd d|D}t dd|Drtdtdd|D} |dk r|j |j|jdfkrhtd|j|j|jjf|jd| krtd| d|jdd|jdkr|jddkrtd|jf|j |jdkr|dtjf}||_||_||_||_||_||_d|_d|_|td|dd|_dS)N _data_ndim _src_type _src_count)NNrbz(If data is a tuple it has to be length 2rrz6kernel (%s) and sens_data (%s) have invalid dimensionsz.The sensor data must have 2 dimensions, got %srBz/vertices must be a list with %d entries, got %scSsg|]}t|tjqSrS)rHrZint64rrSrSrTrsz0_BaseSourceEstimate.__init__..css"|]}tt|dkVqdSr)rHrrrrSrSrTrsz/_BaseSourceEstimate.__init__..z-Vertices must be ordered in increasing order.cSsg|] }t|qSrSrrrSrSrTrsz.Data (shape %s) must have %s dimensions for %szNumber of vertices (z) and stc.data.shape[0] (z ) must matchr^zCData for VectorSourceEstimate must have shape[1] == 3, got shape %s.F raise_error)hasattrrs __class____name__rtuplerJrKr\rr%rrrrrrHr_data_tmin_tsteprB_kernel _sens_data_kernel_removed_times _update_timesrr) selfrCrBr>r@rrZkernelZ sens_dataZn_srcrSrSrT__init__sr         z_BaseSourceEstimate.__init__cCsdtdd|jDf}|jdk r2|d|j7}|dd|j7}|dd|jd7}|d d|j7}|d |jf7}td d|j|jgD}|d t|7}d t |j |fS)Nz %d verticescss|]}t|VqdSrrrrSrSrTrsz/_BaseSourceEstimate.__repr__..z, subject : %sz, tmin : %s (ms)r?z, tmax : %s (ms)rz, tstep : %s (ms)z, data shape : %scss|]}t|VqdSr)r0)rxrSrSrTr sz, ~z <%s | %s>) rrBrr>timesr@r\rCr/rr)rsszrSrSrT__repr__s z_BaseSourceEstimate.__repr__absFc Csl|jdkr|n|}|jdkr(tdt|j|j|||\}}} |sVt|j |}|sd|j|}||fS)a6Get location and latency of peak amplitude. Parameters ---------- %(get_peak_parameters)s Returns ------- pos : int The vertex exhibiting the maximum response, either ID or index. latency : float The latency in seconds. r^rz"Cannot find peaks with no vertices) r magnitude _n_verticesrrrCrrH concatenaterB) rr>tmaxmode vert_as_index time_as_indexrQZvert_idxZtime_idxrrSrSrTget_peaks   z_BaseSourceEstimate.get_peakautoc Cst||||d||dS)aNExtract label time courses for lists of labels. This function will extract one time course for each label. The way the time courses are extracted depends on the mode parameter. Parameters ---------- %(labels_eltc)s %(src_eltc)s %(mode_eltc)s %(allow_empty_eltc)s %(verbose)s Returns ------- %(label_tc_el_returns)s See Also -------- extract_label_time_course : Extract time courses for multiple STCs. Notes ----- %(eltc_mode_notes)s F)rreturn_generator allow_emptyrextract_label_time_course)rlabelsrrrrrSrSrTr)sz-_BaseSourceEstimate.extract_label_time_courseNrrcCst|j|j|dd|_|S)aBaseline correct source estimate data. Parameters ---------- %(baseline_stc)s Defaults to ``(None, 0)``, i.e. beginning of the the data until time point zero. %(verbose)s Returns ------- stc : instance of SourceEstimate The baseline-corrected source estimate object. Notes ----- Baseline correction can be done multiple times. Fr)rrCr)rbaselinerrSrSrTapply_baselineIsz"_BaseSourceEstimate.apply_baselinerrwrc Cs~t|dd}|dkr&td|jjft\}}|dsB|d7}t||d}||t|j|j|j |j |j |j dddd d S) aSave the full source estimate to an HDF5 file. Parameters ---------- fname : str The file name to write the source estimate to, should end in '-stc.h5'. ftype : str File format to use. Currently, the only allowed values is "h5". %(overwrite)s .. versionadded:: 1.0 %(verbose)s Trvrwrz-%s objects can only be written as HDF5 files.rr)rBrCr>r@rrr)rrwN) r1rKrrr2rrFrBrCr>r@rr)rrvrrwrrZ write_hdf5rSrSrTsave`s&     z_BaseSourceEstimate.saveinflatedr Trclassic blackroct6verticalc !CsJt|||||||||| | | | | |||||||||||||||||d}|S)N)r}hemicolormap time_labelsmoothing_steps transparentalpha time_viewer subjects_dirfigureviewscolorbarclimcortexsize background foreground initial_time time_unitbackendspacingr show_tracesrvolume_options view_layoutadd_data_kwargs brain_kwargsr)r3) rrr}rrrrr r r r r rrrrrrrrrrrrrrrrrrrbrainrSrSrTplotsD  z_BaseSourceEstimate.plotcCs d|jS)zSample rate of the data.r)r@rrSrSrTsfreqsz_BaseSourceEstimate.sfreqcCstdd|jDS)Ncss|]}t|VqdSrrrrSrSrTrsz2_BaseSourceEstimate._n_vertices..rrBr rSrSrTrsz_BaseSourceEstimate._n_verticescCs<|jdk s|jdk r8d|_t|j|j|_d|_d|_dS)z;Remove kernel and sensor space data and compute self._data.NT)rrrrHdotrr rSrSrT_remove_kernel_sens_data_s z-_BaseSourceEstimate._remove_kernel_sens_data_cCsjt|j|||j|d}|jt|dd|_|jdk rV|jdk rV|jd|f|_n|jd|f|_|S)aRestrict SourceEstimate to a time interval. Parameters ---------- tmin : float | None The first time point in seconds. If None the first present is used. tmax : float | None The last time point in seconds. If None the last present is used. %(include_tmax)s Returns ------- stc : instance of SourceEstimate The cropped source estimate. )r! include_tmaxrN.) r rr!rHwherer>rrrC)rr>rr%maskrSrSrTcropsz_BaseSourceEstimate.cropboxcarcCsR|d|j}|j}|jtjkr0|tj}t|||||d|_d||_|S)aResample data. If appropriate, an anti-aliasing filter is applied before resampling. See :ref:`resampling-and-decimating` for more information. Parameters ---------- sfreq : float New sample rate to use. npad : int | str Amount to pad the start and end of the data. Can also be "auto" to use a padding that will result in a power-of-two size (can be much faster). window : str | tuple Window to use in resampling. See :func:`scipy.signal.resample`. %(n_jobs)s %(verbose)s Returns ------- stc : instance of SourceEstimate The resampled source estimate. Notes ----- For some data, it may be more accurate to use npad=0 to reduce artifacts. This is dataset dependent -- check your data! Note that the sample rate of the original data is inferred from tstep. r)n_jobs) r$r@rCr;rHrkrefloat64r)rr!ZnpadZwindowr*rZo_sfreqrCrSrSrTrs#    z_BaseSourceEstimate.resamplecCs|jdkr||jS)z$Numpy array of source estimate data.N)rr$r rSrSrTrCs z_BaseSourceEstimate.datacCs|t|}|jdk r2|j|jjkr2td|jjtdd|jD}|jd|krjtd|jd|f||_|dS)Nz%Data array should have %d dimensions.css|]}t|VqdSrrrrSrSrTrsz+_BaseSourceEstimate.data..rzRThe first dimension of the data array must match the number of vertices (%d != %d)) rHZasarrayrrrKrrBr\r)rvalueZn_vertsrSrSrTrCs  cCs*|jdk r|jjS|jjd|jjdfS)zShape of the data.Nrr)rr\rrr rSrSrTr\ s z_BaseSourceEstimate.shapecCs|jS)zThe first timestamp.)rr rSrSrTr>sz_BaseSourceEstimate.tmincCst||_|dSr)rGrrrr,rSrSrTr>s cCs|jS)z?The change in time between two consecutive samples (1 / sfreq).)rr rSrSrTr@sz_BaseSourceEstimate.tstepcCs&|dkrtdt||_|dS)Nrz.tstep must be greater than 0.)rKrGrrr-rSrSrTr@ s cCs|jS)zA timestamp for each sample.)rr rSrSrTr'sz_BaseSourceEstimate.timescCs tddS)NzYou cannot write to the .times attribute directly. This property automatically updates whenever .tmin, .tstep or .data changes.)rKr-rSrSrTr,scCs,|j|jt|jd|_d|jj_dS)z?Update the times attribute after changing tmin, tmax, or tstep.rFN)r>r@rHaranger\rflagsZ writeabler rSrSrTr2sz!_BaseSourceEstimate._update_timescCs|}||7}|S)zAdd source estimates.rrrrQrSrSrT__add__7sz_BaseSourceEstimate.__add__cCs@|t|tr.t|||j|j7_n|j|7_|Srr$rrrrCrrrSrSrT__iadd__=s   z_BaseSourceEstimate.__iadd__cCs|}|t|j}|S)zMake a summary stc file with mean over time points. Returns ------- stc : SourceEstimate | VectorSourceEstimate The modified stc. )rrJr)rrgrSrSrTmeanFsz_BaseSourceEstimate.meancCs\|j}|j|j|jd}|j|d}||j}|j|jjddd|j|||jd}|S)zMake a summary stc file with sum over time points. Returns ------- stc : SourceEstimate | VectorSourceEstimate The modified stc. r@TaxiskeepdimsrBr>r@r)rCr>r@r\rrrBr)rrCrr>r@Zsum_stcrSrSrTrRs z_BaseSourceEstimate.sumcCs|}||8}|S)zSubtract source estimates.rr0rSrSrT__sub__csz_BaseSourceEstimate.__sub__cCs@|t|tr.t|||j|j8_n|j|8_|Srr2r3rSrSrT__isub__is   z_BaseSourceEstimate.__isub__cCs ||Sr)__div__r3rSrSrT __truediv__rsz_BaseSourceEstimate.__truediv__cCs|}||}|S)zDivide source estimates.rr0rSrSrTr=usz_BaseSourceEstimate.__div__cCs ||Sr)__idiv__r3rSrSrT __itruediv__{sz _BaseSourceEstimate.__itruediv__cCs@|t|tr.t|||j|j_n|j|_|Srr2r3rSrSrTr?~s   z_BaseSourceEstimate.__idiv__cCs|}||9}|S)zMultiply source estimates.rr0rSrSrT__mul__sz_BaseSourceEstimate.__mul__cCs@|t|tr.t|||j|j9_n|j|9_|Srr2r3rSrSrT__imul__s   z_BaseSourceEstimate.__imul__cCs|}||C}|Srrr0rSrSrT__pow__sz_BaseSourceEstimate.__pow__cCs||j|C_|Sr)r$rCr3rSrSrT__ipow__sz_BaseSourceEstimate.__ipow__cCs||SrrSr3rSrSrT__radd__sz_BaseSourceEstimate.__radd__cCs||SrrSr3rSrSrT__rsub__sz_BaseSourceEstimate.__rsub__cCs||SrrSr3rSrSrT__rmul__sz_BaseSourceEstimate.__rmul__cCs||SrrSr3rSrSrT__rdiv__sz_BaseSourceEstimate.__rdiv__cCs"|}||jd9_|S)zNegate the source estimate.r)rr$rCrrQrSrSrT__neg__sz_BaseSourceEstimate.__neg__cCs|SrrSr rSrSrT__pos__sz_BaseSourceEstimate.__pos__cCs |}|t|j|_|S)zCompute the absolute value of the data. Returns ------- stc : instance of _BaseSourceEstimate A version of the source estimate, where the data attribute is set to abs(self.data). )rr$rrrIrSrSrT__abs__s  z_BaseSourceEstimate.__abs__cCs|dS)zTake the square root. Returns ------- stc : instance of SourceEstimate A copy of the SourceEstimate with sqrt(data). g?rSr rSrSrTsqrtsz_BaseSourceEstimate.sqrtcCs t|S)zReturn copy of source estimate instance. Returns ------- stc : instance of SourceEstimate A copy of the source estimate. )rdeepcopyr rSrSrTrsz_BaseSourceEstimate.copyc Cs|dkr|j}|dkr |jd}t|||j|}t|d}tj|jdd|f|jj d}t |D]B}|j||k|j||dk@} ||jd| fdd|d|f<qj|d|d} | } || _ | | _|| _| S) a/Return a source estimate object with data summarized over time bins. Time bins of ``width`` seconds. This method is intended for visualization only. No filter is applied to the data before binning, making the method inappropriate as a tool for downsampling data. Parameters ---------- width : scalar Width of the individual bins in seconds. tstart : scalar | None Time point where the first bin starts. The default is the first time point of the stc. tstop : scalar | None Last possible time point contained in a bin (if the last bin would be shorter than width it is dropped). The default is the last time point of the stc. func : callable Function that is applied to summarize the data. Needs to accept a numpy.array as first input and an ``axis`` keyword argument. Returns ------- stc : SourceEstimate | VectorSourceEstimate The binned source estimate. NrrrX.r8rr6) r>rrHr.r@rJemptyr\rCr;rlrr) rwidthZtstartZtstopfuncrntrCrmrr>rQrSrSrTbins   "   z_BaseSourceEstimate.bincCs|dkrtdd}|jdkr`|jdkr`|jr4td||j|d||f}t|tr^|d}n||jdd||f}t|tr|d}|j}t |dkr| |dt |dd}t |j|ddf|}t |dkr|j |jdf|dd}|S)aGet data after a linear (time) transform has been applied. The transform is applied to each source time course independently. Parameters ---------- func : callable The transform to be applied, including parameters (see, e.g., :func:`functools.partial`). The first parameter of the function is the input data. The first return value is the transformed data, remaining outputs are ignored. The first dimension of the transformed data has to be the same as the first dimension of the input data. idx : array | None Indicices of source time courses for which to compute transform. If None, all time courses are used. tmin_idx : int | None Index of first time point to include. If None, the index of the first time point is used. tmax_idx : int | None Index of the first time point not to include. If None, time points up to (and including) the last time point are included. Returns ------- data_t : ndarray The transformed data. Notes ----- Applying transforms can be significantly faster if the SourceEstimate object was created using "(kernel, sens_data)", for the "data" parameter as the transform is applied in sensor space. Inverse methods, e.g., "apply_inverse_epochs", or "apply_lcmv_epochs" do this automatically (if possible). Nz[Performance can be improved by not accessing the data attribute before calling this method..rrbr)slicerrrr!rCrrr\rJrLrHprodr#)rrRrtmin_idxtmax_idxdata_tZ sens_data_tZ data_shaperSrSrTtransform_datas(%      z"_BaseSourceEstimate.transform_datacsJdj}tt||jdd}dkr4d}n|d}|dkrJd} n |dd} j|||| d|dk r||tjk} ||tjktj} j| } j| } n j} j} | | g|dkrdn|}j|j dkr"|rfd d t j dD}nt d n$|s,n }|_|_|_|S) aApply linear transform. The transform is applied to each source time course independently. Parameters ---------- func : callable The transform to be applied, including parameters (see, e.g., :func:`functools.partial`). The first parameter of the function is the input data. The first two dimensions of the transformed data should be (i) vertices and (ii) time. See Notes for details. idx : array | None Indices of source time courses for which to compute transform. If None, all time courses are used. tmin : float | int | None First time point to include (ms). If None, self.tmin is used. tmax : float | int | None Last time point to include (ms). If None, self.tmax is used. copy : bool If True, return a new instance of SourceEstimate instead of modifying the input inplace. Returns ------- stcs : SourceEstimate | VectorSourceEstimate | list The transformed stc or, in the case of transforms which yield N-dimensional output (where N > 2), a list of stcs. For a list, copy must be True. Notes ----- Transforms which yield 3D output (e.g. time-frequency transforms) are valid, so long as the first two dimensions are vertices and time. In this case, the copy parameter must be True and a list of SourceEstimates, rather than a single instance of SourceEstimate, will be returned, one for each index of the 3rd dimension of the transformed data. In the case of transforms yielding 2D output (e.g. filtering), the user has the option of modifying the input inplace (copy = False) or returning a new instance of SourceEstimate (copy = True) with the transformed data. Applying transforms can be significantly faster if the SourceEstimate object was created using "(kernel, sens_data)", for the "data" parameter as the transform is applied in sensor space. Inverse methods, e.g., "apply_inverse_epochs", or "apply_lcmv_epochs" do this automatically (if possible). r?)r!rNrr)rrWrXrbcs2g|]*}tdddd|fjjqSr)rr@r)rrrYrr>rrSrTrs z1_BaseSourceEstimate.transform..z@copy must be True if transformed data has more than 2 dimensions)rrHr&r r!rZrJ lh_vertno rh_vertnorrlr\rKrrBrCr>)rrRrr>rrrZt_idxrWrXZidx_lhZidx_rhZverts_lhZverts_rhstcsrSr[rT transformQs@2         z_BaseSourceEstimate.transformc st}ddg}ddg}t||}t||}|jj} |j} t} dg} |jdk rtddg} | dt |j| j dft || |} | d| ft} dgt |j}t|ttfrdd g|dd <tt||jD]$\}\}| fd d |Dqt|| d|| || | d d }|S)a2Export data in tabular structure as a pandas DataFrame. Vertices are converted to columns in the DataFrame. By default, an additional column "time" is added, unless ``index='time'`` (in which case time values form the DataFrame's index). Parameters ---------- %(index_df_evk)s Defaults to ``None``. %(scalings_df)s %(long_format_df_stc)s %(time_format_df)s .. versionadded:: 0.20 %(verbose)s Returns ------- %(df_return)s timerms timedeltaNrZVOLZLHZRHrbcsg|]}d|qS)z{}_{}format)rZvertrrSrTrsz5_BaseSourceEstimate.to_data_frame..source) default_index col_namesZcol_kind)r(r)r-rCrMrrrappendrHrepeatr\r*rJrBr_BaseSurfaceSourceEstimate_BaseMixedSourceEstimate enumeraterextendr,)rindexZscalingsZ long_format time_formatrpdZvalid_index_argsZvalid_time_formatsrCrZmindexrgrhkindsiivertnoZdfrSrerT to_data_frames8    z!_BaseSourceEstimate.to_data_frame)NN)NNrFF)rFN)r)r)NrrrrrTrrNNrTrrrrNNrrrNrNrrNNN)NNT)rr)NN)NNN)NNNF)NNFN)8r __module__ __qualname__rrrrr#rrrrr"r3rpropertyr!rr$r(rrCsetterr\r>r@rrr1r4r5rr;r<r>r=r@r?rArBrCrDrErFrGrHrJrKrLrMrrHrTrZr_rurSrSrSrTrs ;        .                . K brc Cs"|dks|dkr tdt|dd}tt||d|d|}|dkrV|}n\|dkrtt|dj d}n>t |t r|j dkr|d krd nd}||d }n t |t}|d|d d fj}tj||d d t|} tttj|d|d d f| dd d } || } | S)z%Find the center of mass on a surface.rzUAll values must be non-negative and at least one must be non-zero, cannot compute COMTrsurf.Fr}rrrtNrOrb)rrrKrrrjoinrHr.r\rrrrZrIrMrZargminrMr5) rBvaluesrrzrr restrict_verticesrposZc_o_mvertexrSrSrT_center_of_masss2      rcseZdZdZdZdZeddZeddZedd Z ed d Z d d Z ddZ ddZ edddZedfdd ZZS)rkaAbstract base class for surface source estimates. Parameters ---------- data : array The data in source space. vertices : list of array, shape (2,) Vertex numbers corresponding to the data. The first element of the list contains vertices of left hemisphere and the second element contains vertices of right hemisphere. %(tmin)s %(tstep)s %(subject_optional)s %(verbose)s Attributes ---------- subject : str | None The subject name. times : array of shape (n_times,) The time vector. vertices : list of array, shape (2,) Vertex numbers corresponding to the data. The first element of the list contains vertices of left hemisphere and the second element contains vertices of right hemisphere. data : array The data in source space. shape : tuple The shape of the data. A tuple of int (n_dipoles, n_times). r}rbcCs|jdt|jS)zLeft hemisphere data.NrCrJr\r rSrSrTlh_data+sz"_BaseSurfaceSourceEstimate.lh_datacCs|jt|jdS)zRight hemisphere data.Nrr rSrSrTrh_data0sz"_BaseSurfaceSourceEstimate.rh_datacCs |jdS)zLeft hemisphere vertno.rrBr rSrSrTr\5sz$_BaseSurfaceSourceEstimate.lh_vertnocCs |jdS)zRight hemisphere vertno.rrr rSrSrTr]:sz$_BaseSurfaceSourceEstimate.rh_vertnocCsv|jdkr|jd}n |jd}tt||jd}||}|jdkrd|j|t|jd}n |j|}||fS)Nrrrr)rrBrHZnonzeroin1drCrJ)rlabelZ stc_verticesrrBr}rSrSrT_hemilabel_stc?s     z)_BaseSurfaceSourceEstimate._hemilabel_stcc Cs*ddlm}m}t|||fd|jdk rT|jdk rT|j|jkrTtd|j|jf|jdkr||j\}}||j \}}||g}t ||f} nV|jdkr||\}} |t gt g}n,|jdkst||\}} t gt |g}td d |Dd kr td |j| ||j|j|jd } | S)a4Get a source estimate object restricted to a label. SourceEstimate contains the time course of activation of all sources inside the label. Parameters ---------- label : Label | BiHemiLabel The label (as created for example by mne.read_label). If the label does not match any sources in the SourceEstimate, a ValueError is raised. Returns ------- stc : SourceEstimate | VectorSourceEstimate The source estimate restricted to the given label. r)Label BiHemiLabelrNzClabel and stc must have same subject names, currently "%s" and "%s"bothrrcSsg|] }t|qSrSrrrSrSrTr{sz7_BaseSurfaceSourceEstimate.in_label..rz+No vertices match the label in the stc filer:)rrrr%rrrrrrrHvstackrZrIrsrrKrr>r@) rrrrZlh_vertZlh_valZrh_vertZrh_valrBr} label_stcrSrSrTin_labelSs8    z#_BaseSurfaceSourceEstimate.in_labelc Cst|tstdt|jt|ks,td|t}dg}tt|j|D]T\}\}}t ||}t ||}|| g7}|t|g7}t ||||j|<qPddt||ddD}t |}t t|f|jjdd}t j |j||dd |_|S) aExpand SourceEstimate to include more vertices. This will add rows to stc.data (zero-filled) and modify stc.vertices to include all vertices in stc.vertices and the input vertices. Parameters ---------- vertices : list of array New vertices to add. Can also contain old values. Returns ------- stc : SourceEstimate | VectorSourceEstimate The modified stc (note: method operates inplace). zvertices must be a listz2vertices must have the same length as stc.verticesrcSsg|]\}}||qSrSrS)rrsr=rSrSrTrsz5_BaseSurfaceSourceEstimate.expand..NrrrO)rr TypeErrorrJrBrKr$rmrrHZ setdiff1d searchsortedrinsertrrjrCr\) rrBZ insertersoffsetsviZv_oldZv_newZindsZnew_datarSrSrTexpands$     z!_BaseSurfaceSourceEstimate.expandNcCs\|jdkrtdt|dd}t||}t|j|||j|\}}||j|||j|j |S)aGet a source estimate from morphed source to the original subject. Parameters ---------- src_orig : instance of SourceSpaces The original source spaces that were morphed to the current subject. subject_orig : str | None The original subject. For most source spaces this shouldn't need to be provided, since it is stored in the source space itself. %(subjects_dir)s %(verbose)s Returns ------- stc : SourceEstimate | VectorSourceEstimate The transformed source estimate. See Also -------- morph_source_spaces Notes ----- .. versionadded:: 0.10.0 Nzstc.subject must be setr}re) rrKrrrrBrrr>r@)rZsrc_origZ subject_origr rZdata_idxrBrSrSrTto_original_srcs    z*_BaseSurfaceSourceEstimate.to_original_srcrFc std|dd}|dk rh|dkr2|j}|jgg} nt|jd}|j}g|jg} ||| |j|j j } nt j } | |||||d} |r|r| d|| df} | S)aGet location and latency of peak amplitude. Parameters ---------- hemi : {'lh', 'rh', None} The hemi to be considered. If None, the entire source space is considered. %(get_peak_parameters)s Returns ------- pos : int The vertex exhibiting the maximum response, either ID or index. latency : float | int The time point of the maximum response, either latency in seconds or index. r)rrNrNr)r>rrrrr) r$rr\rJrBrr]rr>r@rsuper) rrr>rrrrZ vertex_offsetrCrBmethrgrrSrTrs.   z#_BaseSurfaceSourceEstimate.get_peak)NNN)NNNrFF)rrvrw__doc__rrrxrrr\r]rrrrrr#r __classcell__rSrSrrTrks0    /( %rkcsJeZdZdZed dddfdd Zeddd Zedd d ZZ S)ra:Container for surface source estimates. Parameters ---------- data : array of shape (n_dipoles, n_times) | tuple, shape (2,) The data in source space. When it is a single array, the left hemisphere is stored in data[:len(vertices[0])] and the right hemisphere is stored in data[-len(vertices[1]):]. When data is a tuple, it contains two arrays: - "kernel" shape (n_vertices, n_sensors) and - "sens_data" shape (n_sensors, n_times). In this case, the source space data corresponds to ``np.dot(kernel, sens_data)``. vertices : list of array, shape (2,) Vertex numbers corresponding to the data. The first element of the list contains vertices of left hemisphere and the second element contains vertices of right hemisphere. %(tmin)s %(tstep)s %(subject_optional)s %(verbose)s Attributes ---------- subject : str | None The subject name. times : array of shape (n_times,) The time vector. vertices : list of array, shape (2,) The indices of the dipoles in the left and right source space. data : array of shape (n_dipoles, n_times) The data in source space. shape : tuple The shape of the data. A tuple of int (n_dipoles, n_times). See Also -------- VectorSourceEstimate : A container for vector source estimates. VolSourceEstimate : A container for volume source estimates. MixedSourceEstimate : A container for mixed surface + volume source estimates. rQFNrc slt|dd}td|dddg|jdt|j}|jt|j d}|dkrt|jrdtdt d t|d |d }t|d |d }t ||j |j |j|d t ||j |j |j|d n|dkrD|jddkrtdt dt|d|d }t|d|d }t||j|dddfdt||j|dddfdn|dkr^tj||d t ddS)afSave the source estimates to a file. Parameters ---------- fname : str The stem of the file name. The file names used for surface source spaces are obtained by adding "-lh.stc" and "-rh.stc" (or "-lh.w" and "-rh.w") to the stem provided, for the left and the right hemisphere, respectively. ftype : str File format to use. Allowed values are "stc" (default), "w", and "h5". The "w" format only supports a single time point. %(overwrite)s .. versionadded:: 1.0 %(verbose)s TrrrQrnrNzCannot save complex-valued STC data in FIFF format; please set ftype='h5' to save in HDF5 format instead, or cast the data to real numbers before saving.Writing STC to disk...r~rwrr>r@rBrCrz,w files can only contain a single time point!Writing STC to disk (w format)...rrrrBrC[done])r1r$rCrJr\r]rHZ iscomplexobjrKrinfor]r>r@r\rtrr) rrvrrwrrrZfname_lZfname_rrrSrTr)s:        zSourceEstimate.savecCsddlm}m}ddlm}t||dt|tdt|tdt||j dk r^t d||d d d }||||d dd d d d d d d d d \ }} } } } } } }} |dd}|d} ||j } t |d} d| t j| | dd d} |}dt |j |j | |jd d <|S)aCompute time-varying SNR in the source space. This function should only be used with source estimates with units nanoAmperes (i.e., MNE-like solutions, *not* dSPM or sLORETA). See also :footcite:`GoldenholzEtAl2009`. .. warning:: This function currently only works properly for fixed orientation. Parameters ---------- %(info_not_none)s fwd : instance of Forward The forward solution used to create the source estimate. cov : instance of Covariance The noise covariance used to estimate the resting cortical activations. Should be an evoked covariance, not empty room. %(verbose)s Returns ------- snr_stc : instance of SourceEstimate The source estimate with the SNR computed. Notes ----- We define the SNR in decibels for each source location at each time point as: .. math:: {\rm SNR} = 10\log_10[\frac{a^2}{N}\sum_k\frac{b_k^2}{s_k^2}] where :math:`\\b_k` is the signal on sensor :math:`k` provided by the forward model for a source with unit amplitude, :math:`a` is the source amplitude, :math:`N` is the number of sensors, and :math:`s_k^2` is the noise variance on sensor :math:`k`. References ---------- .. footbibliography:: r)convert_forward_solutionForward)_prepare_forwardfwdrcovrzhThis STC appears to be from free orientation, currently SNR function is valid only for fixed orientationTF)Zsurf_oriZ force_fixedNZfro) ZfixedlooseZrankpcause_cpsexpZlimit_depth_chsZ combine_xyzZallow_fixed_depthlimitZsolrCdimr7r)forwardrrZminimum_norm.inverserr%r7rr'rCrr!rMrHZdiagrrlog10r)rrrrrrrrGrZ n_channelsZb_k2Zs_k2ZscalingZsnr_stcrSrSrT estimate_snr\s@,      $zSourceEstimate.estimate_snrspherec sft|tstdt|ft|j|}t|jdkr@t dtj |jddt t |j dt t |j dt |j dg}|dkrttfdd|Dd}t |dkst d |d}td |ddg|j |}||~t|d d g|||||d }tj |jddt} t | t |jdt | } |j|j| } ||| fS)a Compute the center of mass of activity. This function computes the spatial center of mass on the surface as well as the temporal center of mass as in :footcite:`LarsonLee2013`. .. note:: All activity must occur in a single hemisphere, otherwise an error is raised. The "mass" of each point in space for computing the spatial center of mass is computed by summing across time, and vice-versa for each point in time in computing the temporal center of mass. This is useful for quantifying spatio-temporal cluster locations, especially when combined with :func:`mne.vertex_to_mni`. Parameters ---------- subject : str | None The subject the stc is defined for. hemi : int, or None Calculate the center of mass for the left (0) or right (1) hemisphere. If None, one of the hemispheres must be all zeroes, and the center of mass will be calculated for the other hemisphere (useful for getting COM for clusters). restrict_vertices : bool | array of int | instance of SourceSpaces If True, returned vertex will be one from stc. Otherwise, it could be any vertex from surf. If an array of int, the returned vertex will come from that array. If instance of SourceSpaces (as of 0.13), the returned vertex will be from the given source space. For most accuruate estimates, do not restrict vertices. %(subjects_dir)s surf : str The surface to use for Euclidean distance center of mass finding. The default here is "sphere", which finds the center of mass on the spherical surface to help avoid potential issues with cortical folding. Returns ------- vertex : int Vertex of the spatial center of mass for the inferred hemisphere, with each vertex weighted by the sum of the stc across time. For a boolean stc, then, this would be weighted purely by the duration each vertex was active. hemi : int Hemisphere the vertex was taken from. t : float Time of the temporal center of mass (weighted by the sum across source vertices). See Also -------- mne.Label.center_of_mass mne.vertex_to_mni References ---------- .. footbibliography:: zsurf must be a string, got %srz'Cannot compute COM with negative valuesrrONcsg|]}t|qSrSrHr)rrr}rSrTrsz1SourceEstimate.center_of_mass..zCould not infer hemisphererrr)rrzrr r~)rstrrrrrrHrrCrKrr.rJrBr&rZr$rrerGr\r>r@) rrrr~r rzZ vert_indsrBrZmassesZt_indtrSrrTcenter_of_masssF<       $zSourceEstimate.center_of_mass)rQ)N)NNFNr) rrvrwrrrrr#rrrSrSrrTrs-2 ErcsVeZdZdZedfdd ZddZddZedd d Z e e dddZ Z S)_BaseVectorSourceEstimater^Ncs(t|dstt||||||dS)Nr)rrsrrrrCrBr>r@rrrrSrTrsz"_BaseVectorSourceEstimate.__init__cCs,tjj|jdd}|||j|j|j|jS)zCompute magnitude of activity without directionality. Returns ------- stc : instance of SourceEstimate The source estimate without directionality information. rrO) rHlinalgnormrCrrBr>r@r)rZdata_magrSrSrTrsz#_BaseVectorSourceEstimate.magnitudecs$tfddt||jD}|S)Ncsg|]\}}t||qSrS)r)rrrrrSrTrsz>_BaseVectorSourceEstimate._get_src_normals..)rHrrrB)rrrnormalsrSrrT_get_src_normalss z*_BaseVectorSourceEstimate._get_src_normalsTc Cst|ttjfdt|dtfdt|trtd|ddd|dkrp|dkrVtdtd|| ||}n&|d ks|t |j }t |j std |j j tjtjf|j tjkrtjntj}||}|jd d |j jd kst tjj|d d\}}}|dddddf}|dkrr@r) rrrrrr;urrZsignsrZ data_normrQrSrSrTprojects^*            (z!_BaseVectorSourceEstimate.projectrhotrr皙?rlateralrrrrrc CsDt|||||||||| | | | | ||||||||||||||||dSN)rrrrrr  brain_alpha overlay_alpha vector_alpha scale_factorr r r rrrrrrrrrrrrrrrr)r4rrrrrrr rrrrr r r rrrrrrrrrrrrrrrrrSrSrTrjs@ z_BaseVectorSourceEstimate.plot)NNNNN)NT)NrrrrTrNrNrNNrTrrrrNNrrNrrNNN)rrvrwrrrrrr#rr"r4rrrSrSrrTrsL  SrcseZdZdZdZeed%fdd Zeed&ddZ e d'dddddZ e ddddZ e d(ddd d!d"Z d)d#d$ZZS)*_BaseVolSourceEstimater|NwhiterrrT皙?axialrrrrrrrc sHtj||||||||| | | | | |||||||||||||||||dS)N)rr}rrrrr r r r r rrrrrrrrrrrrrrrrrrr)rr)rrr}rrrrr r r r r rrrrrrrrrrrrrrrrrrrrrSrTplot_3ds@ z_BaseVolSourceEstimate.plot_3dstat_mapT1.mgzcCs:|jdkr|n|}t|||||||||| | | | | dS)Nr^) rrr rbg_imgrrrr showr initial_posr)rrr5)rrrr rrrrrr rrrrrCrSrSrTrs"z_BaseVolSourceEstimate.plotFmri_resolutionrc Cst||||d|||dS)anExtract label time courses for lists of labels. This function will extract one time course for each label. The way the time courses are extracted depends on the mode parameter. Parameters ---------- %(labels_eltc)s %(src_eltc)s %(mode_eltc)s %(allow_empty_eltc)s %(mri_resolution_eltc)s %(verbose)s Returns ------- %(label_tc_el_returns)s See Also -------- extract_label_time_course : Extract time courses for multiple STCs. Notes ----- %(eltc_mode_notes)s F)rrrrrr)rrrrrrrrSrSrTrsz0_BaseVolSourceEstimate.extract_label_time_courserc Cst|jdkrtdt|tdfdt|tr8|g}nd|t|i}t|||fdd}t|dksjt|d}|j}t |jd|j}|j ||jd|g}}|j |||j |j|jd } | S) a*Get a source estimate object restricted to a label. SourceEstimate contains the time course of activation of all sources inside the label. Parameters ---------- label : str | int The label to use. Can be the name of a label if using a standard FreeSurfer atlas, or an integer value to extract from the ``mri``. mri : str Path to the atlas to use. src : instance of SourceSpaces The volumetric source space. It must be a single, whole-brain volume. %(verbose)s Returns ------- stc : VolSourceEstimate | VolVectorSourceEstimate The source estimate restricted to the given label. Notes ----- .. versionadded:: 0.21.0 rzBThis method can only be used with whole-brain volume source spaceszint-likerz Volume ID %sF)rrr:)rJrBrr%rrr+_volume_labelsrsrHrrCrr>r@r) rrmrirrZ volume_labelrBZkeepr}rrSrSrTrs"  z_BaseVolSourceEstimate.in_labelrnifti1rc CsBddl}t|ddt||d}|j||||d} || |dS)a%Save a volume source estimate in a NIfTI file. Parameters ---------- fname : str The name of the generated nifti file. src : list The list of source spaces (should all be of type volume). dest : 'mri' | 'surf' If 'mri' the volume is defined in the coordinate system of the original T1 image. If 'surf' the coordinate system of the FreeSurfer surface is used (Surface RAS). mri_resolution : bool It True the image is saved in MRI resolution. .. warning:: If you have many time points, the file produced can be huge. format : str Either 'nifti1' (default) or 'nifti2'. .. versionadded:: 0.17 %(overwrite)s .. versionadded:: 1.0 %(verbose)s .. versionadded:: 1.0 Returns ------- img : instance Nifti1Image The image object. Notes ----- .. versionadded:: 0.9.0 rNrurvr)destrrd)Znibabelr%r1 as_volumer) rrvrrrrdrwrZnibZimgrSrSrTsave_as_volumes(   z%_BaseVolSourceEstimate.save_as_volumecCs4ddlm}|jdkr|n|}||||d|dS)aExport volume source estimate as a nifti object. Parameters ---------- src : instance of SourceSpaces The source spaces (should all be of type volume, or part of a mixed source space). dest : 'mri' | 'surf' If 'mri' the volume is defined in the coordinate system of the original T1 image. If 'surf' the coordinate system of the FreeSurfer surface is used (Surface RAS). mri_resolution : bool It True the image is saved in MRI resolution. .. warning:: If you have many time points, the file produced can be huge. format : str Either 'nifti1' (default) or 'nifti2'. Returns ------- img : instance of Nifti1Image The image object. Notes ----- .. versionadded:: 0.9.0 r)_interpolate_datar^T)rZ mri_spaceoutput)Zmorphrrr)rrrrrdrrCrSrSrTr/s  z _BaseVolSourceEstimate.as_volume)NrrrrrTrrNNrTrrrrNNrrrNrNrrNNN) NNrrTrrrTNNN)rF)rFr)rFr)rrvrwrrr"r3rr5rrrrrrrrSrSrrTrs~ "-.rcs.eZdZdZeddddfdd ZZS) raContainer for volume source estimates. Parameters ---------- data : array of shape (n_dipoles, n_times) | tuple, shape (2,) The data in source space. The data can either be a single array or a tuple with two arrays: "kernel" shape (n_vertices, n_sensors) and "sens_data" shape (n_sensors, n_times). In this case, the source space data corresponds to ``np.dot(kernel, sens_data)``. %(vertices_volume)s %(tmin)s %(tstep)s %(subject_optional)s %(verbose)s Attributes ---------- subject : str | None The subject name. times : array of shape (n_times,) The time vector. %(vertices_volume)s data : array of shape (n_dipoles, n_times) The data in source space. shape : tuple The shape of the data. A tuple of int (n_dipoles, n_times). See Also -------- SourceEstimate : A container for surface source estimates. VolVectorSourceEstimate : A container for volume vector source estimates. MixedSourceEstimate : A container for mixed surface + volume source estimates. Notes ----- .. versionadded:: 0.9.0 rQFNrcst|dd}td|dddg|dkrCan only write non-complex data to .stc or .w, use .h5 insteadr)rxryrxrrrr)rzr{rzrrN)r1r$rJrBrKrCr;rrrr]r>r@rtrr)rrvrrwrrrSrTr|s0         zVolSourceEstimate.save)rQ)rrvrwrrrrrSrSrrTrSs'rc@s&eZdZdZeZeedddZdS)raContainer for volume source estimates. Parameters ---------- data : array of shape (n_dipoles, 3, n_times) The data in source space. Each dipole contains three vectors that denote the dipole strength in X, Y and Z directions over time. %(vertices_volume)s %(tmin)s %(tstep)s %(subject_optional)s %(verbose)s Attributes ---------- subject : str | None The subject name. times : array of shape (n_times,) The time vector. %(vertices_volume)s data : array of shape (n_dipoles, n_times) The data in source space. shape : tuple The shape of the data. A tuple of int (n_dipoles, n_times). See Also -------- SourceEstimate : A container for surface source estimates. VectorSourceEstimate : A container for vector source estimates. MixedSourceEstimate : A container for mixed surface + volume source estimates. Notes ----- .. versionadded:: 0.9.0 NrrrrTrrrrrrrrc CsFtj|||||||||| | | | | ||||||||||||||||dSr)rrrrSrSrTrs@ zVolVectorSourceEstimate.plot_3d)NrrrrTrNrNrNNrTrrrrNNrrNrrNNN) rrvrwrrrr"r4rrSrSrSrTrs>%rc@seZdZdZeZdS)raContainer for vector surface source estimates. For each vertex, the magnitude of the current is defined in the X, Y and Z directions. Parameters ---------- data : array of shape (n_dipoles, 3, n_times) The data in source space. Each dipole contains three vectors that denote the dipole strength in X, Y and Z directions over time. vertices : list of array, shape (2,) Vertex numbers corresponding to the data. The first element of the list contains vertices of left hemisphere and the second element contains vertices of right hemisphere. %(tmin)s %(tstep)s %(subject_optional)s %(verbose)s Attributes ---------- subject : str | None The subject name. times : array of shape (n_times,) The time vector. shape : tuple The shape of the data. A tuple of int (n_dipoles, n_times). See Also -------- SourceEstimate : A container for surface source estimates. VolSourceEstimate : A container for volume source estimates. MixedSourceEstimate : A container for mixed surface + volume source estimates. Notes ----- .. versionadded:: 0.15 N)rrvrwrrrrSrSrSrTrs(rcsFeZdZdZdZed fdd ZeddZddZ d d Z Z S) rlrNcs:t|trt|dkrtdtj||||||ddS)NrbzHVertices must be a list of numpy arrays with one array per source space.)rBr>r@rr)rrrJrKrrrrrSrTr% s z!_BaseMixedSourceEstimate.__init__cCstdd|jddDS)Ncss|]}t|VqdSrrrrSrSrTr1 sz8_BaseMixedSourceEstimate._n_surf_vert..rbr"r rSrSrT _n_surf_vert/ sz%_BaseMixedSourceEstimate._n_surf_vertcCs@|jdkrt}nt}||jd|j|jdd|j|j|jS)zReturn the cortical surface source estimate. Returns ------- stc : instance of SourceEstimate or VectorSourceEstimate The surface source estimate. r^Nrb) rrrrCrrBr>r@rrrrSrSrTr}3 s  z _BaseMixedSourceEstimate.surfacecCs@|jdkrt}nt}||j|jd|jdd|j|j|jS)zReturn the volume surface source estimate. Returns ------- stc : instance of VolSourceEstimate or VolVectorSourceEstimate The volume source estimate. r^Nrb) rrrrCrrBr>r@rrrSrSrTr|C s  z_BaseMixedSourceEstimate.volume)NNNNN) rrvrwrrrrrxrr}r|rrSrSrrTrl s  rlc@seZdZdZdS)raContainer for mixed surface and volume source estimates. Parameters ---------- data : array of shape (n_dipoles, n_times) | tuple, shape (2,) The data in source space. The data can either be a single array or a tuple with two arrays: "kernel" shape (n_vertices, n_sensors) and "sens_data" shape (n_sensors, n_times). In this case, the source space data corresponds to ``np.dot(kernel, sens_data)``. vertices : list of array Vertex numbers corresponding to the data. The list contains arrays with one array per source space. %(tmin)s %(tstep)s %(subject_optional)s %(verbose)s Attributes ---------- subject : str | None The subject name. times : array of shape (n_times,) The time vector. vertices : list of array Vertex numbers corresponding to the data. The list contains arrays with one array per source space. data : array of shape (n_dipoles, n_times) The data in source space. shape : tuple The shape of the data. A tuple of int (n_dipoles, n_times). See Also -------- SourceEstimate : A container for surface source estimates. VectorSourceEstimate : A container for vector source estimates. VolSourceEstimate : A container for volume source estimates. VolVectorSourceEstimate : A container for Volume vector source estimates. Notes ----- .. versionadded:: 0.9.0 N)rrvrwrrSrSrSrTrT src@seZdZdZeZdS)raContainer for volume source estimates. Parameters ---------- data : array, shape (n_dipoles, 3, n_times) The data in source space. Each dipole contains three vectors that denote the dipole strength in X, Y and Z directions over time. vertices : list of array, shape (n_src,) Vertex numbers corresponding to the data. %(tmin)s %(tstep)s %(subject_optional)s %(verbose)s Attributes ---------- subject : str | None The subject name. times : array, shape (n_times,) The time vector. vertices : array of shape (n_dipoles,) The indices of the dipoles in the source space. data : array of shape (n_dipoles, n_times) The data in source space. shape : tuple The shape of the data. A tuple of int (n_dipoles, n_times). See Also -------- MixedSourceEstimate : A container for mixed surface + volume source estimates. Notes ----- .. versionadded:: 0.21.0 N)rrvrwrrrrSrSrSrTr s%rcCsHt|dkst|ddddd}t|t}d|j|dd<|S)z!Get the volume source space mask.rrr\NrTrt)rJrsrHrjboolZflat)rr\r'rSrSrT _get_vol_mask s  rcCs2ddlm}t|}||jd|i}t||}|S)Nr) grid_to_graphr')Zsklearn.feature_extractionrrr\_get_adjacency_from_edges)rn_timesrr'edges adjacencyrSrSrT"_spatio_temporal_src_adjacency_vol s   rcCsR|dddkrtddd|D}tdgdd|Ddd}tddt|||D}t||}d dt||D}td d |D|jd|krtd d d|Ddd|Dkrtdt|}dt t |t|t |}|rNt d|t ||}t |d}|}||}|dd|f}|}|S)Nruse_triszpThe source space does not appear to be an ico surface. adjacency cannot be extracted from non-ico source spaces.cSsg|]}t|dqSr)rHuniquerrrSrSrTr sz7_spatio_temporal_src_adjacency_surf..cSsg|] }t|qSrSr)ru_vrSrSrTr srcSs&g|]\}}}t||d|qSr)rHr)rrroffrSrSrTr scSs g|]\}}t||dqSrt)rHr)rrrrSrSrTr scss|] }|jVqdSr)r)rrrSrSrTr sz6_spatio_temporal_src_adjacency_surf..z*Used vertices do not match adjacency shapecSsg|]}t|qSrSr)rmrSrSrTr scSsg|]}t|dqSrrrrSrSrTr sz-Vertex mask does not match number of verticesdz%0.1f%% of original source space vertices have been omitted, tri-based adjacency will have holes. Consider using distance-based adjacency or morphing data to all source space vertices.)rrHZcumsumrrspatio_temporal_tris_adjacencyrr\rKrGrJr!tiler&tocsrtocoo)rrZ used_vertsZoffstrisrZmasksmissingrSrSrT#_spatio_temporal_src_adjacency_surf s4"     " rcCsT|dddkr0|dk r$td|t||}n |dk rFt|||}n t||}|S)aKCompute adjacency for a source space activation over time. Parameters ---------- src : instance of SourceSpaces The source space. It can be a surface source space or a volume source space. n_times : int Number of time instants. dist : float, or None Maximal geodesic distance (in m) between vertices in the source space to consider neighbors. If None, immediate neighbors are extracted from an ico surface. %(verbose)s Returns ------- adjacency : ~scipy.sparse.coo_matrix The adjacency matrix describing the spatio-temporal graph structure. If N is the number of vertices in the source space, the N first nodes in the graph are the vertices are time 1, the nodes from 2 to 2N are the vertices during time 2, etc. rrZvolNz4dist must be None for a volume source space. Got %s.)rKrspatio_temporal_dist_adjacencyr)rrdistrrrSrSrTspatio_temporal_src_adjacency s  rcCs,t|dd}t||t|df}|S)a*Get tris defined for a certain grade. Parameters ---------- grade : int Grade of an icosahedral mesh. %(verbose)s Returns ------- tris : list 2-element list containing Nx3 arrays of tris, suitable for use in spatio_temporal_tris_adjacency. NFr) _get_ico_trisrHrmax)graderrrrSrSrT grade_to_tris s rcCsZddlm}|r,tdtt||}t|}||j|j ddd }t ||S)aCompute adjacency from triangles and time instants. Parameters ---------- tris : array N x 3 array defining triangles. n_times : int Number of time points. remap_vertices : bool Reassign vertex indices based on unique values. Useful to process a subset of triangles. Defaults to False. %(verbose)s Returns ------- adjacency : ~scipy.sparse.coo_matrix The adjacency matrix describing the spatio-temporal graph structure. If N is the number of vertices in the source space, the N first nodes in the graph are the vertices are time 1, the nodes from 2 to 2N are the vertices during time 2, etc. rsparsezReassigning vertex indices.csrrc) scipyrrrrHrrreyer\rr)rrremap_verticesrrrrSrSrTr# s  rcCsddlm}|dddkr$tddd|D}|D]6}t|tjrXtj ||dk<q6|j|jdkdkq6||}t|j||jdd<| }| | }t ||S) aCompute adjacency from distances in a source space and time instants. Parameters ---------- src : instance of SourceSpaces The source space must have distances between vertices computed, such that src['dist'] exists and is useful. This can be obtained with a call to :func:`mne.setup_source_space` with the ``add_dist=True`` option. n_times : int Number of time points. dist : float Maximal geodesic distance (in m) between vertices in the source space to consider neighbors. %(verbose)s Returns ------- adjacency : ~scipy.sparse.coo_matrix The adjacency matrix describing the spatio-temporal graph structure. If N is the number of vertices in the source space, the N first nodes in the graph are the vertices are time 1, the nodes from 2 to 2N are the vertices during time 2, etc. r) block_diagrNzVsrc must have distances included, consider using setup_source_space with add_dist=TruecSs4g|],}|d|dddfdd|dfqS)rrtNrSrrSrSrTre sz2spatio_temporal_dist_adjacency..r) scipy.sparser rrrHrinfrCZ less_equalrZeliminate_zerosrr)rrrrZsparse_block_diagblocksblockrrSrSrTrF s  rcCs t|d|S)a:Compute adjacency for a source space activation. Parameters ---------- src : instance of SourceSpaces The source space. It can be a surface source space or a volume source space. dist : float, or None Maximal geodesic distance (in m) between vertices in the source space to consider neighbors. If None, immediate neighbors are extracted from an ico surface. %(verbose)s Returns ------- adjacency : ~scipy.sparse.coo_matrix The adjacency matrix describing the spatial graph structure. r)rrrrrSrSrTspatial_src_adjacencyu srcCs t|d|S)aCompute adjacency from triangles. Parameters ---------- tris : array N x 3 array defining triangles. remap_vertices : bool Reassign vertex indices based on unique values. Useful to process a subset of triangles. Defaults to False. %(verbose)s Returns ------- adjacency : ~scipy.sparse.coo_matrix The adjacency matrix describing the spatial graph structure. r)r)rr rrSrSrTspatial_tris_adjacency srcCs t|d|S)aCompute adjacency from distances in a source space. Parameters ---------- src : instance of SourceSpaces The source space must have distances between vertices computed, such that src['dist'] exists and is useful. This can be obtained with a call to :func:`mne.setup_source_space` with the ``add_dist=True`` option. dist : float Maximal geodesic distance (in m) between vertices in the source space to consider neighbors. %(verbose)s Returns ------- adjacency : ~scipy.sparse.coo_matrix The adjacency matrix describing the spatial graph structure. r)rrrSrSrTspatial_dist_adjacency srcsddlmddlm}t|dd}||dd|dd|dd|dd}j||ktd }fd d |jD} |d|g |j |dgg}|S) aGet vertices on each hemisphere that are close to the other hemisphere. Parameters ---------- src : instance of SourceSpaces The source space. Must be surface type. dist : float Maximal Euclidean distance (in m) between vertices in one hemisphere compared to the other to consider neighbors. %(verbose)s Returns ------- adjacency : ~scipy.sparse.coo_matrix The adjacency matrix describing the spatial graph structure. Typically this should be combined (addititively) with another existing intra-hemispheric adjacency matrix, e.g. computed using geodesic distances. rr)cdistr}rerrrtrrXcsg|]}j||ftdqS)rX) csr_matrixrI)rnvrrSrTr sz0spatial_inter_hemi_adjacency..) r rscipy.spatial.distancerrrrIr\rZhstackrM)rrrrZadjZemptiesrSrrTspatial_inter_hemi_adjacency s   rc Cshddlm}|jd}td||jj}|tt |dddfd|f}|jdddf| }|j dddf| }|dkr|t |ddddft |dddf } |t d|dddft |dddf } t || | f}t || | f}tj |jj|d||dtjd} || ||ff||fdd} | S) z3Given edges sparse matrix, create adjacency matrix.r) coo_matrixz#-- number of adjacent vertices : %dNrrbrX)r\)r rr\rrcolrrHrr.ravelrowrZonesrCr) rrrrrnnzZauxrrodrCrrSrSrTr s.  &   rcCst|}|s|dS|SdS)zGet triangles for ico surface.rN)r)rrZ return_surfZicorSrSrTr srcCsZt|dd\}}}tt|dddf|}tj|tt|}|||dS)NFrr)rrHrr#rrrMrJ)fliprCUrVrscalerSrSrT _pca_flip sr&cCstj|ddSNrrOrHr5r"rCrSrSrT r*cCstj||ddSr'r(r)rSrSrTr* r+cCstjt|ddSr')rHrrr)rSrSrTr* r+)r5 mean_fliprZpca_flipc csXdd|D}t||D]\}}||d<qz dVW5t||D]\}}||d<q@XdS)NcSsg|] }|dqSrrSrrSrSrTr sz'_temporary_vertices..rt)r)rrBZ orig_verticesrrrSrSrT_temporary_vertices s  r-cCst|dk rp|dk rpt|j|jddddt||jdD]:\}}}t||d}|r4td|t ||fq4dS)NFsource space subject stc.subjectrZ first_kindZ second_kind)leftrightrtzO%d/%d %s hemisphere stc vertices missing from the source space, likely mismatch) r_subjectrrrBrHrrrKrJ)rQrrrrZ n_missingrSrSrT_check_stc_src s r4c Csddlm}ddlm}m}m} t|||dkr@dd|Dn|j} dd| D} t} t} t}t |D]\}}|r|d n|j }t |t |d dd d d d t |t |ddd d dd |r.t |tst|d}|jddkr||dd}n|dkr||jdd}| || dqnt||| fd|f|jdkr^|j|jg}n|g}t}|D]}|jdkrt| d|j}t| d|}nF|jdkrt| d|j}| dt| d|}ntd|j||qnt|}d}t|dkr$||jd}n@|dkrdt||j$|||dddddf}W5QRX| || |qnt|rdt|t ||f}|st|n&|d7}|dkrt!"|nt#|| | fS)z8Prepare indices and flips for extract_label_time_course.rrr)label_sign_fliprrNcSsg|] }|dqSrrSrrSrSrTr4 sz-_prepare_label_extraction..cSsg|] }t|qSrSr)rvnrSrSrTr5 srFz label.subjectr/r0r3r.rnamer5rOz labels[%d]rrrzlabel %s has invalid hemir5rrbz=source space does not contain any vertices for %d label%s: %sz Assigning all-zero time series.ignore)$r rrr5rrr4rBrrmrrgetattrrrFrsr\rirr5r%rrrrHZ intersect1drrKr7rrJr-rrrr!)rQrrrr use_sparserr5rrrtnvertZ label_flip label_vertidxZ bad_labelsZlirrvertidxZ sub_labelsZ this_vertidxZslabelZ this_verticesZ this_flipmsgrSrSrT_prepare_label_extraction& s             (      r@c CsDt|ddtddtjdd|ddDdd iDtjS) NrZ src_mri_tcSsg|]}|jddqS)Forder)r)rr!rSrSrTr sz_vol_src_rr..css|]}t|VqdSr)rHr.rrSrSrTr sz_vol_src_rr..r\ZindexingZij)rrHrZZmeshgridrGrMrrSrSrT _vol_src_rr s rEcs$ddlmjdkstjd}tdt|dttfd|t |rT|}d}n:t |d krrt d t |f|\}}d }t|dd |t d |ftt|dd}|d}t|jjdkrttkstdttj|r*fddtdD}t||dd}t|tsHt|d}ddd} | dkrttd|d| d}} tj|| ddstdtfdddD} |j } | | krtd | | f|j!d!d"}|rt} d} dd#}|j dt"| kst|j |j#t dd$fks:t|dddd%f}|D]@\}}||k}||}| $t||d&| |j ddk7} qZnldd%t%}t&||fd'd(|'D}fd)d(t(||)D} t*d*d|D} t d+| t | f| S),Nr)rr|z! when using a volume source spacezuse volume atlas labelsrurTrbz4labels, if list or tuple, must have length 2, got %sFz labels[0]zReading atlas %s)rCrCrz4Non-integer values present in atlas, cannot labelizecsi|]\}}|kr||qSrSrS)rkr) atlas_valuesrSrT sz"_volume_labels..rz labels[1])r7 vox_mri_tzOCannot use volumetric atlas if no mri was supplied during source space creationtransgư>)ZatolzCatlas vox_mri_t does not match that used to create the source spacec3s|]}dd|VqdS)rZmri_NrS)rrFrDrSrTr sz!_volume_labels..)rQheightdepthz7atlas shape %s does not match source space MRI shape %srArBZ interpolatorrrt)rr7rcsg|]}|kqSrSrS)rrq) src_valuesrtrSrTr sz"_volume_labels..cs g|]\}}|d|dqS)r)rr7rrS)rrrq)rrrSrTr scss|]}t|dkVqdSrrrrSrSrTr sz?%d/%d atlas regions had at least one vertex in the source space)+rrrrsr3r r%rrr.rJrKrrr rrHrr;isfiniteroundrrrerr itemsrrrFgetZallcloser\rrVrrirEr r}rkeysr)rrrrrZ infer_labelsZvol_infoZ atlas_datarIZwantZ src_shapeZ atlas_shapeZ out_labelsrinterprFrr'rrrBrS)rrGrrMrrtrTr s         "    rcCsttdgS)Nr)sorted _label_funcsrRrSrSrSrT_get_default_label_modes srVcCst|ttfrdStSdS)N)r5rr)rrrrV)rQrSrSrT_get_allowed_label_modes s rWr5T)rrrrccs(ddlm}|dkr"|dkr"d}nt|t|j}td|t|dkr^t|tsX|g}d} nt |||}t |} t |} |dkrt |d dnd} | | } d} }t |D]r\}}t|t d |fd td|t|d t|ttfr|d krdn|}n|d kr dn|}| dkrXt|j} tdd| D}t|||||| \}}t|}t | t |jkrttdt| |jD]J\}}t |t |krtdt |t |ft||stdqtd| |ftj| f|jjdd|jj d}t t||D]\}\}}|dk rt||j!r|s>t"|jd|jjdksZt"t#|j|jjddf}||}|jdf|jjdd|_n |j|}|||||<q|d| $}t |d dD]@\}}|dkr||}tj%|j||dd|| |<|}q|VqdS)Nrrr8r}r)r}rFrrbzstcs[%d]zsource estimatez1when using a vector and/or volume source estimaterr5r,cSsg|] }t|qSrSrrrSrSrTr sz2_gen_extract_label_time_course..z$stc not compatible with source spacezstc not compatible with source space. stc has %s time series but there are %s vertices in source space. Ensure you used src from the forward or inverse operator, as forward computation can exclude vertices.z0Extracting time courses for %d labels (mode: %s)rrXrrO)&r rr%rrr$rVrrrrrJrmrrWrrrrNrBrHrZr@rUrKrrrrrjrCr\r;rrsrLrr5)r^rrrrrrrrr;Zn_modeZn_meanZn_labelsrtrRsirQr<r=Zsrc_flipr6svnlabel_tcrmr>r"Z this_datar=rZv2rSrSrT_gen_extract_label_time_course s            r[rrc CsTt|tttfs |g}d}d}nd}t||||||d} |sDt| } |sP| d} | S)aExtract label time course for lists of labels and source estimates. This function will extract one time course for each label and source estimate. The way the time courses are extracted depends on the mode parameter (see Notes). Parameters ---------- stcs : SourceEstimate | list (or generator) of SourceEstimate The source estimates from which to extract the time course. %(labels_eltc)s %(src_eltc)s %(mode_eltc)s %(allow_empty_eltc)s return_generator : bool If True, a generator instead of a list is returned. %(mri_resolution_eltc)s %(verbose)s Returns ------- %(label_tc_el_returns)s Notes ----- %(eltc_mode_notes)s If encountering a ``ValueError`` due to mismatch between number of source points in the subject source space and computed ``stc`` object set ``src`` argument to ``fwd['src']`` or ``inv['src']`` to ensure the source space is the one actually used by the inverse to compute the source time courses. FT)rrrr)rrrrr[) r^rrrrrrrZreturn_severalrZrSrSrTrH s$&r{Gz?rpialc ! sddlm} m} ddlm} t| dt|tdt|dtfdtd|d |dkrjt j d d d d } |t fd d |D}|tjhkstdt|ttjdddfddD}t|r|fddttDt|ddd d\}}t|tdddtd ddk rhfdddD}|dkrttddtdd|D}tddt||D}d}n\dkrtdd|D}|ddtjkr t||}ntd dt||D}d }t t!t"t#d!}td"|j$t|%||j$}t& d#td$t'd%t|d&|j$d'|d( |r|j$dkrt& d)t(t |d*d d+d,d-| )d.}t& d/|rd0nd1d2|d3d4| |}|j*t|tfkst+t||kd5d}t& d6t|d7t|d8t,d9|||d}|d:krt-|j*d}tj.|dd}|d;kr|||fnd9}|/d||||f<n,|dt'|d?d@2fdAd |D|j3}|rztj4t0dBd |Dtj5f|j6dC}|||<dDd|D}n@|j$dkst+|}t|ddE} ||| k||| k| g}|||j5dd9j dF| dGS)Ha Create a STC from ECoG, sEEG and DBS sensor data. Parameters ---------- evoked : instance of Evoked The evoked data. Must contain ECoG, sEEG or DBS channels. %(trans)s subject : str The subject name. distance : float Distance (m) defining the activation "ball" of the sensor. mode : str Can be "sum" to do a linear sum of weights, "weighted" to make this a weighted sum, "nearest" to use only the weight of the nearest sensor, or "single" to do a distance-weight of the nearest sensor. Default is "sum". See Notes. .. versionchanged:: 0.24 Added "weighted" option. project : bool If True, project the sensors to the nearest ``'pial`` surface vertex before computing distances. Only used when doing a surface projection. %(subjects_dir)s src : instance of SourceSpaces The source space. .. warning:: If a surface source space is used, make sure that ``surface='pial'`` was used during construction, or that you set ``surface='pial'`` here. %(picks_base)s good sEEG, ECoG, and DBS channels. .. versionadded:: 0.24 surface : str | None The surface to use if ``src=None``. Default is the pial surface. If None, the source space surface will be used. .. versionadded:: 0.24.1 %(verbose)s Returns ------- stc : instance of SourceEstimate The surface source estimate. If src is None, a surface source estimate will be produced, and the number of vertices will equal the number of pial-surface vertices that were close enough to the sensors to take on a non-zero volue. If src is not None, a surface, volume, or mixed source estimate will be produced (depending on the kind of source space passed) and the vertices will match those of src (i.e., there may be me many all-zero values in stc.data). Notes ----- For surface projections, this function projects the ECoG sensors to the pial surface (if ``project``), then the activation at each pial surface vertex is given by the mode: - ``'sum'`` Activation is the sum across each sensor weighted by the fractional ``distance`` from each sensor. A sensor with zero distance gets weight 1 and a sensor at ``distance`` meters away (or larger) gets weight 0. If ``distance`` is less than half the distance between any two sensors, this will be the same as ``'single'``. - ``'single'`` Same as ``'sum'`` except that only the nearest sensor is used, rather than summing across sensors within the ``distance`` radius. As ``'nearest'`` for vertices with distance zero to the projected sensor. - ``'nearest'`` The value is given by the value of the nearest sensor, up to a ``distance`` (beyond which it is zero). - ``'weighted'`` The value is given by the same as ``sum`` but the total weight for each vertex is 1. (i.e., it's a weighted sum based on proximity). If creating a Volume STC, ``src`` must be passed in, and this function will project sEEG and DBS sensors to nearby surrounding vertices. Then the activation at each volume vertex is given by the mode in the same way as ECoG surface projections. .. versionadded:: 0.22 r)rpdistr)EvokedevokedrNr)rsinglenearestweightedT)ZecogZseegZdbsc3s |]}jd|dVqdS)Zchs coord_frameN)r)rpickr`rSrTr sz#stc_near_sensors..z3Channels must be in the head coordinate frame, got rOcsg|]}j|qSrSZch_namesrrrfrSrTr sz$stc_near_sensors..csg|]}|kr|qSrSrSrh)nan_indsrrSrTr sheadr) allow_noneFrc s2g|]*}ttd|dddqS)rzr{rr?)rrr|)rr)rr r}rSrTr s  )rrr}zwhen src is NonecSs(g|] }t|tt|dtjdqS)rz)rrtrrd)rFrHr.rJr ZFIFFV_COORD_MRI)rrrSrSrTr scSsg|]\}}||dqSrrSrZs_rrrrSrSrTr scSsg|]}|d|dqS)rrtrSrrSrSrTr srdcSsg|]\}}||dqSrrSrlrSrSrTr s)r}r|rzsrc.kindzProjecting data from z sensorz onto  z vertices: z modez# Projecting sensors onto surface)rrb)Z project_rrsmethodrbrWz Minimum z projected zintra-sensor distance: z0.1fz mmrz z / z non-zero verticesr)rarbrarc)r9ZChannelz missing in STC: z, c3s|]}j|VqdSrrg)rmirfrSrTrA scss|]}t|dVqdS)rtNrrrSrSrTrG srXcSsg|]}|dqSrrrrSrSrTrJ srtr!)rr)7rrr^r`r_r%rrr$rrrresetr ZFIFFV_COORD_HEADrrTZ_get_channel_positionsrHr&isnanrrJZ drop_channelsrlrrrrrrrFrrrrrRrrrminr\rsmaximumr.Zargmaxfillrr!r|rCrjrr;)!r`rJrZdistancerrr rZpicksr}rrr^r_framesZnan_chsrZsurf_rrZrrsZkeep_allrZmin_distdistsrBrnZrange_rvalsZnormsrZnz_datarCr=rS)r`rirrr r}rTstc_near_sensors sX               0        ,  ry)N)N)NNNNFNN)NN)N)FN)N)NN)FN)N)N)N)NF)rFF)r\rTNNNr]N)| contextlibros.pathpathrtypesrnumpyrHrrrrr`rfilterrfixesrZ _freesurferr r r r Z io.constantsr Zio.pickrr}rrrrZ source_spacerrrrrrZ transformsrrutilsrrrrrr r!r"r#r$r%r&r'r(r)r*r+r,r-r.r/r0r1r2Zvizr3r4r5Zio.baser6Z io.meas_infor7rUr]rhrorrrtrrrrrrrkrrrrrrrlrrrrrrrrrrrrrrrr&rUcontextmanagerr-r4r@rErrVrWr[rryrSrSrSrTs          h  .  (    -1s PT F 04- - # )  " .         d S U;