U f{j @sddlmZddlZddlmZmZmZddlm Z m Z m Z ddl m Z mZddlmZmZmZddlmZmZmZdd lmZmZmZmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*dd l+m,Z,m-Z-m.Z.m/Z/m0Z0dd l1m2Z2m3Z3dd l4m5Z5dd l6m7Z7ddl8m9Z9ddl:m;Z;ddlm?Z?m@Z@mAZAddlBmCZCmDZDmEZEmFZFmGZGmHZHddlImJZJddlKmLZLmMZMmNZNmOZOmPZPmQZQmRZRmSZSmTZTddlUmVZVmWZWddlXmYZYe7jZe7j[e7j\e7j]e7j^e7j_e7j`e7jae7jbe7jce7jdd ZeddeefDZge GdddeJeCe e e ee*e Zhe GdddehZid9dd Zjd!d"Zkd#d$Zld%d&Zmd'd(Zned:d+d,Zod;d-d.Zped/ddd0d1d2ZqddeepcopyN)rescale _log_rescale_check_baseline)UpdateChannelsMixinSetChannelsMixinInterpolationMixin)_merge_ch_data_pair_grad_sensors)_INTERPOLATION_DEFAULT_EXTRAPOLATE_DEFAULT_BORDER_DEFAULT)detrend FilterMixin _check_fun) check_fnameloggerverbosewarn sizeof_fmt SizeMixincopy_function_doc_to_method_doc_validate_typefill_doc _check_option_build_data_frame_check_pandas_installed_check_pandas_index_arguments_convert_times_scale_dataframe_data_check_time_format_check_preload _check_fname TimeMixin) plot_evokedplot_evoked_topomapplot_evoked_fieldplot_evoked_imageplot_evoked_topo)plot_evoked_whiteplot_evoked_joint_topomap_animation)FIFF) fiff_open)read_tag) dir_tree_find) pick_types _picks_to_idx_FNIRS_CH_TYPES_SPLIT) ContainsMixinread_meas_infowrite_meas_info_read_extended_ch_info _rename_list_ensure_infos_match) ProjMixin) start_and_end_file start_block end_block write_int write_stringwrite_float_matrixwrite_id write_floatwrite_complex_float_matrix)_check_maxshield_get_ch_factors) parallel_func) averageZstandard_errorZ single_epochZpartial_averageZalternating_subaverageZsample_cut_out_by_graphZpower_density_spectrumZdipole_amplitude_cuvreZsquid_modulation_lower_boundZsquid_modulation_upper_boundZsquid_gate_settingcCsi|]\}}||qSrJ).0keyvalrJrJI/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/evoked.py <srOc@seZdZdZedWddddZed d Zejd d Zed d Z e jdd Z e dXddZ edYddZ edZddddZ edddddZed[dddddZddZeddZeed\ddd$d%d&Zeed]d*d+Zeedd,dd-ddddd.gddddd/dd dfd0d1Zeedddddddddd2d3d4d#dddddddd5d6eddeded3dfd7d8Zeed^d;dd<d=d>Zee d_d?d@Z!ee"d`dCdDZ#e daeeddEdFdGZ$dbdJdKZ%e dcdLdMZ&dNdOZ'dPdQZ(dddSdTZ)ededddUdVZ*dS)fEvokedaEvoked data. Parameters ---------- fname : str Name of evoked/average FIF file to load. If None no data is loaded. condition : int, or str Dataset ID number (int) or comment/name (str). Optional if there is only one data set in file. proj : bool, optional Apply SSP projection vectors. kind : str Either 'average' or 'standard_error'. The type of data to read. Only used if 'condition' is a str. allow_maxshield : bool | str (default False) If True, allow loading of data that has been recorded with internal active compensation (MaxShield). Data recorded with MaxShield should generally not be loaded directly, but should first be processed using SSS/tSSS to remove the compensation signals that may also affect brain activity. Can also be "yes" to load without eliciting a warning. %(verbose)s Attributes ---------- %(info_not_none)s ch_names : list of str List of channels' names. nave : int Number of averaged epochs. kind : str Type of data, either average or standard_error. comment : str Comment on dataset. Can be the condition. data : array of shape (n_channels, n_times) Evoked response. first : int First time sample. last : int Last time sample. tmin : float The first time point in seconds. tmax : float The last time point in seconds. times : array Time vector in seconds. Goes from ``tmin`` to ``tmax``. Time interval between consecutive time samples is equal to the inverse of the sampling frequency. baseline : None | tuple of length 2 This attribute reflects whether the data has been baseline-corrected (it will be a ``tuple`` then) or not (it will be ``None``). Notes ----- Evoked objects can only contain the average of a single set of conditions. NTrIFrcCst|tdt|ddd}t||||\|_|_|_|_}|_|_ | ||j |_ d|_|d|_|rx|||_dS)Nz'proj'Tread)fname must_exist overwriter)rboolr$ _read_evokedinfonave _aspect_kindcommentdatabaseline _set_timestimescopy _raw_times_decimZ_update_first_lastpreloadZ apply_projfilename)selfrS conditionprojkindallow_maxshieldrr_rJrJrN__init__{s    zEvoked.__init__cCs t|jS)zThe data kind.) _aspect_revrZrerJrJrNrhsz Evoked.kindcCs"td|ttt||_dS)Nrh)rlist _aspect_dictkeysrZ)rerhrJrJrNrhscCs|jS)zThe data matrix._datarlrJrJrNr\sz Evoked.datacCs ||_dS)zSet the data matrix.Nrp)rer\rJrJrNr\sc Csbt|j|ddd}|||\}}|j|||f}|dk r^t|||}||ddtjf9}|S)aGet evoked data as 2D array. Parameters ---------- %(picks_all)s %(units)s tmin : float | None Start time of data to get in seconds. tmax : float | None End time of data to get in seconds. Returns ------- data : ndarray, shape (n_channels, n_times) A view on evoked data. Notes ----- .. versionadded:: 0.24 allrJexcludeN)r4rXZ_handle_tmin_tmaxr\rGnpnewaxis) repicksunitstmintmaxstartstopr\Z ch_factorsrJrJrNget_datas zEvoked.get_datac  st|dt|j|ddd}ts,td|j|dk rT||jjkrT|j||_td|jj dgt t |\}}|d kr|D],}t |ddff|j|ddf<qnD|fd d |D} t |D]\} } | | |j| ddf<q|S) aApply a function to a subset of channels. %(applyfun_summary_evoked)s Parameters ---------- %(fun_applyfun_evoked)s %(picks_all_data_noref)s %(dtype_applyfun)s %(n_jobs)s %(verbose)s %(kwargs_fun)s Returns ------- self : instance of Evoked The evoked object with transformed data. zevoked.apply_functionrJF)rtZ with_ref_megzfun needs to be a functionNz evoked.ndimrc3s(|] }|ddffVqdSNrJ)rKpZdata_infunkwargsZp_funrJrN sz(Evoked.apply_function..) r#r4rXcallable ValueErrorrqdtypeastyperndimrHr enumerate) rerrwrn_jobsrrparallelidxZdata_picks_newpprrJrrNapply_functions$ ,zEvoked.apply_functionNrcCsjt||j|jdd}|jdk r2|dkr2tdn4|dkrJttdnt|j|j|dd|_||_|S)aBaseline correct evoked data. Parameters ---------- %(baseline_evoked)s Defaults to ``(None, 0)``, i.e. beginning of the the data until time point zero. %(verbose)s Returns ------- evoked : instance of Evoked The baseline-corrected Evoked object. Notes ----- Baseline correction can be done multiple times. .. versionadded:: 0.13.0 sfreq)r_rNzYThe data has already been baseline-corrected. Cannot remove existing baseline correction.F)r`) rr_rXr]rrrrr\)rer]rrJrJrNapply_baselines zEvoked.apply_baselinerUrcCst|||ddS)a'Save evoked data to a file. Parameters ---------- fname : str The name of the file, which should end with ``-ave.fif(.gz)`` or ``_ave.fif(.gz)``. %(overwrite)s %(verbose)s Notes ----- To write multiple conditions into a single file, use `mne.write_evokeds`. .. versionchanged:: 0.23 Information on baseline correction will be stored with the data, and will be restored when reading again via `mne.read_evokeds`. )rUN) write_evokeds)rerSrUrrJrJrNsavesz Evoked.saveautocCs"ddlm}||||||ddS)agExport Evoked to external formats. %(export_fmt_support_evoked)s %(export_warning)s Parameters ---------- %(fname_export_params)s %(export_fmt_params_evoked)s %(overwrite)s %(verbose)s Notes ----- .. versionadded:: 1.1 %(export_warning_note_evoked)s r)export_evokedsrN)exportr)rerSfmtrUrrrJrJrNr2s z Evoked.exportcCsd}t|j|kr*|jd|}|d7}n|j}d||j|jf}|d|jd|jdf7}|d7}|jdkrz|d7}nL||jdd d |jd d d 7}|jt|j|j|jd ddkr|d7}|d|jj d7}|dt |j f7}d|S)Nz...z'%s' (%s, N=%s)u, %0.5g – %0.5g secrz , baseline offgu – rz secradjust)r_rZon_baseline_outside_dataz8 (baseline period was cropped after baseline correction)z, %s chz, ~%sz ) lenr[rhrYr_r]rrXr\shaper_size)reZmax_comment_lengthr[srJrJrN__repr__Js*   $zEvoked.__repr__cCs |jdS)zChannel names.ch_namesrXrlrJrJrNr`szEvoked.ch_namesbadstightunsortedr) highlightrcCs6t|||||||||| | | | | |||||||||dS)N)rwrtunitshowylimrgxlimhlinerxscalingstitlesaxesgfp window_titlespatial_colorszorder selectable noise_cov time_unitsphererr)r&)rerwrtrrrrrgrrxrrrrrrrrrrrrrrJrJrNplotes2z Evoked.plotRdBu_rGreys?cCs4t|||||||||| | | | | ||||||||dS)N)rwrtrrclimrrgrxrrrcmapcolorbarmask mask_style mask_cmap mask_alphar show_namesgroup_byr)r))rerwrtrrrrrgrxrrrrrrrrrrrrrrJrJrN plot_imageus0zEvoked.plot_imageg= ףp=?nonewcCs,t|||||||||| | | | | ||||dS)zF Notes ----- .. versionadded:: 0.10.0 )layout layout_scalecolorborderrrtitlergvlinefig_background merge_gradslegendrbackground_colorrrtr)r*)rerrrrrrrrgrrrrrrrrtrrJrJrN plot_topos( zEvoked.plot_topo@rz%3.1fheadc!CsFt|||||||||| | | | | |||||||||||||||||dS)N)r_ch_typevminvmaxrsensorsrrrxressizecbar_fmtr time_formatrgrrrr mask_paramsoutlinescontours image_interprIr extrapolaterrnrowsncols)r')rer_rrrrrrrrxrrrrrrgrrrrrrrrrIrrrrrrrJrJrN plot_topomapsB zEvoked.plot_topomap t = %0.0f msZterrain) interactionrc Cst|||||||||| d S)N)time time_labelrfigr n_contoursrr)r() reZ surf_mapsrrrrrrrrrJrJrN plot_fieldszEvoked.plot_fieldc Cst||||||||dS)N)rrankrrrrr)r+)rerrrrrrrrJrJrN plot_whiteszEvoked.plot_whitepeaksc Cst||||||||dS)N)r_rrwrtrts_args topomap_args)r,)rer_rrwrtrrrrJrJrN plot_joints  zEvoked.plot_joint)rrrc  Cs t|||||||||| | | d S)aMake animation of evoked data as topomap timeseries. The animation can be paused/resumed with left mouse button. Left and right arrow keys can be used to move backward or forward in time. Parameters ---------- ch_type : str | None Channel type to plot. Accepted data types: 'mag', 'grad', 'eeg', 'hbo', 'hbr', 'fnirs_cw_amplitude', 'fnirs_fd_ac_amplitude', 'fnirs_fd_phase', and 'fnirs_od'. If None, first available channel type from the above list is used. Defaults to None. times : array of float | None The time points to plot. If None, 10 evenly spaced samples are calculated over the evoked time series. Defaults to None. frame_rate : int | None Frame rate for the animation in Hz. If None, frame rate = sfreq / 10. Defaults to None. butterfly : bool Whether to plot the data as butterfly plot under the topomap. Defaults to False. blit : bool Whether to use blit to optimize drawing. In general, it is recommended to use blit in combination with ``show=True``. If you intend to save the animation it is better to disable blit. Defaults to True. show : bool Whether to show the animation. Defaults to True. time_unit : str The units for the time axis, can be "ms" (default in 0.16) or "s" (will become the default in 0.17). .. versionadded:: 0.16 %(sphere_topomap_auto)s %(image_interp_topomap)s %(extrapolate_topomap)s .. versionadded:: 0.22 %(verbose)s Returns ------- fig : instance of matplotlib.figure.Figure The figure. anim : instance of matplotlib.animation.FuncAnimation Animation of the topomap. Notes ----- .. versionadded:: 0.12.0 ) rr_ frame_rate butterflyblitrrrrrrr-) rerr_rrrrrrrrrrJrJrNanimate_topomaps:zEvoked.animate_topomapgradfastcCsddlm}||||dS)aCompute virtual evoked using interpolated fields. .. Warning:: Using virtual evoked to compute inverse can yield unexpected results. The virtual channels have ``'_v'`` appended at the end of the names to emphasize that the data contained in them are interpolated. Parameters ---------- ch_type : str The destination channel type. It can be 'mag' or 'grad'. mode : str Either ``'accurate'`` or ``'fast'``, determines the quality of the Legendre polynomial expansion used. ``'fast'`` should be sufficient for most applications. Returns ------- evoked : instance of mne.Evoked The transformed evoked object containing only virtual channels. Notes ----- This method returns a copy and does not modify the data it operates on. It also returns an EvokedArray instance. .. versionadded:: 0.9.0 r)_as_meg_type_inst)rmode)forwardr)rerrrrJrJrNas_types zEvoked.as_typecCs*t|j|}t|j||dd|j|<|S)a~Detrend data. This function operates in-place. Parameters ---------- order : int Either 0 or 1, the order of the detrending. 0 is a constant (DC) detrend, 1 is a linear detrend. %(picks_good_data)s Returns ------- evoked : instance of Evoked The detrended evoked object. rZaxis)r4rXrr\)reorderrwrJrJrNr(s zEvoked.detrendcCs t|}|S)zCopy the instance of evoked. Returns ------- evoked : instance of Evoked A copy of the object. r)reevokedrJrJrNr`>sz Evoked.copycCsP|}|jd9_|jdk r:d|jkr:d|jd|_d|jpDd|_|S)zNegate channel responses. Returns ------- evoked_neg : instance of Evoked The Evoked instance with channel data negated and '-' prepended to the comment. rN + ()z- unknown)r`r\r[)reoutrJrJrN__neg__Is zEvoked.__neg__absc sdt}|jddd} tdt|||dk rH|| krHtd|dnt| dkrd|dkrdtd |r|d krztd n|d krtd d} } } } }}}d}|dkr|} nT|dkrd} nF|dkrd} n8|dkrd} n*|dkrd}n|dkrd}n|tkr |}|dk rH|r,t|jdd}nt |j| | | | |d||d }|j }|j |dk rx||}fdd|D|rt ||g\}}dddddDt ||j|||\}}}||r|n|j|f}|r||f7}|S)ahGet location and latency of peak amplitude. Parameters ---------- ch_type : str | None The channel type to use. Defaults to None. If more than one channel type is present in the data, this value **must** be provided. tmin : float | None The minimum point in time to be considered for peak getting. If None (default), the beginning of the data is used. tmax : float | None The maximum point in time to be considered for peak getting. If None (default), the end of the data is used. mode : 'pos' | 'neg' | 'abs' How to deal with the sign of the data. If 'pos' only positive values will be considered. If 'neg' only negative values will be considered. If 'abs' absolute values will be considered. Defaults to 'abs'. time_as_index : bool Whether to return the time index instead of the latency in seconds. merge_grads : bool If True, compute peak from merged gradiometer data. return_amplitude : bool If True, return also the amplitude at the maximum response. .. versionadded:: 0.16 Returns ------- ch_name : str The channel exhibiting the maximum response. latency : float | int The time point of the maximum response, either latency in seconds or index. amplitude : float The amplitude of the maximum response. Only returned if return_amplitude is True. .. versionadded:: 0.16 )magreegseegdbsecogmiscNoneT)uniqueZ only_data_chsrNzChannel type "z"" not found in this evoked object.rzGMultiple data channel types found. Please pass the "ch_type" parameter.rz+Channel type must be "grad" for merge_gradsnegzBNegative mode (mode=neg) does not make sense with merge_grads=TrueF)r rr rrrr)Ztopomap_coords)megr rrrZref_megfnirsrcsg|] }|qSrJrJrKkrrJrN sz#Evoked.get_peak..cSsg|]}|dddqS)NrXrJ)rKZch_namerJrJrNrsr~)r5Zget_channel_typesrstrrr RuntimeErrorr rXr3r\rr _get_peakr_)rerryrzrZ time_as_indexrZreturn_amplitude supportedZ types_usedrr rrrrrrwr\_Zch_idxZtime_idxZmax_ampr rJrrNget_peakZs|+         zEvoked.get_peakc Cst}dg} ddg} t|| }t|| }t|j|ddd}|j|ddf} |j} | j} |rd| } t || ||} t } t || |} | d| ft || ||| |dgd}|S) a\Export data in tabular structure as a pandas DataFrame. Channels 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 ---------- %(picks_all)s %(index_df_evk)s Defaults to ``None``. %(scalings_df)s %(copy_df)s %(long_format_df_raw)s %(time_format_df)s .. versionadded:: 0.20 %(verbose)s Returns ------- %(df_return)s rms timedeltarrrJrsN)Z default_index)rrr"r4rXr\r_Tr`r!rmr appendr)rerwindexrr`Z long_formatrrpdZvalid_index_argsZvalid_time_formatsr\r_ZmindexZdfrJrJrN to_data_frames&   zEvoked.to_data_frame)NTrIF)NNNN)NNNN)r)r)NrTTNrFNNNNNFNFrTNrN)NrTTNrFNNNNrTNNrrrNNN)NrNNNr)TNrNNN)rrNrTNN)NNNFTTrN)rr)rN)NNNr FFF)NNNTFN)+__name__ __module__ __qualname____doc__rrjpropertyrhsetterr\rr}rrrrrrrr&rr)rr*rr'r rrrr(rr+rr,rrrrr`r r!r(rJrJrJrNrP?s\9     ! /$      ?    qrPc@s$eZdZdZed dddd ZdS) EvokedArrayaEvoked object from numpy array. Parameters ---------- data : array of shape (n_channels, n_times) The channels' evoked response. See notes for proper units of measure. %(info_not_none)s Consider using :func:`mne.create_info` to populate this structure. tmin : float Start time before event. Defaults to 0. comment : str Comment on dataset. Can be the condition. Defaults to ''. nave : int Number of averaged epochs. Defaults to 1. kind : str Type of data, either average or standard_error. Defaults to 'average'. %(baseline_evoked)s Defaults to ``None``, i.e. no baseline correction. .. versionadded:: 0.23 %(verbose)s See Also -------- EpochsArray, io.RawArray, create_info Notes ----- Proper units of measure: * V: eeg, eog, seeg, dbs, emg, ecg, bio, ecog * T: mag * T/m: grad * M: hbo, hbr * Am: dipole * AU: misc rrrrINrQc Cspt|rtjntj} tj|| d}|jdkr>td|jft|dt|dkrztdt|dt|df||_ t t ||d|_ |j t|dd |_ |tj|j |j d tjd|d|j|_d |_||_||_||_||_d|_d |_d|_t|jd d |jtkrBtd |jft|j|_||_|jdk rl||jdS)N)rr~zFData must be a 2D array of shape (n_channels, n_samples), got shape %srrz:Info (%s) and data (%s) must have same number of channels.rrrTrrhz:unknown kind "%s", should be "average" or "standard_error") ru iscomplexobj complex128float64Z asanyarrayrrrrr\introundfirstlastr^aranger_r`rarbrXrYrhr[rwrcZ _projectorrrnrZr]r) rer\rXryr[rYrhr]rrrJrJrNrj&sL        zEvokedArray.__init__)rrrrIN)r)r*r+r,rrjrJrJrJrNr/s%r/Fc Cs<t}t}|D]}t|dD]@}|d|j}|d|j}|tjkr t||} || jq t ||d} t| dD]D}| d|j}| d|j}|tj kr|t||} |t | jq|qt |}t |}t|t|kst|dkr|tddd|D} ddt| |D} d| } ||| fS) zGet all evoked entries.nent directoryrz-Dataset names in FIF file could not be found.cSsg|] }t|qSrJ)rk)rKarJrJrNrgsz _get_entries..cSs$g|]\}}d|d|dqS)"z" (rrJ)rKttcrJrJrNrhs )rmrangerhposr/ FIFF_COMMENTr1r%r\ _get_aspectFIFF_ASPECT_KINDr3ruZ atleast_1drcloserzipjoin) fid evoked_nodericomments aspect_kindsevrmy_kindr@tag my_aspecttrJrJrN _get_entriesOs2       rPcCsVd}t|tj}t|dkr4t|t|tj}d}t|dkrJtd|d|fS)zGet Evoked data aspect.FrTrz.Multiple data aspects found. Taking first one.)r2r/ FIFFB_ASPECTrrFFIFFB_IAS_ASPECTrrX)rriZ is_maxshieldaspectrJrJrNrBms     rBc Cs@t|\}}}|$}t||dd\}}t|tj}W5QRX|S)zGet info in evoked file.FrQ)r0r7r2r/ FIFFB_EVOKED)rSftreer rGmeasrHrJrJrN_get_evoked_nodezs rXcCs|d}|j}t|ddD]\}}|j|krzt|jt|krTtd||fn&td|}|||||d<tt |j |j dkstd||fq|S)Nrrz+%s and %s do not contain the same channels.z2Order of channels differs, reordering channels ...gHz>z/%s and %s do not contain the same time instants) rrsetrrr`Zreorder_channelsrumaxr r_) all_evokedrriirKrJrJrN_check_evokeds_ch_names_timess&   r]cCstdd|Dt}t|trZtd|ddg|dkrF||}qft|t|}n t|t}|j dks~|j t|krt ddt|d |}t |}|d  }ttd d |D}||jd <tdd t||D|_||_d}tt||D]\}\}} |d krdnd} tt|dr6dn t|d} | rLdnd} | jdk rxd| jkrxd| jd} n| jpd} |d kr|| | | | 7}n"|d| pdd| | | 7}q|dd|_|S)aMerge evoked data by weighted addition or subtraction. Each `~mne.Evoked` in ``all_evoked`` should have the same channels and the same time instants. Subtraction can be performed by passing ``weights=[1, -1]``. .. Warning:: Other than cases like simple subtraction mentioned above (where all weights are -1 or 1), if you provide numeric weights instead of using ``'equal'`` or ``'nave'``, the resulting `~mne.Evoked` object's ``.nave`` attribute (which is used to scale noise covariance when applying the inverse operator) may not be suitable for inverse imaging. Parameters ---------- all_evoked : list of Evoked The evoked datasets. weights : list of float | 'equal' | 'nave' The weights to apply to the data of each evoked instance, or a string describing the weighting strategy to apply: ``'nave'`` computes sum-to-one weights proportional to each object's ``nave`` attribute; ``'equal'`` weights each `~mne.Evoked` by ``1 / len(all_evoked)``. Returns ------- evoked : Evoked The new evoked data. Notes ----- .. versionadded:: 0.9.0 cSsg|] }|jqSrJ)rY)rKZevkrJrJrNrsz"combine_evoked..weightsrYequalrz+weights must be the same size as all_evoked?r~rcss"|]}|jdD] }|VqqdS)rNr)rKebrJrJrNrs z!combine_evoked..rcss|]\}}||jVqdSrr\)rKrrarJrJrNrsr-z0.3fu × Nrrrr +z - - )ruarrayfloat isinstancerrsum ones_likerrrrr]r`rmrYrXrEr\rYriscloser r[replace)r[r^ZnavesZnew_naverrr[rrrasignweightZ multiplierZ this_commentrJrJrNcombine_evokeds:!     " &rprITc Cst|ddd}t|ddtd|d}|dkrJt|}tt|}nt|ts^|g}d}g} |D]} t || ||||d } |dkr| j dkrtt dnD|dkr| j dk r| j \} } td | d d | d d n | || | qf|r| S| dS)a Read evoked dataset(s). Parameters ---------- fname : path-like The filename, which should end with ``-ave.fif`` or ``-ave.fif.gz``. condition : int or str | list of int or str | None The index or list of indices of the evoked dataset to read. FIF files can contain multiple datasets. If None, all datasets are returned as a list. %(baseline_evoked)s If ``None`` (default), do not apply baseline correction. .. note:: Note that if the read `~mne.Evoked` objects have already been baseline-corrected, the data retrieved from disk will **always** be baseline-corrected (in fact, only the baseline-corrected version of the data will be saved, so there is no way to undo this procedure). Only **after** the data has been loaded, a custom (additional) baseline correction **may** be optionally applied by passing a tuple here. Passing ``None`` will **not** remove an existing baseline correction, but merely omit the optional, additional baseline correction. kind : str Either 'average' or 'standard_error', the type of data to read. proj : bool If False, available projectors won't be applied to the data. allow_maxshield : bool | str (default False) If True, allow loading of data that has been recorded with internal active compensation (MaxShield). Data recorded with MaxShield should generally not be loaded directly, but should first be processed using SSS/tSSS to remove the compensation signals that may also affect brain activity. Can also be "yes" to load without eliciting a warning. %(verbose)s Returns ------- evoked : Evoked or list of Evoked The evoked dataset(s); one `~mne.Evoked` if ``condition`` is an integer or string; or a list of `~mne.Evoked` if ``condition`` is ``None`` or a list. See Also -------- write_evokeds Notes ----- .. versionchanged:: 0.23 If the read `~mne.Evoked` objects had been baseline-corrected before saving, this will be reflected in their ``baseline`` attribute after reading. rRT)rUrTrz-ave.fifz -ave.fif.gzz_ave.fifz _ave.fif.gzzReading %s ...NF)rhrgrirz5Loaded Evoked data is baseline-corrected (baseline: [rz, z] sec)r)r$rrrXrXr?rrirmrPr]rrr%)rSrfr]rhrgrirZ return_listrHr r=rbminbmaxrJrJrN read_evokedss08      rtc* s|dkrtdt|\}}}|>}t||dd\}t|tj} t| dkrXtdt|tj} t| dkrxtdt|t r|t krtdt || |\} } } t | |gt | t |g@}t |d}t|d krtd ||| f|d}n<|dkr:t| d kr6t || |\}}}td |nd}|t| ksR|dkrZtd | |}t||\}d <W5QRXd}d}g}d}}}d}}}}}t|dD]v}|d|j}|d|j} |tjkrt|| }!|!j}q|tjkr&t|| }!t|!j}q|tjkrHt|| }!t|!j}n|tjkrjt|| }!t|!j}n|tjkrt|| }!t|!j}n|tjkrt|| }!| |!jn|tj!krt|| }!t|!j}nd|tj"krt|| }!t|!j}nB|tj#krt|| }!t|!j}n |tj$krt|| }!t|!j}q|dkrHd}|dk s\|dk r||dk rp|dk stt%||f}|dkr|dkrtdt||krtdt&|||}"|d<t'd|"ddd<t()d||dkr|d<d }#g}$t|dD]}|d|j}|d|j} |tjkrNt|| }!|!j}nd|tj*krpt|| }!t|!j}%nB|tj+krt|| }!t|!j}#n |tj,krt|| }!|$ |!qt|$}&|&d kr|&dkrtd|&df|&d kr$|$dj}'|'j-d d kr<dd kr<|'j.}'nt j/dd|$Ddd}'t 0|'rV|'1t j2}'n |'1t j3}'|dk r|dk r|t 4|d}(n8|dk r||d }t 4||d d}(nt5d~~|dk r|'j-d |krtd|'j-d |ft()dt()d d!|(dd!|(d|fd"dk rLt()d#td"t()d$|#|%fW5QRXt 6fd%dtdD})|'|)ddt j7f9}'|#|%||(|'|fS)&z!Read evoked data from a FIF file.NzNo evoked filename specifiedT)Z clean_badsrzCould not find processed datazCould not find evoked dataz*kind must be "average" or "standard_error"rz8condition "%s" (%s) not found, out of found datasets: %sz\Evoked file has more than one condition, the condition parameters must be specified from: %szData set selector out of range maxshieldrr8r9z No commentz=Local channel information was not found when it was expected.zBNumber of channels and number of channel definitions are differentchsrz8 Found channel information in evoked data. nchan = %drnchanz=Number of epoch tags is unreasonable (nepoch = %d nchan = %d)cSsg|]}|jdddfqSrrc)rKrarJrJrNrsz _read_evoked..rzCould not read time parametersz/Incorrect number of samples (%d instead of %d)z Found the data of interest:z% t = %10.2f ... %10.2f ms (%s)rcompsz. %d CTF compensation matrices availablez$ nave = %d - aspect type = %dcs0g|](}d|dd|ddqS)rvcalscaler`)getrrrJrNrs)8rr0r7r2r/FIFFB_PROCESSED_DATArrTrirrnrorPruZin1dwhere TypeErrorZ_unlockrBr?rhr@rAr1r\FIFF_FIRST_SAMPLEr3FIFF_LAST_SAMPLEZ FIFF_NCHANZ FIFF_SFREQrhZ FIFF_CH_INFOr%FIFF_FIRST_TIMEFIFF_NO_SAMPLESFIFF_MNE_BASELINE_MINFIFF_MNE_BASELINE_MAXAssertionErrorr9r:rrXrC FIFF_NAVE FIFF_EPOCHrr$Z concatenateZ isrealobjrr2r1r7rrgrv)*rSrfrhrirUrVr rGrW processedrHrIrJrOZgoodsZ found_cond conditionsZ my_evokedrNrwrrvr]rrrsr[r6r5Z first_timeZnsamprrLr@rMZch_names_mappingrYepochZ aspect_kindZnepochr\r_ZcalsrJrrNrWLs6                                                                   rWraise) on_mismatchrUrcCst||||ddS)a5Write an evoked dataset to a file. Parameters ---------- fname : str The file name, which should end with -ave.fif or -ave.fif.gz. evoked : Evoked instance, or list of Evoked instances The evoked dataset, or list of evoked datasets, to save in one file. Note that the measurement info from the first evoked instance is used, so be sure that information matches. %(on_mismatch_info)s %(overwrite)s .. versionadded:: 1.0 %(verbose)s .. versionadded:: 0.24 See Also -------- read_evokeds Notes ----- .. versionchanged:: 0.23 Information on baseline correction will be stored with each individual `~mne.Evoked` object, and will be restored when reading the data again via `mne.read_evokeds`. rrUN)_write_evokeds)rSrrrUrrJrJrNr s rrc Csddlm}t||d}|r(t|ddt|ttfs<|g}d}t|}t|t j t |t j |dj dd k rt |t j|dj dt||dj t|t jt|D]\}} |rt|dj | j d |d |d t|t j| jd k rt| jdkrt|t j| jt|t j| jdt|t jt| jt|t j| jt|t j| j t| |s| j!d k r| j!\} } t|t j"| t|t j#| | j $d rt j%} nt j&} t|| t|t j'| j(t)t*| j+} | | j+kr|st,dd}t|t j-| ~ t./| j ddf}t0| j dD]6}d| j d|d| j d|$dd||<q2t.1| j2r~t3}nt4}||t j5|| j2t6|| t6|t jqt6|t jt6|t j W5QRXd S)zWrite evoked data.r) DipoleFixed)rSrUrrqFrZmeas_idNzevoked[])Zinfo1Zinfo2namerruzconverting "nave" to integer before saving evoked; this can have a minor effect on the scale of source estimates that are computed using "nave".Trwr`rvryrz)7Zdipolerr$rrirmtupler=r>r/Z FIFFB_MEASrCZ FIFF_BLOCK_IDrXZFIFF_PARENT_BLOCK_IDr8r|rr;rTr[rrArArDrr_r@rrr5rr6r]rrr{rRrQrCrZr3r4rYrrruZzerosr?r0r\rErBrr?)rSrcheckrrUrZwarnedrGeirarrrsrSZnave_intZdecalrZwrite_functionrJrJrNr,sn             rr c Cstd|dddg|dkr"|d}|dkr2|d}||ksJ||kr||kr`d}|}nd }|}t|d |d |d |n||krtd |d|d||k||k@}t|t}d|dd|f<tj} |dkrt ||dksr?r@rArBrCrDrEZio.baserFrGrrHZFIFFV_ASPECT_AVERAGEZFIFFV_ASPECT_STD_ERRZFIFFV_ASPECT_SINGLEZFIFFV_ASPECT_SUBAVERAGEZFIFFV_ASPECT_ALTAVERAGEZFIFFV_ASPECT_SAMPLEZFIFFV_ASPECT_POWER_DENSITYZFIFFV_ASPECT_DIPOLE_WAVEZFIFFV_ASPECT_IFII_LOWZFIFFV_ASPECT_IFII_HIGHZFIFFV_ASPECT_GATErnitemsrkrPr/rPrBrXr]rprtrWrrrrJrJrJrN s T       ,  DO   ^ V >" V