U f{j @stdZddlmZddlmZddlZddlmZddl m Z m Z dd l m Z dd lmZdd lmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)dd l*m+Z+dd l,m-Z-m.Z.ddl/m0Z0m1Z1m2Z2m3Z3m4Z4ddl5m6Z6m7Z7ddl8m9Z9m:Z:m;Z;mZ>m?Z?dRddZ@dSddZAdTddZBdddddddZCdUd!d"ZDd#d$ZEdVd%d&ZFdWd'd(ZGd)d*ZHdXd+d,ZIedYd.d/ZJedZd0d1ZKed[d2d3ZLGd4d5d5e7e+eeZMeGd6d7d7eMZNeGd8d9d9eMeZOd\d;d<ZPd=d>ZQd?d@ZRdAdBZSd]dCdDZTdEdFZUed^ddGdHdIZVdJdKZWd_dLdMZXdNdOZYd`dPdQZZdS)azA module which implements the time-frequency estimation. Morlet code inspired by Matlab code from Sheraz Khan & Brainstorm & SPM deepcopy)partialN) dpss_windows)rescale_check_baseline) next_fast_len) parallel_func)loggerverbose _time_mask _freq_mask check_fname sizeof_fmtGetEpochsMixin TimeMixin_prepare_read_metadatafill_doc_prepare_write_metadata_check_event_id _gen_events SizeMixin _is_numeric _check_option_validate_type_check_combine_check_pandas_installed_check_pandas_index_arguments_check_time_format_convert_times_build_data_framewarn_import_h5io_funcs)UpdateChannelsMixin)_merge_ch_data_pair_grad_sensors) pick_info _picks_to_idx channel_type _pick_inst_get_channel_types)Info ContainsMixin) figure_nobarplt_show _setup_cmap_connection_line_prepare_joint_axes_setup_vmin_vmax_set_title_multiple_electrodes@FcCszt}t|}t|}t|dkr0td|jdkrP|jt|krPtdt|D]\}}t|dkrx||}n|d}|dkr|dtj |} n|dtj |} t dd| d |} tj | ddd  | ddf} t d tj || } t | d  d| d } |rDt d tj || d } | | 8} | | }|t dtj|}||qX|S)aCompute Morlet wavelets for the given frequency range. Parameters ---------- sfreq : float The sampling Frequency. freqs : array Frequency range of interest (1 x Frequencies). n_cycles : float | array of float, default 7.0 Number of cycles. Fixed number or one per frequency. sigma : float, default None It controls the width of the wavelet ie its temporal resolution. If sigma is None the temporal resolution is adapted with the frequency like for all wavelet transform. The higher the frequency the shorter is the wavelet. If sigma is fixed the temporal resolution is fixed like for the short time Fourier transform and the number of oscillations increases with the frequency. zero_mean : bool, default False Make sure the wavelet has a mean of zero. Returns ------- Ws : list of array The wavelets time series. r2all frequencies in 'freqs' must be greater than 0.r7n_cycles should be fixed or defined for each frequency.N@g@?@r?)listnp atleast_1darrayany ValueErrorsizelen enumeratepiarangeZr_expsqrtlinalgnormravelappend)sfreqfreqsn_cyclessigma zero_meanWskf this_n_cyclesZsigma_tt oscillationZgaussian_enveloppe real_offsetWr^U/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/time_frequency/tfr.pymorlet(s2    " r`@cCsft}t|}t|dkr&td|dkr6tdtt|d}t|}|jdkrr|jt |krrtdt |D]}t}t |D]\} } t |dkr|| } n|d} | t | } t d| d|} td tj| | | d}t| jd|d|\}}|||}|r,|}||8}|td tj|}||q||qz|S) aCompute DPSS tapers for the given frequency range. Parameters ---------- sfreq : float The sampling frequency. freqs : ndarray, shape (n_freqs,) The frequencies in Hz. n_cycles : float | ndarray, shape (n_freqs,), default 7. The number of cycles globally or for each frequency. time_bandwidth : float, default 4.0 Time x Bandwidth product. The number of good tapers (low-bias) is chosen automatically based on this to equal floor(time_bandwidth - 1). Default is 4.0, giving 3 good tapers. zero_mean : bool | None, , default False Make sure the wavelet has a mean of zero. Returns ------- Ws : list of array The wavelets time series. rr7r9z/time_bandwidth should be >= 2.0 for good tapersrr8r:r;r=r?)r@rArCrDrEintfloorrBrFrGrangerHfloatrJrKrIrshapemeanrLrMrNrOrP)rQrRrStime_bandwidthrUrVZn_tapsmZWmrWrXrYZt_winrZr[ZtapersZconcZWkr\r^r^r_ _make_dpssgs<          rjTcCsj|jd}tdd|D}||krRd|d|d}|rR|rJt|tnt|||d}t|}|S)Nr<css|] }|jVqdSN)rF).0wr^r^r_ sz_get_nfft..zAt least one of the wavelets (z) is longer than the signal (z6). Consider using a longer signal or shorter wavelets.r)rfmaxr# UserWarningrEr )ZwaveletsXuse_fftcheckn_timesmax_sizemsgnfftr^r^r_ _get_nffts   rxsamefsizemodedecimrrccsddlm}m}td|dddgt|}t|}|j\}} |dd|fjd} t|} |rtj | |ftj d } t |D]\} }|||| | <q|tj | | ftj d }|D]B}|r|||}t |D]\}}|r||| |d| |j d}ntj|||d }|dkrrtt|j | d}| |d }t||j|||j}|r`t||}|||||f<q|dkr|s|j dd }t||j d }|||}||||ddf<q|rt|| }||||ddf<q|VqdS) a,Compute cwt with fft based convolutions or temporal convolutions. Parameters ---------- X : array of shape (n_signals, n_times) The data. Ws : list of array Wavelets time series. fsize : int FFT length. mode : {'full', 'valid', 'same'} See numpy.convolve. decim : int | slice, default 1 To reduce memory usage, decimation factor after time-frequency decomposition. If `int`, returns tfr[..., ::decim]. If `slice`, returns tfr[..., decim]. .. note:: Decimation may create aliasing artifacts. use_fft : bool, default True Use the FFT for convolutions or not. Returns ------- out : array, shape (n_signals, n_freqs, n_time_decim) The time-frequency transform of the signals. r)fftifftr|ryZvalidfullNrdtype)r|r)Z scipy.fftr~rr _check_decimrAasarrayrfrGempty complex128rHzerosrFZconvolverbabsslicestep _centered)rqrVr{r|r}rrr~r_rtZ n_times_outn_freqsZfft_Wsir]tfrxZfft_xiiretszoffsetZ this_slicestartendr^r^r__cwt_gensJ    $       rr;complexc  sTt|}|jdkr$td|jft||||| \}}}}}t||dkrxtd|d|fdkrt ||||d} | gndkrt |||||dt d d |jd krtd t |} t }|d d d d fj\}}}d krtj }ndkr$tj }dks8dkrLt|| |f|}n@dkrxdkrxt|||| |f|}nt||| |f|}tddDt}t||tt| \}} |fdd|dd d D}t|D]\}}|||<qdkrPdkrPdkr@dkr@|d d ddd}n|dd d d}|S)a Compute time-frequency transforms. Parameters ---------- epoch_data : array of shape (n_epochs, n_channels, n_times) The epochs. freqs : array-like of floats, shape (n_freqs) The frequencies. sfreq : float | int, default 1.0 Sampling frequency of the data. method : 'multitaper' | 'morlet', default 'morlet' The time-frequency method. 'morlet' convolves a Morlet wavelet. 'multitaper' uses complex exponentials windowed with multiple DPSS tapers. n_cycles : float | array of float, default 7.0 Number of cycles in the wavelet. Fixed number or one per frequency. zero_mean : bool | None, default None None means True for method='multitaper' and False for method='morlet'. If True, make sure the wavelets have a mean of zero. time_bandwidth : float, default None If None and method=multitaper, will be set to 4.0 (3 tapers). Time x (Full) Bandwidth product. Only applies if method == 'multitaper'. The number of good tapers (low-bias) is chosen automatically based on this to equal floor(time_bandwidth - 1). use_fft : bool, default True Use the FFT for convolutions or not. decim : int | slice, default 1 To reduce memory usage, decimation factor after time-frequency decomposition. If `int`, returns tfr[..., ::decim]. If `slice`, returns tfr[..., decim]. .. note:: Decimation may create aliasing artifacts, yet decimation is done after the convolutions. output : str, default 'complex' * 'complex' : single trial complex. * 'power' : single trial power. * 'phase' : single trial phase. * 'avg_power' : average of single trial power. * 'itc' : inter-trial coherence. * 'avg_power_itc' : average of single trial power and inter-trial coherence across trials. %(n_jobs)s The number of epochs to process at the same time. The parallelization is implemented across channels. %(verbose)s Returns ------- out : array Time frequency transform of epoch_data. If output is in ['complex', 'phase', 'power'], then shape of ``out`` is ``(n_epochs, n_chans, n_freqs, n_times)``, else it is ``(n_chans, n_freqs, n_times)``. However, using multitaper method and output ``'complex'`` or ``'phase'`` results in shape of ``out`` being ``(n_epochs, n_chans, n_tapers, n_freqs, n_times)``. If output is ``'avg_power_itc'``, the real values in the ``output`` contain average power' and the imaginary values contain the ITC: ``out = avg_power + i * itc``. z@epoch_data must be of shape (n_epochs, n_chans, n_times), got %sr9zKCannot compute freq above Nyquist freq of the data (%0.1f Hz), got %0.1f Hzr`)rSrU multitaper)rSrhrUrrz`At least one of the wavelets is longer than the signal. Use a longer signal or shorter wavelets.N)powerphase avg_poweritcr avg_power_itcavg_rrrcSsg|] }t|qSr^r@)rlr]r^r^r_ sz _compute_tfr..c 3s"|]}|dVqdS)ryNr^)rlZchannelrVr}methodZmy_cwtoutputrrr^r_rnsz_compute_tfr..r)rArndimrErf_check_tfr_paramrrDror`rjrGfloat64rrsumr@rxr _time_frequency_loopZ transposerH) epoch_datarRrQrrSrUrhrrr}rn_jobsr r]rn_tapersn_epochsZn_chansrtroutZall_WsparalleltfrsZ channel_idxrr^rr_ _compute_tfrshE        rc Cst|ttjfs tdt|tj|td}|jdkrLtdt |j t|tt fsjtdt|t|}|dkr|dkn|}t|t stdt|t|}t|t tfrt|}nXt|ttjfr t |}t |t |krtd t |t |fntd t||d kr8|dk r8td n |dkrX|dkrPd nt|}t|t sttdt|t|t rtdd|}t|tstdt|td|ddddddgtd|dd g||||||fS)z;Aux. function to _compute_tfr to check the params validity.z,freqs must be an array-like, got %s instead.rrz2freqs must be of shape (n_freqs,), got %s instead.z0sfreq must be a float or an int, got %s instead.Nrz1zero_mean should be of type bool, got %s. insteadzUn_cycles must be a float or an array of length %i frequencies, got %i cycles instead.z5n_cycles must be a float or an array, got %s instead.r`z3time_bandwidth only applies to "multitaper" method.raz*use_fft must be a boolean, got %s instead.z4decim must be an integer or a slice, got %s instead.rrrrrrrr) isinstancer@rAndarrayrEtyperrerrCrfrbboolrGrr) rRrQrrUrSrhrrr}rr^r^r_rsl             rc CsPtj}|dkrtj}t|}t|}|dd|fj\} } t|d} d|ksVd|krjtj| | f|d} n<|dkr|dkrtj|| | | f|d} ntj| | | f|d} t|D]b\} }t|||d d }t ||||||d }d|krtj| | ftjd}t|D]\}}|d kr"|| j }n`|d kr8t |}nJ|dkrbt |}|||7}|d}n |dkr||t |7}qd|ksd|kr| |7} n:|dkr|dkr| | |f|7<n| ||7<q|dkr| dt |7} q|dkr| t |7} qd|ks(d|kr0| | } |dkrL|dkrL| |} | S)aAux. function to _compute_tfr. Loops time-frequency transform across wavelets and epochs. Parameters ---------- X : array, shape (n_epochs, n_times) The epochs data of a single channel. Ws : list, shape (n_tapers, n_wavelets, n_times) The wavelets. output : str * 'complex' : single trial complex. * 'power' : single trial power. * 'phase' : single trial phase. * 'avg_power' : average of single trial power. * 'itc' : inter-trial coherence. * 'avg_power_itc' : average of single trial power and inter-trial coherence across trials. use_fft : bool Use the FFT for convolutions or not. mode : {'full', 'valid', 'same'} See numpy.convolve. decim : slice The decimation slice: e.g. power[:, decim] method : str | None Used only for multitapering to create tapers dimension in the output if ``output in ['complex', 'phase']``. rNrrrrrrF)rsrz)rrrrry?r)rArrrrGrfrrHrxrconjrealZangler)rqrVrrrr|r}rrrrrtrrZ taper_idxr]rwcoefsZplfZ epoch_idxrZtfr_absr^r^r_rsh!           rcCst|||}t||||||S)aCompute time freq decomposition with continuous wavelet transform. Parameters ---------- X : array, shape (n_signals, n_times) The signals. Ws : list of array Wavelets time series. use_fft : bool Use FFT for convolutions. Defaults to True. mode : 'same' | 'valid' | 'full' Convention for convolution. 'full' is currently not implemented with ``use_fft=False``. Defaults to ``'same'``. decim : int | slice To reduce memory usage, decimation factor after time-frequency decomposition. If `int`, returns tfr[..., ::decim]. If `slice`, returns tfr[..., decim]. .. note:: Decimation may create aliasing artifacts. Defaults to 1. Returns ------- tfr : array, shape (n_signals, n_freqs, n_times) The time-frequency decompositions. See Also -------- mne.time_frequency.tfr_morlet : Compute time-frequency decomposition with Morlet wavelets. )rx _cwt_array)rqrVrrr|r}rwr^r^r_cwtCs" rc Csjt|}t||||||d}|dd|fj\}}tj|t||ftjd} t|D]\} } | | | <qT| S)Nrzr)rrrfrArrGrrH) rqrVrwr|r}rrrZ n_signalsrtrrWrr^r^r_ris rc Ksddlm} t|}t||} |j} t| | |dd\} } ~|rb|dkrRtd|r\d}q~d}n|dkrnd n|}|r~td t| || d f|||d |} |j |} | | d |j <W5QRX|r4|r| j | j }}n| }t| }t| || ||d |d} |r| t| || ||d|df} nx| }t|| rxt|j}t|j}t|j}t|j}t|j}nd}}}}}t| || |d ||||||d } | S)Nr BaseEpochsraxisrz&output must be "power" if average=Truerrrz9Inter-trial coherence is not supported with average=FalserQ)rrr}z%s-powerrz%s-itc)reventsevent_id selectiondrop_logmetadata)epochsrr _get_datainfocopy_prepare_picksrErtimesZ_unlockrrimagrG AverageTFRrr _metadatarrrr EpochsTFR)rinstrRr} return_itcpicksaverager tfr_paramsrdatarrrrrnavemetaZevsZev_idrrr^r^r__tfr_auxvsh            rrc Cs*t||||| d} td|||||| f| S)aCompute Time-Frequency Representation (TFR) using Morlet wavelets. Same computation as `~mne.time_frequency.tfr_array_morlet`, but operates on `~mne.Epochs` objects instead of :class:`NumPy arrays `. Parameters ---------- inst : Epochs | Evoked The epochs or evoked object. freqs : ndarray, shape (n_freqs,) The frequencies in Hz. n_cycles : float | ndarray, shape (n_freqs,) The number of cycles globally or for each frequency. use_fft : bool, default False The fft based convolution or not. return_itc : bool, default True Return inter-trial coherence (ITC) as well as averaged power. Must be ``False`` for evoked data. decim : int | slice, default 1 To reduce memory usage, decimation factor after time-frequency decomposition. If `int`, returns tfr[..., ::decim]. If `slice`, returns tfr[..., decim]. .. note:: Decimation may create aliasing artifacts. %(n_jobs)s picks : array-like of int | None, default None The indices of the channels to decompose. If None, all available good data channels are decomposed. zero_mean : bool, default True Make sure the wavelet has a mean of zero. .. versionadded:: 0.13.0 %(average_tfr)s output : str Can be "power" (default) or "complex". If "complex", then average must be False. .. versionadded:: 0.15.0 %(verbose)s Returns ------- power : AverageTFR | EpochsTFR The averaged or single-trial power. itc : AverageTFR | EpochsTFR The inter-trial coherence (ITC). Only returned if return_itc is True. See Also -------- mne.time_frequency.tfr_array_morlet mne.time_frequency.tfr_multitaper mne.time_frequency.tfr_array_multitaper mne.time_frequency.tfr_stockwell mne.time_frequency.tfr_array_stockwell )rSrrrrUrr`dictr) rrRrSrrrr}rrrUrrr rr^r^r_ tfr_morlets>rc Cs t|||d||d||||| d S)a5 Compute Time-Frequency Representation (TFR) using Morlet wavelets. Same computation as `~mne.time_frequency.tfr_morlet`, but operates on :class:`NumPy arrays ` instead of `~mne.Epochs` objects. Parameters ---------- epoch_data : array of shape (n_epochs, n_channels, n_times) The epochs. sfreq : float | int Sampling frequency of the data. freqs : array-like of float, shape (n_freqs,) The frequencies. n_cycles : float | array of float, default 7.0 Number of cycles in the Morlet wavelet. Fixed number or one per frequency. zero_mean : bool | False If True, make sure the wavelets have a mean of zero. default False. use_fft : bool Use the FFT for convolutions or not. default True. decim : int | slice To reduce memory usage, decimation factor after time-frequency decomposition. default 1 If `int`, returns tfr[..., ::decim]. If `slice`, returns tfr[..., decim]. .. note:: Decimation may create aliasing artifacts, yet decimation is done after the convolutions. output : str, default 'complex' * 'complex' : single trial complex. * 'power' : single trial power. * 'phase' : single trial phase. * 'avg_power' : average of single trial power. * 'itc' : inter-trial coherence. * 'avg_power_itc' : average of single trial power and inter-trial coherence across trials. %(n_jobs)s The number of epochs to process at the same time. The parallelization is implemented across channels. Default 1. %(verbose)s Returns ------- out : array Time frequency transform of epoch_data. If output is in ['complex', 'phase', 'power'], then shape of out is (n_epochs, n_chans, n_freqs, n_times), else it is (n_chans, n_freqs, n_times). If output is 'avg_power_itc', the real values code for 'avg_power' and the imaginary values code for the 'itc': out = avg_power + i * itc. See Also -------- mne.time_frequency.tfr_morlet mne.time_frequency.tfr_multitaper mne.time_frequency.tfr_array_multitaper mne.time_frequency.tfr_stockwell mne.time_frequency.tfr_array_stockwell Notes ----- .. versionadded:: 0.14.0 r`N) rrRrQrrSrUrhrrr}rrr )r) rrQrRrSrUrrr}rrr r^r^r_tfr_array_morletsDrc Cs*t|||d|d} td|||||| f| S)aQCompute Time-Frequency Representation (TFR) using DPSS tapers. Same computation as `~mne.time_frequency.tfr_array_multitaper`, but operates on `~mne.Epochs` objects instead of :class:`NumPy arrays `. Parameters ---------- inst : Epochs | Evoked The epochs or evoked object. freqs : ndarray, shape (n_freqs,) The frequencies in Hz. n_cycles : float | ndarray, shape (n_freqs,) The number of cycles globally or for each frequency. The time-window length is thus T = n_cycles / freq. time_bandwidth : float, (optional), default 4.0 (n_tapers=3) Time x (Full) Bandwidth product. Should be >= 2.0. Choose this along with n_cycles to get desired frequency resolution. The number of good tapers (least leakage from far away frequencies) is chosen automatically based on this to floor(time_bandwidth - 1). E.g., With freq = 20 Hz and n_cycles = 10, we get time = 0.5 s. If time_bandwidth = 4., then frequency smoothing is (4 / time) = 8 Hz. use_fft : bool, default True The fft based convolution or not. return_itc : bool, default True Return inter-trial coherence (ITC) as well as averaged (or single-trial) power. decim : int | slice, default 1 To reduce memory usage, decimation factor after time-frequency decomposition. If `int`, returns tfr[..., ::decim]. If `slice`, returns tfr[..., decim]. .. note:: Decimation may create aliasing artifacts. %(n_jobs)s %(picks_good_data)s %(average_tfr)s %(verbose)s Returns ------- power : AverageTFR | EpochsTFR The averaged or single-trial power. itc : AverageTFR | EpochsTFR The inter-trial coherence (ITC). Only returned if return_itc is True. See Also -------- mne.time_frequency.tfr_array_multitaper mne.time_frequency.tfr_stockwell mne.time_frequency.tfr_array_stockwell mne.time_frequency.tfr_morlet mne.time_frequency.tfr_array_morlet Notes ----- .. versionadded:: 0.9.0 T)rSrrrrUrhrr) rrRrSrhrrrr}rrrr rr^r^r_tfr_multitaperAs?rcseZdZdZddZeddZejddZeddZe dfd d Z d dZ e dddZ e dd dddZe dd dddZZS)_BaseTFRzBase TFR class.cCs d|_dSrk)baselineselfr^r^r___init__sz_BaseTFR.__init__cCs|jSrk_datarr^r^r_rsz _BaseTFR.datacCs ||_dSrkr)rrr^r^r_rscCs |jdS)zChannel names.ch_namesrrr^r^r_rsz_BaseTFR.ch_namesNTcstj|||d|dk s"|dk rEsz*_BaseTFR.to_data_frame..csg|] }|qSr^r^rlrW) rev_event_idr^r_rFsz*_BaseTFR.to_data_frame..rc3s"|]}t|tdkVqdSrNrG)rlZmdx)mindexr^r_rnIsz)_BaseTFR.to_data_frame..) default_index)rrrextendrr rr)rrrAnewaxisrfZmoveaxisZreshaper@Ztiler!rPrRrepeatrritemsrrAssertionErrorr")rrindexZ long_format time_formatr pdZvalid_index_argsZvalid_time_formatsrrrn_picksrrtrR conditionsr Zdfr^)r rr_ to_data_framesN          z_BaseTFR.to_data_frame)NNNNT)rgN)F)NNFN)__name__ __module__ __qualname____doc__rpropertyrsetterrrrrr rrr __classcell__r^r^rr_rs.   )  'rcsbeZdZdZed6fdd Zeddddddddddddddddd ddd d dgddfd d Zeddddddddddddddddd ddd dddddedddfddZedddddddddddddddd dgdddfddZ ed7ddZ ed8ddZ e d9d d!Z d"d#Zd$d%Zd&d'Zd(d)Zd*d+Zd,d-Zd.d/Zd0d1Zd2d3Zd4d5ZZS):raContainer for Time-Frequency data. Can for example store induced power at sensor level or inter-trial coherence. Parameters ---------- %(info_not_none)s data : ndarray, shape (n_channels, n_freqs, n_times) The data. times : ndarray, shape (n_times,) The time values in seconds. freqs : ndarray, shape (n_freqs,) The frequencies in Hz. nave : int The number of averaged TFRs. comment : str | None, default None Comment on the data, e.g., the experimental condition. method : str | None, default None Comment on the method used to compute the data, e.g., morlet wavelet. %(verbose)s Attributes ---------- %(info_not_none)s ch_names : list The names of the channels. nave : int Number of averaged epochs. data : ndarray, shape (n_channels, n_freqs, n_times) The data array. times : ndarray, shape (n_times,) The time values in seconds. freqs : ndarray, shape (n_freqs,) The frequencies in Hz. comment : str Comment on dataset. Can be the condition. method : str | None, default None Comment on the method used to compute the data, e.g., morlet wavelet. Nc st||_|jdkr(td|j|j\} } } | t|dkr\td| t|df| t|kr|td| t|f| t|krtd| t|f||_|t j |t d|j |_t j |t d|_||_||_||_d|_dS) Nrzdata should be 3d. Got %d.chs8Number of channels and data size don't match (%d != %d).;Number of frequencies and data size don't match (%d != %d).5Number of times and data size don't match (%d != %d).rT)rrrrrErfrGr _set_timesrArCrerr _raw_timesrRrcommentrpreload) rrrrrRrr%rr n_channelsrrtrr^r_rs2        zAverageTFR.__init__rgRdBu_rFTautoZGreys皙?cCs<|j||||||||| | | | | ||||||||||||dS)aqPlot TFRs as a two-dimensional image(s). Parameters ---------- %(picks_good_data)s baseline : None (default) or tuple, shape (2,) The time interval to apply baseline correction. If None do not apply it. If baseline is (a, b) the interval is between "a (s)" and "b (s)". If a is None the beginning of the data is used and if b is None then b is set to the end of the interval. If baseline is equal to (None, None) all the time interval is used. mode : 'mean' | 'ratio' | 'logratio' | 'percent' | 'zscore' | 'zlogratio' Perform baseline correction by - subtracting the mean of baseline values ('mean') (default) - dividing by the mean of baseline values ('ratio') - dividing by the mean of baseline values and taking the log ('logratio') - subtracting the mean of baseline values followed by dividing by the mean of baseline values ('percent') - subtracting the mean of baseline values and dividing by the standard deviation of baseline values ('zscore') - dividing by the mean of baseline values, taking the log, and dividing by the standard deviation of log baseline values ('zlogratio') tmin : None | float The first time instant to display. If None the first time point available is used. Defaults to None. tmax : None | float The last time instant to display. If None the last time point available is used. Defaults to None. fmin : None | float The first frequency to display. If None the first frequency available is used. Defaults to None. fmax : None | float The last frequency to display. If None the last frequency available is used. Defaults to None. vmin : float | None The minimum value an the color scale. If vmin is None, the data minimum value is used. Defaults to None. vmax : float | None The maximum value an the color scale. If vmax is None, the data maximum value is used. Defaults to None. cmap : matplotlib colormap | 'interactive' | (colormap, bool) The colormap to use. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If 'interactive', translates to ('RdBu_r', True). Defaults to 'RdBu_r'. .. warning:: Interactive mode works smoothly only for a small amount of images. dB : bool If True, 10*log10 is applied to the data to get dB. Defaults to False. colorbar : bool If true, colorbar will be added to the plot. Defaults to True. show : bool Call pyplot.show() at the end. Defaults to True. title : str | 'auto' | None String for ``title``. Defaults to None (blank/no title). If 'auto', and ``combine`` is None, the title for each figure will be the channel name. If 'auto' and ``combine`` is not None, ``title`` states how many channels were combined into that figure and the method that was used for ``combine``. If str, that String will be the title for each figure. axes : instance of Axes | list | None The axes to plot to. If list, the list must be a list of Axes of the same length as ``picks``. If instance of Axes, there must be only one channel plotted. If ``combine`` is not None, ``axes`` must either be an instance of Axes, or a list of length 1. layout : Layout | None Layout instance specifying sensor positions. Used for interactive plotting of topographies on rectangle selection. If possible, the correct layout is inferred from the data. yscale : 'auto' (default) | 'linear' | 'log' The scale of y (frequency) axis. 'linear' gives linear y axis, 'log' leads to log-spaced y axis and 'auto' detects if frequencies are log-spaced and only then sets the y axis to 'log'. .. versionadded:: 0.14.0 mask : ndarray | None An array of booleans of the same shape as the data. Entries of the data that correspond to False in the mask are plotted transparently. Useful for, e.g., masking for statistical significance. .. versionadded:: 0.16.0 mask_style : None | 'both' | 'contour' | 'mask' If ``mask`` is not None: if ``'contour'``, a contour line is drawn around the masked areas (``True`` in ``mask``). If ``'mask'``, entries not ``True`` in ``mask`` are shown transparently. If ``'both'``, both a contour and transparency are used. If ``None``, defaults to ``'both'`` if ``mask`` is not None, and is ignored otherwise. .. versionadded:: 0.17 mask_cmap : matplotlib colormap | (colormap, bool) | 'interactive' The colormap chosen for masked parts of the image (see below), if ``mask`` is not ``None``. If None, ``cmap`` is reused. Defaults to ``'Greys'``. Not interactive. Otherwise, as ``cmap``. .. versionadded:: 0.17 mask_alpha : float A float between 0 and 1. If ``mask`` is not None, this sets the alpha level (degree of transparency) for the masked-out segments. I.e., if 0, masked-out segments are not visible at all. Defaults to 0.1. .. versionadded:: 0.16.0 combine : 'mean' | 'rms' | None Type of aggregation to perform across selected channels. If None, plot one figure per selected channel. exclude : list of str | 'bads' Channels names to exclude from being shown. If 'bads', the bad channels are excluded. Defaults to an empty list. %(cnorm)s .. versionadded:: 0.24 %(verbose)s Returns ------- figs : list of instances of matplotlib.figure.Figure A list of figures containing the time-frequency power. )rrr|rrrrvminvmaxcmapdBcolorbarshowtitleaxeslayoutyscalemask mask_style mask_cmap mask_alphacombinercnormr )_plot)rrrr|rrrrr+r,r-r.r/r0r1r2r3r4r5r6r7r8r9rr:r r^r^r_plots2 zAverageTFR.plotg?c)s|ddlmddlm}t|||||||| | |||| }~|j} |dkrRt|jnd}!|dkrn| jddd} n2|d krt | djddd} n|dk rt d |j dd g\}}| dkrt | } |dkrt |  }t| } t|tst|t jrd d |D}"nXt|jr2dd |fD}"n8|dkrbfdd t|!D}#dd |#D}"nt dt|"|!krtdt|!D]}$|"|$d}%|"|$d}&t|j| |dd|Dd}'||&d|||| |'d| |$|$d|jdd| | ||||||d|dkrTt|jddks*|dkr:|jd|$}(ntd||jdd|d}(n|}(|%|(qt| dd |"DS)zfPlot TFRs as a two-dimensional image(s). See self.plot() for parameters description. rNr) _imshow_tfrrrgT)rkeepdimsrmsz"combine must be None, mean or rms.r<cSsg|]}||fqSr^Z get_figurerlaxr^r^r_r^sz$AverageTFR._plot..cSsg|]}||fqSr^r@rAr^r^r_r`scsg|] }qSr^)Zfigure)rlrpltr^r_rbscSsg|]}||dfqS)o) add_subplot)rlfigr^r^r_rcsz1axes must be None, plt.Axes, or list of plt.Axes.z.There must be an axes for each picked channel.cSsi|]\}}|dkr||qS)>r,r-r2r+r^rr^r^r_rpsz$AverageTFR._plot..)r-source_plot_joint topomap_argsTime (s)Frequency (Hz)) Zylimrrx_labely_labelr/r-r4r5r6r7r8r:r)r)rch_typecSsg|] \}}|qSr^r^)rlrGrBr^r^r_rs)matplotlib.pyplotpyplotviz.topor=_preproc_tfr_instancerrGrrgrArLrErrror1rr@rZAxesrd RuntimeErrorr _onselectrrRrr5suptitler0))rrrr|rrrrr+r,r-r.r/r0r1r2r3r4r5r6r7r8r9rrrHrIrNr:r r=rrrZ figs_and_axesfigsidxrGrBonselect_callbacksubtitler^rCr_r;/s       zAverageTFR._plotcCsddlm}m}m}m}ddlm}tdd|||fD}t||||d~t j dd }t |d kr t d t }|D]fd d tj dD}t|ddd}t t |j dd d krtd||j|d||||||| | | | | d|||d||dq~|S|} t|}t |}!|dkr6t}dd|D}"|dd|"d<|dd|"d<| |"d<t|!\}#}$t| } |dkrt}jfd||||||| | | | dd|||ddd|"| d|djj}}jj}}|D]v\}%}&||%kr.|ksBndt|%d}'n0||&krZ|ksndt|&d}'nqt d|'dqggggf\}(})}*}+t!"d d |D},|,dddf#}-t$|,|-D]\}.\}%}&||%|&f}/|/d!\}0}1|0dkrjt!%t!&j|%}%|1dkr@jt!%t!&j|&}&|0dkrb|1dkrbd"|%|&f}2nd#|%|0|&|1f}2|%|0}|%|0}|&|1}|&|1}j'}3|d$}4| d%krt(j dd&}|j |ddd|4d'}5|pd(}6t)|3|| g|6d)\}3}7~~6n|j d|4\}5}7~4|*|5t*|3jj||||||| | dj d* \}3}8}9}7}7|+t!&|3|(|2|)|3jt!&jt!+|8g%}:jt!&jt!+|9g%};|:|;f|,|.<qt|+}<|d+|< |"d+<} |d,|<|"d,<} || | |"d\}=}>|>|"d<t,|#|(|)|*D]>\}?}}3}5|?-|||3j.d-d.|5f| d|?dd/|"q&| rdd0l/m0}@|j1|?j2d|$d1}A|=dkr|@j3d2d3}=|=|A_4|A5|j6d4d5d6|dk rd7nd8d9fd:d t,|,|#D}Bj78|Bt9|S);aPlot TFRs as a two-dimensional image with topomaps. Parameters ---------- timefreqs : None | list of tuple | dict of tuple The time-frequency point(s) for which topomaps will be plotted. See Notes. %(picks_good_data)s baseline : None (default) or tuple of length 2 The time interval to apply baseline correction. If None do not apply it. If baseline is (a, b) the interval is between "a (s)" and "b (s)". If a is None, the beginning of the data is used. If b is None, then b is set to the end of the interval. If baseline is equal to (None, None), the entire time interval is used. mode : None | str If str, must be one of 'ratio', 'zscore', 'mean', 'percent', 'logratio' and 'zlogratio'. Do baseline correction with ratio (power is divided by mean power during baseline) or zscore (power is divided by standard deviation of power during baseline after subtracting the mean, power = [power - mean(power_baseline)] / std(power_baseline)), mean simply subtracts the mean power, percent is the same as applying ratio then mean, logratio is the same as mean but then rendered in log-scale, zlogratio is the same as zscore but data is rendered in log-scale first. If None no baseline correction is applied. tmin : None | float The first time instant to display. If None the first time point available is used. tmax : None | float The last time instant to display. If None the last time point available is used. fmin : None | float The first frequency to display. If None the first frequency available is used. fmax : None | float The last frequency to display. If None the last frequency available is used. vmin : float | None The minimum value of the color scale for the image (for topomaps, see ``topomap_args``). If vmin is None, the data absolute minimum value is used. vmax : float | None The maximum value of the color scale for the image (for topomaps, see ``topomap_args``). If vmax is None, the data absolute maximum value is used. cmap : matplotlib colormap The colormap to use. dB : bool If True, 10*log10 is applied to the data to get dB. colorbar : bool If true, colorbar will be added to the plot (relating to the topomaps). For user defined axes, the colorbar cannot be drawn. Defaults to True. show : bool Call pyplot.show() at the end. title : str | None String for title. Defaults to None (blank/no title). yscale : 'auto' (default) | 'linear' | 'log' The scale of y (frequency) axis. 'linear' gives linear y axis, 'log' leads to log-spaced y axis and 'auto' detects if frequencies are log-spaced and only then sets the y axis to 'log'. combine : 'mean' | 'rms' Type of aggregation to perform across selected channels. exclude : list of str | 'bads' Channels names to exclude from being shown. If 'bads', the bad channels are excluded. Defaults to an empty list, i.e., ``[]``. topomap_args : None | dict A dict of ``kwargs`` that are forwarded to :func:`mne.viz.plot_topomap` to style the topomaps. ``axes`` and ``show`` are ignored. If ``times`` is not in this dict, automatic peak detection is used. Beyond that, if ``None``, no customizable arguments will be passed. Defaults to ``None``. image_args : None | dict A dict of ``kwargs`` that are forwarded to :meth:`AverageTFR.plot` to style the image. ``axes`` and ``show`` are ignored. Beyond that, if ``None``, no customizable arguments will be passed. Defaults to ``None``. %(verbose)s Returns ------- fig : matplotlib.figure.Figure The figure containing the topography. Notes ----- ``timefreqs`` has three different modes: tuples, dicts, and auto. For (list of) tuple(s) mode, each tuple defines a pair (time, frequency) in s and Hz on the TFR plot. For example, to look at 10 Hz activity 1 second into the epoch and 3 Hz activity 300 msec into the epoch, :: timefreqs=((1, 10), (.3, 3)) If provided as a dictionary, (time, frequency) tuples are keys and (time_window, frequency_window) tuples are the values - indicating the width of the windows (centered on the time and frequency indicated by the key) to be averaged over. For example, :: timefreqs={(1, 10): (0.1, 2)} would translate into a window that spans 0.95 to 1.05 seconds, as well as 9 to 11 Hz. If None, a single topomap will be plotted at the absolute peak across the time-frequency representation. .. versionadded:: 0.16.0 r)_set_contour_locator plot_topomap_get_pos_outlines_find_topomap_coordsrNcss|]}|dk VqdSrkr^)rlvarr^r^r_rn sz(AverageTFR.plot_joint..rT)uniquerz?Multiple channel types selected, returning one figure per type.cs g|]}tj|kr|qSr^)r*r)rlrW)r this_typer^r_rsz)AverageTFR.plot_joint..ZnchanzsPossibly infinite loop due to channel selection problem. This should never happen! Please check your channel types.F) timefreqsrrr|rrrrr+r,r-r.r/r0r1r4r9rrIr cSsi|]\}}|dkr||qS))r2r0r/r^rr^r^r_r0sz)AverageTFR.plot_joint..outlinesZskirtcontoursrN)rrr|rrrrr+r,r-r.r/r0r1r2r4r9rrrHrIrNz time point (z s)z frequency (z Hz)z Requested z< exceeds the rangeof the data. Choose different `timefreqs`.cSsg|]}t|qSr^)rArC)rlkeysr^r^r_rdsr9z(%.2f s, %.1f Hz)u!(%.1f ± %.1f s, %.1f ± %.1f Hz)spheregrad)topomap_coords)rrfr?rrQr+r,)r<r>r)r-r2r0)ticker)Zcax)ZnbinsgQ?g?gQ?r;g333333?)leftrightbottomtopc s(g|] \\}}}t|||ddqS)Z transData)yZy_source_transform)r2)rlZtime_Zfreq_Zmap_ax_)rGtf_axr^r_rs ): viz.topomaprZr[r\r]rOrPrDr+r,rrGr r@rdrSrP plot_jointpop_get_timefreqsrrgetr3r1r;rrominrRrestrrErArCZargsortrHZargminrrr'r& _preproc_tfrZmedianzip set_titlergZ matplotlibrir/ZimagesZ MaxNLocatorlocatorZ update_ticksZsubplots_adjustlinesr r0)Crrarrr|rrrrr+r,r-r.r/r0r1r4r9rrIZ image_argsr rZr[r\r]rDrZch_typesrVZ type_picksZtf_rNZ n_timefreqsZtopomap_args_passZmap_axZcbar_axrrZ error_valuetitlesZall_dataZall_posZvlimsZtimefreqs_arrayorderravgZtime_half_rangeZfreq_half_rangeZ sub_map_titlerrfposrrrrRZnew_tnew_fZmax_limr{rcrBriZcbarr|r^)rGrprr`r_rrsnv                     ""        zAverageTFR.plot_jointc sddlm} m} m} t|j|jdksz&AverageTFR._onselect..)keycs t|Srkrr)rr^r_rrcs t|Srkrr)rr^r_rrcs t|Srkrr)rr^r_rrzFThe selected area is too small. Select a larger time-frequency window.ZeegmagrgF)rhZ raise_errorrz*{:.2f} s - {:.2f} s, {:.2f} Hz - {:.2f} Hzg{Gz?)rorErQr<)r+r,r-r2r0ZAU)r1padr) rNrrrrrr|r-r1r+r,r2)rqrr[rrrroroundrvZxdataroZydatarrRr rr@rPrGr'r/rUformatrFrxrrgrAr0rH)rZeclickZereleaserr|r-rHrIr rr[rtypesrGrBrr,ZimrrWrNr^)rrrrr_rTs(            zAverageTFR._onselect= ףp=?nonerWrmc$Csddlm}m}m}ddlm}|j}|j}|j }|j }t |||dd\}}~t ||||||||||| | |d \}}}}} | dkrddl m}||j } t|j||d } t||||| d f| d }!t|||| | d }"||||"|!| ||| | || |d d||d d d}#||#|t||#S)arPlot TFRs in a topography with images. Parameters ---------- %(picks_good_data)s baseline : None (default) or tuple of length 2 The time interval to apply baseline correction. If None do not apply it. If baseline is (a, b) the interval is between "a (s)" and "b (s)". If a is None the beginning of the data is used and if b is None then b is set to the end of the interval. If baseline is equal to (None, None) all the time interval is used. mode : 'mean' | 'ratio' | 'logratio' | 'percent' | 'zscore' | 'zlogratio' Perform baseline correction by - subtracting the mean of baseline values ('mean') - dividing by the mean of baseline values ('ratio') - dividing by the mean of baseline values and taking the log ('logratio') - subtracting the mean of baseline values followed by dividing by the mean of baseline values ('percent') - subtracting the mean of baseline values and dividing by the standard deviation of baseline values ('zscore') - dividing by the mean of baseline values, taking the log, and dividing by the standard deviation of log baseline values ('zlogratio') tmin : None | float The first time instant to display. If None the first time point available is used. tmax : None | float The last time instant to display. If None the last time point available is used. fmin : None | float The first frequency to display. If None the first frequency available is used. fmax : None | float The last frequency to display. If None the last frequency available is used. vmin : float | None The minimum value of the color scale. If vmin is None, the data minimum value is used. vmax : float | None The maximum value of the color scale. If vmax is None, the data maximum value is used. layout : Layout | None Layout instance specifying sensor positions. If possible, the correct layout is inferred from the data. cmap : matplotlib colormap | str The colormap to use. Defaults to 'RdBu_r'. title : str Title of the figure. dB : bool If True, 10*log10 is applied to the data to get dB. colorbar : bool If true, colorbar will be added to the plot. layout_scale : float Scaling factor for adjusting the relative size of the layout on the canvas. show : bool Call pyplot.show() at the end. border : str Matplotlib borders style to be used for each sensor plot. fig_facecolor : color The figure face color. Defaults to black. fig_background : None | array A background image for the figure. This must be a valid input to `matplotlib.pyplot.imshow`. Defaults to None. font_color : color The color of tick labels in the colorbar. Defaults to white. yscale : 'auto' (default) | 'linear' | 'log' The scale of y (frequency) axis. 'linear' gives linear y axis, 'log' leads to log-spaced y axis and 'auto' detects if frequencies are log-spaced and only then sets the y axis to 'log'. %(verbose)s Returns ------- fig : matplotlib.figure.Figure The figure containing the topography. r)r= _plot_topo_imshow_tfr_unified)add_background_imagerrrQN) find_layout)rr|T)rrr4r-onselect)rrr-rrJrK)rrZ show_funcZ click_funcr3r/r+r,r- layout_scaler1borderrLrM fig_facecolor font_colorZunifiedZimg)rQr=rrvizrrrrRrrrrxZmnerrrTr0)$rrrr|rrrrr+r,r3r-r1r.r/rr0rrZfig_backgroundrr4r r=rrrrrRrrrrXZ click_funZimshowrGr^r^r_ plot_toposdY        zAverageTFR.plot_topo@r%1.1eheadrdcCsDddlm}||||||||||| | | | | ||||||||||dS)aPlot topographic maps of time-frequency intervals of TFR data. Parameters ---------- tmin : None | float The first time instant to display. If None the first time point available is used. tmax : None | float The last time instant to display. If None the last time point available is used. fmin : None | float The first frequency to display. If None the first frequency available is used. fmax : None | float The last frequency to display. If None the last frequency available is used. ch_type : 'mag' | 'grad' | 'planar1' | 'planar2' | 'eeg' | None The channel type to plot. For 'grad', the gradiometers are collected in pairs and the RMS for each pair is plotted. If None, then first available channel type from order given above is used. Defaults to None. baseline : tuple or list of length 2 The time interval to apply rescaling / baseline correction. If None do not apply it. If baseline is (a, b) the interval is between "a (s)" and "b (s)". If a is None the beginning of the data is used and if b is None then b is set to the end of the interval. If baseline is equal to (None, None) all the time interval is used. mode : 'mean' | 'ratio' | 'logratio' | 'percent' | 'zscore' | 'zlogratio' Perform baseline correction by - subtracting the mean of baseline values ('mean') - dividing by the mean of baseline values ('ratio') - dividing by the mean of baseline values and taking the log ('logratio') - subtracting the mean of baseline values followed by dividing by the mean of baseline values ('percent') - subtracting the mean of baseline values and dividing by the standard deviation of baseline values ('zscore') - dividing by the mean of baseline values, taking the log, and dividing by the standard deviation of log baseline values ('zlogratio') vmin : float | callable | None The value specifying the lower bound of the color range. If None, and vmax is None, -vmax is used. Else np.min(data) or in case data contains only positive values 0. If callable, the output equals vmin(data). Defaults to None. vmax : float | callable | None The value specifying the upper bound of the color range. If None, the maximum value is used. If callable, the output equals vmax(data). Defaults to None. cmap : matplotlib colormap | (colormap, bool) | 'interactive' | None Colormap to use. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range. Hitting space bar resets the range. Up and down arrows can be used to change the colormap. If None (default), 'Reds' is used for all positive data, otherwise defaults to 'RdBu_r'. If 'interactive', translates to (None, True). sensors : bool | str Add markers for sensor locations to the plot. Accepts matplotlib plot format string (e.g., 'r+' for red plusses). If True, a circle will be used (via .add_artist). Defaults to True. colorbar : bool Plot a colorbar. unit : dict | str | None The unit of the channel type used for colorbar label. If scale is None the unit is automatically determined. res : int The resolution of the topomap image (n pixels along each side). size : float Side length per topomap in inches. cbar_fmt : str String format for colorbar values. show_names : bool | callable If True, show channel names on top of the map. If a callable is passed, channel names will be formatted using the callable; e.g., to delete the prefix 'MEG ' from all channel names, pass the function lambda x: x.replace('MEG ', ''). If ``mask`` is not None, only significant sensors will be shown. title : str | None Title. If None (default), no title is displayed. axes : instance of Axes | None The axes to plot to. If None the axes is defined automatically. show : bool Call pyplot.show() at the end. %(outlines_topomap)s contours : int | array of float The number of contour lines to draw. If 0, no contours will be drawn. When an integer, matplotlib ticker locator is used to find suitable values for the contour thresholds (may sometimes be inaccurate, use array for accuracy). If an array, the values represent the levels for the contours. If colorbar=True, the ticks in colorbar correspond to the contour levels. Defaults to 6. %(sphere_topomap_auto)s Returns ------- fig : matplotlib.figure.Figure The figure containing the topography. r)r)rrrrrNrr|r+r,r-sensorsr/unitresrFcbar_fmt show_namesr1r2r0rbrcrf)rr)rrrrrrNrr|r+r,r-rr/rrrFrrr1r2r0rbrcrfrr^r^r_r[xs.p  zAverageTFR.plot_topomapcCs0t|j|jkstt|j|jks,tdS)z)rrRrrrfr_sizersr^r^r___repr__$s zAverageTFR.__repr__)NNN)NNNFNN)NNrgNNNNNNNr(NFTrTrrWNrmr)N)NNNNNNrgNNNTTNrrrFNNTrrdN)rrrrr rr<rr;rrrTrrr[rrrrrrrrrrrr^r^rr_rTs)  W ; 8 } zrc sLeZdZdZedfdd ZeddZddZd d Z dddZ Z S)ra Container for Time-Frequency data on epochs. Can for example store induced power at sensor level. Parameters ---------- %(info_not_none)s data : ndarray, shape (n_epochs, n_channels, n_freqs, n_times) The data. times : ndarray, shape (n_times,) The time values in seconds. freqs : ndarray, shape (n_freqs,) The frequencies in Hz. comment : str | None, default None Comment on the data, e.g., the experimental condition. method : str | None, default None Comment on the method used to compute the data, e.g., morlet wavelet. events : ndarray, shape (n_events, 3) | None The events as stored in the Epochs class. If None (default), all event values are set to 1 and event time-samples are set to range(n_epochs). event_id : dict | None Example: dict(auditory=1, visual=3). They keys can be used to access associated events. If None, all events will be used and a dict is created with string integer names corresponding to the event id integers. selection : iterable | None Iterable of indices of selected epochs. If ``None``, will be automatically generated, corresponding to all non-zero events. .. versionadded:: 0.23 drop_log : tuple | None Tuple of tuple of strings indicating which epochs have been marked to be ignored. .. versionadded:: 0.23 metadata : instance of pandas.DataFrame | None A :class:`pandas.DataFrame` containing pertinent information for each trial. See :class:`mne.Epochs` for further details. %(verbose)s Attributes ---------- %(info_not_none)s ch_names : list The names of the channels. data : ndarray, shape (n_epochs, n_channels, n_freqs, n_times) The data array. times : ndarray, shape (n_times,) The time values in seconds. freqs : ndarray, shape (n_freqs,) The frequencies in Hz. comment : string Comment on dataset. Can be the condition. method : str | None, default None Comment on the method used to compute the data, e.g., morlet wavelet. events : ndarray, shape (n_events, 3) | None Array containing sample information as event_id event_id : dict | None Names of conditions correspond to event_ids selection : array List of indices of selected events (not dropped or ignored etc.). For example, if the original event array had 4 events and the second event has been dropped, this attribute would be np.array([0, 2, 3]). drop_log : tuple of tuple A tuple of the same length as the event array used to initialize the ``EpochsTFR`` object. If the i-th original event is still part of the selection, drop_log[i] will be an empty tuple; otherwise it will be a tuple of the reasons the event is not longer in the selection, e.g.: - ``'IGNORED'`` If it isn't part of the current subset defined by the user - ``'NO_DATA'`` or ``'TOO_SHORT'`` If epoch didn't contain enough data names of channels that exceeded the amplitude threshold - ``'EQUALIZED_COUNTS'`` See :meth:`~mne.Epochs.equalize_event_counts` - ``'USER'`` For user-defined reasons (see :meth:`~mne.Epochs.drop`). metadata : pandas.DataFrame, shape (n_events, n_cols) | None DataFrame containing pertinent information for each trial Notes ----- .. versionadded:: 0.13.0 Nc st||_|jdkr(td|j|j\} }}}|t|dkr^td|t|df|t|kr~td|t|f|t|krtd|t|f|dkrt|} t| }dkrt|} t | | dkr t t|t d}t fdd t |D} n| } tt|ks&t t| t|ks.css|]}t|dkVqdSr r )rldlr^r^r_rnsrT)!rrrrrErfrGrrArJrotuplerdrrrrr#rCrerrr$Z_decimrRrrrrr%rr&r)rrrrrRr%rrrrrrr rr'rrtZn_epochs_prerejectionrrr_rs`             zEpochsTFR.__init__cCstSrkrrr^r^r__detrend_picksszEpochsTFR._detrend_pickscCsxd|jd|jdf}|d|jd|jdf7}|d|jjd7}|d|jjd7}|dt|jf7}d |S) Nrrr<rz , epochs : %drrrz)rrRrrfrrrr^r^r_rs zEpochsTFR.__repr__cCs|}t|j|_|S)zTake the absolute value.)rrArr)rrr^r^r___abs__szEpochsTFR.__abs__rgrFc Csjtd|dtdd|jjdd|}t||d}||j}|jj\}}} } |j|j} } |dkrxtj |jdd } d} n|d krtj |jdd } d} |d kr|j jdd } n||| | f} tj ||d }|j| krt d|jd| d|d krt |j|| | |jjd|j|jdS|rLt|j|| | |j|j|j|j|jd S||_|| | |_|Sd S)aAverage the data across epochs. Parameters ---------- method : str | callable How to combine the data. If "mean"/"median", the mean/median are returned. Otherwise, must be a callable which, when passed an array of shape (n_epochs, n_channels, n_freqs, n_time) returns an array of shape (n_channels, n_freqs, n_time). Note that due to file type limitations, the kind for all these will be "average". dim : 'epochs' | 'freqs' | 'times' The dimension along which to combine the data. copy : bool Whether to return a copy of the modified instance, or modify in place. Ignored when ``dim='epochs'`` because a new instance must be returned. Returns ------- ave : instance of AverageTFR | EpochsTFR The averaged data. Notes ----- Passing in ``np.median`` is considered unsafe when there is complex data because NumPy doesn't compute the marginal median. Numpy currently sorts the complex values by real part and return whatever value is computed. Use with caution. We use the marginal median in the complex case (i.e. the median of each component separately) if one passes in ``median``. See a discussion in scipy: https://github.com/scipy/scipy/pull/12676#issuecomment-783370228 dim)rrRrrrr)r|rrRT)r>rrNrz5You passed a function that resulted in data of shape z, but it should be .)rrrrRrrr%) rrrrRrr%rrr)rrrrrrfrRrrArgrZ expand_dimsrSrrrrr%rrrrr#)rrrrrfuncrrr'rrtrRrZexpected_shaper^r^r_rsT#          zEpochsTFR.average)NNNNNNNN)rgrF) rrrrr rrrrrrrr^r^rr_r-sV3 rrcCst|d}t|trh|dkr&td|dkrRtdd|Dt}||}ndt|gt|}t|t}|j dks|j t|krtd |j }|dd D]R}|j |kst td ||ft t|j|jd kst td ||fqtt|jdjdd|dd D}||jd<tddt||D|_t tdtddt||Dd|_|S)aMerge AverageTFR data by weighted addition. Create a new AverageTFR instance, using a combination of the supplied instances as its data. By default, the mean (weighted by trials) is used. Subtraction can be performed by passing negative weights (e.g., [1, -1]). Data must have the same channels and the same time instants. Parameters ---------- all_tfr : list of AverageTFR The tfr datasets. weights : list of float | str The weights to apply to the data of each AverageTFR instance. Can also be ``'nave'`` to weight according to tfr.nave, or ``'equal'`` to use equal weighting (each weighted as ``1/N``). Returns ------- tfr : AverageTFR The new TFR data. Notes ----- .. versionadded:: 0.11.0 r)requalz5Weights must be a list of float, or "nave" or "equal"rcSsg|] }|jqSr^r)rler^r^r_r; szcombine_tfr..r;rz(Weights must be the same size as all_tfrNz*%s and %s do not contain the same channelsgHz>z/%s and %s do not contain the same time instantsbadscss|]}|jdVqdS)rNr)rlt_r^r^r_rnM szcombine_tfr..css|]\}}||jVqdSrkr)rlrmrr^r^r_rnR scss |]\}}|d|jVqdS)rNr)rlrmrr^r^r_rnS s)rrrwrErArCrerrGrrFrrrorrr@setrunionryrrbr)Zall_tfrweightsrrrrr^r^r_ combine_tfr s@      rcCsbddlm}ddlm}t|||fs.tdt||rB|}n|rNtd|jt j  }|S)z>Get data from Epochs or Evoked instance as epochs x ch x time.rr)Evokedzinst must be Epochs or Evokedz(return_itc must be False for evoked data) rrZevokedrr TypeErrorget_datarErrArr)rrrrrr^r^r_r[ s    rcCsDt||dd}t||}tdg|j}|||<|t|}||fS)zPrepare the picks.rrN)r)r(rrr)rrrrslr^r^r_rj s   rcsRt|}t|j}||d|fddttD}|t|S)zAux Function to center data.rcsg|]}t||qSr^)rrZendindZstartindr^r_r{ sz_centered..)rArrCrfrdrGr)ZarrZnewsizecurrsizeZmyslicer^rr_rt s    rcCs0| dkr|dk } t||||| d}t|r@t||j}d\}}tt|||| dd}|dk rr|d}|dk r|dd}|||}d\}}tt|||| dd}|dk r|d}|dk r|dd}|||}|dd||||f}| rdt|}t || | \} } |||| | fS) z(Aux Function to prepare tfr computation.Nr)NN)rQrr<r) rrAZ iscomplexobjrLrrrrlog10r4)rrrRrrrrr|rr+r,r.rQrZitminZitmaxrWZifminZifmaxr^r^r_rx s0     rxcCsHt|dtfdt|ts*tddt|}|jdkrDt|j|jd}|S)z*Aux function checking the decim parameter.zint-liker}Nr)rrrrbrrstop)r}r^r^r_r s   rrc Cspt\}}g}t|ttfs"|g}t|D].\}}|jdkr@|n|j} |t|| dq*||||ddddS)aWrite a TFR dataset to hdf5. Parameters ---------- fname : str The file name, which should end with ``-tfr.h5``. tfr : AverageTFR | list of AverageTFR | EpochsTFR The TFR dataset, or list of TFR datasets, to save in one file. Note. If .comment is not None, a name will be generated on the fly, based on the order in which the TFR objects are passed. %(overwrite)s %(verbose)s See Also -------- read_tfrs Notes ----- .. versionadded:: 0.9.0 N)r mnepythonreplace)rr1slash)r$rr@rrHr%rP_prepare_write_tfr) rrrr rZ write_hdf5rrZtfr_r%r^r^r_r s  rcCs~t|j|j|j|j|j|jd}t|dr6|j|d<n@t|drv|j |d<|j |d<|j |d<|j |d<t |j|d<||fS)z Aux function.)rrRrrr%rrrrrrr)rrrRrrr%rhasattrrrrrrrr)rr attributesr^r^r_r s       rc st|ddt\}}td|||ddd}|D]<\}}t|d|d<|dd|kr6t|d|d<q6d |k}|d k r|std t|}||krd d |D} t d |d | t f||} n*|rt nt fdd tt|dD} | S)a4Read TFR datasets from hdf5 file. Parameters ---------- fname : str The file name, which should end with -tfr.h5 . condition : int or str | list of int or str | None The condition to load. If None, all conditions will be returned. Defaults to None. Returns ------- tfr : AverageTFR | list of AverageTFR | EpochsTFR Depending on ``condition`` either the TFR object or a list of multiple TFR objects. See Also -------- write_tfrs Notes ----- .. versionadded:: 0.9.0 r)z-tfr.h5z_tfr.h5zReading %s ...rr)r1rrrrNz/condition not supported when reading EpochsTFR.cSsg|] }d|qS)z%sr^rr^r^r_r szread_tfrs..zBCannot find condition ("{}") in this file. The file contains "{}""z or csg|]}f|qSr^r^)rldrr^r_r sr)rr$r rr-Z_check_consistencyrNotImplementedErrorrrErjoinrrr@ry) rrZ read_hdf5rZtfr_datarWrZ is_averageZtfr_dictrerr^rr_ read_tfrs s0     rcsd}ttrZD]>\}}||fD],}t|dksHtdd|Dr&t||q&qnVdk rtdsvt|tdkrtddDrtgn>D]8}t|drt|dkrtdd|Drqt||qnd d l m }t d j j dd f}|j |dd }|d jd krXtj j j \} } } j| j| fgnXfddt|d |dD} t| } j|d| }j|d | }||fgfddDS)z1Find and/or setup timefreqs for `tfr.plot_joint`.z{Supplied `timefreqs` are somehow malformed. Please supply None, a list of tuple pairs, or a dict of such tuple pairs, not: rcss|]}t| VqdSrkrrlnr^r^r_rn$ sz!_get_timefreqs..N__len__css|]}t|VqdSrkr)rlrr^r^r_rn) scss|]}t|VqdSrkrrr^r^r_rn. sr) argrelmaxr)r~rcs g|]\}}jd||fqSrr)rlrXrZrr^r_r= sz"_get_timefreqs..cs8i|]0}t|ttr&t|n tddgqSr)rrrrArrCr)rar^r_rE sz"_get_timefreqs..)rrrrGrDrErrrZ scipy.signalrrorrfrFrAZ unravel_indexZargmaxrrRry)rraZtimefreq_error_msgrWritemrr~Z peaks_idxrZp_tZp_fZpeaksZ peakmax_idxZ peakmax_timeZ peakmax_freqr^)rrar_rt sF          rtc s| r n|dkrdn| } tj|dd}fdd|D} | | dkrlfddjdD} | dk r~| tjjj||||| | |||jddd \}}}}} ||_|_S) z7Baseline and truncate (times and freqs) a TFR instance.Nrrcsg|]}jd|qSrr)rlpickrr^r_rS sz)_preproc_tfr_instance..csg|]}|jdkr|qSrr)rlchrr^r_rW srQFr) rr)rZ pick_channelsZ drop_channelsrxrrrRr#)rrrrrrr+r,r.r|rrrZ pick_namesrrrRrr^rr_rRL s:   rR)r6NF)r6raF)TT) r;r`r6NNTrrNN)N)Tryr)N) FTrNNTTrN)r6FTrrNN)raTTrNNTN)r)N)F)N)T)[rrr functoolsrnumpyrArrrrr filterr rr utilsr r rrrrrrrrrrrrrrrrrrr r!r"r#r$Zchannels.channelsr%Zchannels.layoutr&r'Zio.pickr(r)r*r+r,Z io.meas_infor-r.Z viz.utilsr/r0r1r2r3r4r5r`rjrxrrrrrrrrrrrrrrrrrrxrrrrrtrRr^r^r^r_s     l $ ? H R A d & < C J FM_n @  (! 52