U f{jU@sdZddlmZddlmZddlmZddlZddlZddl m Z ddl Z ddlmZddlmZmZmZmZmZmZmZmZmZmZmZmZmZmZdd lm Z m!Z!m"Z"m#Z#m$Z$dd l%m&Z&m'Z'dd l(m)Z)dd l*m+Z+m,Z,dd l-m.Z.ddl/m0Z0ddl1m2Z2m3Z3m4Z4m5Z5m6Z6m7Z7m8Z8ddl9m:Z:m;Z;ddlZ>ddl?m@Z@ddlAmBZBddlCmDZDmEZEmFZFddlGmHZHmIZImJZJddlKmLZLmMZMmNZNddlOmPZPddlQmRZRmSZSmTZTddlUmVZVddlWmXZXmYZYmZZZm[Z[m\Z\m]Z]ddl^m_Z_m`Z`maZambZbmcZcmdZdmeZemfZfmgZgmhZhmiZimjZjmkZkmlZlmmZmmnZnmoZompZpmqZqmrZrmsZsmtZtmuZumvZvmwZwmxZxmyZymzZzm{Z{m|Z|ddl}m~Z~ddlmZmZmZddZd d!Zd"d#Zd$d%Zd&d'Zd(d)Ze~Gd*d+d+e;e$eHeIeJeMelegeke Zdcd-d.Zddd/d0Ze~Gd1d2d2eZe~Gd3d4d4eZded6d7Zdfd9d:Zd;d<Zd=d>Zebd?gdfd@dAZdBdCZebdgdDdEZGdFdGdGeZe~GdHdIdIeZe~dhdJdKZdLdMZebdidNdOZdjdPdQdRdSZdTdUZebdkdPddVdWdXZebdld]d^ZebdmdadbZdS)nz$Tools for working with epoched data.)partial)CounterdeepcopyN)_construct_bids_filename)start_and_end_file start_block end_block write_int write_floatwrite_float_matrixwrite_double_matrixwrite_complex_float_matrixwrite_complex_double_matrixwrite_id write_string_get_split_size_NEXT_FILE_BUFFER INT32_MAX)read_meas_infowrite_meas_info _merge_info_ensure_infos_match ContainsMixin) fiff_open_get_next_fname) dir_tree_find)read_tag read_tag_info)FIFF)_get_fname_rep)channel_indices_by_type channel_type pick_channels pick_info_pick_data_channels_DATA_CH_TYPES_SPLIT _picks_to_idx) setup_proj ProjMixin)BaseRaw_get_ch_factors) _check_origin) EvokedArray)rescale _log_rescale_check_baseline)UpdateChannelsMixinSetChannelsMixinInterpolationMixin)detrend FilterMixin _check_fun) parallel_func)_read_events_fifmake_fixed_length_eventsmatch_event_names) rng_uniform) plot_epochsplot_epochs_psdplot_epochs_psd_topomapplot_epochs_imageplot_topo_image_epochs plot_drop_log) _check_fname check_fnameloggerverbosecheck_random_statewarn_pl sizeof_fmt SizeMixincopy_function_doc_to_method_doc_check_pandas_installed_check_preloadGetEpochsMixin TimeMixin_prepare_read_metadata_prepare_write_metadata_check_event_id _gen_events _check_option_check_combine_build_data_frame_check_pandas_index_arguments_convert_times_scale_dataframe_data_check_time_format object_size _on_missing_validate_type_ensure_events _path_like)fill_doc)_write_annotations_read_annotations_fifEpochAnnotationsMixincCs0t}dD] }t||d}|dk r |||<q |S)N)rejectflat reject_tmin reject_tmax)dictgetattr)epochs reject_paramskeyvalroI/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/epochs.py_pack_reject_paramsGs   rqc Cst|\}}|dkrV|dkr.d|||f}n(|dks:tt|||dd}t||dd} ||d kr|dkrd||d |f} n |dkstt|||d dd} |d } nd} t|} t| |||| | W5QRXdS) zSplit epochs. Anything new added to this function also needs to be added to BaseEpochs.save to account for new file sizes. rneuromagz%s-%d%sZbidsF)validate) overwriteNr)opsplitextAssertionErrorrrCr _save_part) rkfnamepart_idxn_partsfmt split_namingrtbaseext next_fnamenext_idxfidrororp _save_splitPs*       rcCsZ|j}|d}t|tjt|tj|ddk rDt|tj|dt||t|tjt|tj | }t d|ddgt |r|dkrt} q|dkrt} n|dkrt} n |dkrt} t|dg} | dk rt| rt|| t|tjt|tj|jjt|tjt|jt|tj|jdk r^t|tj t!|j} t|tj| t|tj t"t#|j$|d} | t|j%d} t|tj&| t|tj'| t(|tj)|j*|j+dk r|j+\}}t(|tj,|t(|tj-|t .|d}t/|dD]2}d |d |d |d |0d d ||<q||t j1ddt j1f9}| |tj2|||t j1ddt j1f}t|tj3t45|j6t7|}|rt|tj8t45|t|tj9|j:|dk r2|dkr2t|tj;t|tjt?@||dk rt|tjA|t|tjB|t|tj;t|tj t|tjt|tjdS) Nmeas_idr|singledouble annotationssfreqrnchan?chscalscale)Cinfor r Z FIFFB_MEASrZ FIFF_BLOCK_IDZFIFF_PARENT_BLOCK_IDrFIFFB_PROCESSED_DATAFIFFB_MNE_EPOCHSget_datarUnp iscomplexobjrrr rrjlenrbZFIFFB_MNE_EVENTSr ZFIFF_MNE_EVENT_LISTeventsTrFIFF_DESCRIPTION_event_id_stringevent_idr metadataFIFFB_MNE_METADATArRintroundtmintimesFIFF_FIRST_SAMPLEFIFF_LAST_SAMPLEr FIFF_MNE_EPOCHS_RAW_SFREQ _raw_sfreqbaselineFIFF_MNE_BASELINE_MINFIFF_MNE_BASELINE_MAXemptyrangegetnewaxis FIFF_EPOCHFIFF_MNE_EPOCHS_DROP_LOGjsondumpsdrop_logrqFIFF_MNE_EPOCHS_REJECT_FLATFIFF_MNE_EPOCHS_SELECTION selectionZ FIFFB_REFZ FIFF_REF_ROLEZFIFFV_ROLE_NEXT_FILEZFIFF_REF_FILE_NAMErubasenameZFIFF_REF_FILE_IDZFIFF_REF_FILE_NUM)rrkr|r{rrrrdataZwrite_functionrrfirstlastbminbmaxZdecalkrlrororprxrs                       rxcCsddd|DS)N;cSs g|]\}}|dt|qS):str.0rvrororp sz$_event_id_string..)joinitemsrrororprsrc s|}|}t}tj|dddfdd\}}||dkD]}|dddf|kd}t||df} t| dkr| dnd} t||df} t| dkr| d} nt|t|fdd| D} |D](}t| d t| kr||} qqttj t||ddddf fdd } | ddkrXd} nBt | }t |dkd}t|dkrd n|d}| |d} d t| }t| ||<| ||ddf<| ||ddf<||ddq@t||d}t||d}|||fS) zMerge repeated events.NrT)Z return_countsrcsg|]}|qSro)index)rvalueZ event_id_keysZ event_id_valsrorprsz!_merge_events../axis)copylistruniquenonzerorkeysvaluessetsplit concatenateflattendiffwherersortedrextenddelete)rrr new_eventsZevent_idxs_to_delete unique_eventscountsevidxsZ unique_priorsZ new_priorZev_valsZ new_event_valZ new_key_compsrmZdiffsidxZnew_event_id_key new_selectionrorrp _merge_eventssR        rc sft|t|kstt|}tj|dddfdd\}}t|t|krX||||fStd|dddgt|}|dkrtd n|dkrt d ||}||}t ||} | D]} || d || <q|}nR|dkr$t d t |||\}}}t ||} | D]} || d || <q|}t |}|ddddf fdd|D}||||fS)zMHandle repeated events. Note that drop_log will be modified inplace NrT)Z return_indexevent_repeatederrordropmergezUEvent time samples were not unique. Consider setting the `event_repeated` parameter."ziMultiple event values for single event times found. Keeping the first occurrence and dropping all others.)zDROP DUPLICATEzlMultiple event values for single event times found. Creating new event value to reflect simultaneous events.)zMERGE DUPLICATErcsi|]\}}|kr||qSrororrrorp Osz*_handle_event_repeated..)rrwrZasarrayrrUr RuntimeErrorrEr setdiff1drtuplerr) rrrrrrZ u_ev_idxsrrZ drop_ev_idxsrrorrp_handle_event_repeated#s:         rcseZdZdZeddddd d d ZddZddZddZedddddZ ddZ edddZ edddZ dddZ ddd Zedd"d#Zedd$d%Zdd&d'Zed(d)Zd*d+Zed,d-Zeedddd1d2d3Zeed4ejddd dd dd5ddd6d7d8d9dd/ddd dddd:dfd;d<Zeedd?d@Zee ddGdHZ!eddJdKZ"ddMdNZ#ee$ddQdRZ$ee%ddSdTZ&eddVdWZ'ddXdYZ(dZd[Z)edddddd\d]d^Z*ed_d`Z+eddadbZ,eddcddZ-ededfZ.dgdhZ/didjZ0edfdkdl Z1dmdnZ2dodpZ3eddtduZ4edd ddvdwdxZ5ddzd{Z6edddd|d}Z7dddZ8Z9S) BaseEpochsaAbstract base class for `~mne.Epochs`-type classes. .. warning:: This class provides basic functionality and should never be instantiated directly. Parameters ---------- %(info_not_none)s data : ndarray | None If ``None``, data will be read from the Raw object. If ndarray, must be of shape (n_epochs, n_channels, n_times). %(events_epochs)s %(event_id)s %(epochs_tmin_tmax)s %(baseline_epochs)s Defaults to ``(None, 0)``, i.e. beginning of the the data until time point zero. %(raw_epochs)s %(picks_all)s %(reject_epochs)s %(flat)s %(decim)s %(epochs_reject_tmin_tmax)s %(detrend_epochs)s %(proj_epochs)s %(on_missing_epochs)s preload_at_end : bool %(epochs_preload)s selection : iterable | None Iterable of indices of selected epochs. If ``None``, will be automatically generated, corresponding to all non-zero events. drop_log : tuple | None Tuple of tuple of strings indicating which epochs have been marked to be ignored. filename : str | None The filename (if the epochs are read from disk). %(metadata_epochs)s %(event_repeated_epochs)s %(verbose)s raw_sfreq : float The original Raw object sampling rate. If None, then it is set to ``info['sfreq']``. annotations : instance of mne.Annotations | None Annotations to set. Notes ----- The ``BaseEpochs`` class is public to allow for stable type-checking in user code (i.e., ``isinstance(my_epochs, BaseEpochs)``) but should not be used as a constructor for Epochs objects (use instead :class:`mne.Epochs`). N皙ɿ?NrrTraiseFr)rF raw_sfreqrc)s\|dk r4t|}|}|tkr4tdtd|t||}|_~|dk rzjD]2\}}||dddfkrZd||f}t||qZt t |_ |_ t jjdd~tj}ttj dddf|d} |dkr| }n t|t}|jt | fkr*td| j|jf|_ |dkrntfd d ttt j tj d D_n|_j | _ tj j|j j\_ __ _tt|j d}!ttrfd d |!Dndk rj|!t jjddd_t j }"|"d krVtj tjdddf dkrVt!dt"|"dkrpt#$d|"ntdnt_tgt_ _|dkst|t%rtd|_&|_'|(t)|| dddd_*t+|j*_$~d_,|dkrd_-d_.d_/nx| d kst0|j1dksP|jdt2||j$dd krXt3d|jdt j krvtdd_-|_.d_/d_4||krtdt5j$d}#tt2||#}$t |$tt2||#d |#_67j6| dk r&t8| |r j9} n| |kr&td| d|dk r`t8||rFj:}n||kr`td|d| dk r|dk r| |krtd| d |d| _;|_| t?|j@j$dd!_AjAdk rjA|krt#$d"jAdd#jAd d$t#$tBjAd_Cd_DE| | dd%dg}%||%krPtd&|%|f|d%krld_Ft#$d'nd_FjFr~dn|}&tGj$d|&d(\_H_$|rʈj.dkst0j-dkst0InJ|dkrjHdk r|dk rtJj.D]\}'}(tKjH|(j.|'<q|dk r&tL|n|_M|dkr@j$d}|_N(O|dS))Nz$events array values must not exceed z, got rz-No matching events found for %s (event id %i)FrFrz'selection must be shape %s got shape %sc3s |]}|jkrdndVqdS)roZIGNOREDN)rrrselfrorp sz&BaseEpochs.__init__..rcsg|] }|qSroro)rs)rrorprsz'BaseEpochs.__init__..zLThe events passed to the Epochs constructor are not chronologically ordered.z%d matching events foundzNo desired events found.)Nrrzdetrend must be None, 0, or 1allro)noneexcludeZ allow_emptyTrzbad data shapez8The number of epochs and the number of events must matchz)tmin has to be less than or equal to tmaxz-reject_tmin needs to be None or >= tmin (got )z-reject_tmax needs to be None or <= tmax (got z reject_tmin (z) needs to be < reject_tmax (rrzSetting baseline interval to [, z] secZdelayedz "proj" must be one of %s, not %szEntering delayed SSP mode.activate)Pr_maxr ValueErrorrSrrr]rarangerrrrOrfsetrrrin1darrayrshaperrrr isinstanceilocrastypeZint64minrHRuntimeWarningrErboolr5_raw_check_consistencyr(picksr%_currentpreload_data _do_baselinerwndimrr_offsetfloat _raw_times _set_timesisclosertmaxrgrh_decimZdecimater1rrr0rerf _reject_setup_do_delayed_projr) _projector load_data enumeratedotr _filenamerset_annotations))rrrrrrrrrawrrerfdecimrgrhr5proj on_missingpreload_at_endrrfilenamerrrFrrZ events_maxrmrnmsgrselectedsubn_eventsr start_idxZ valid_projriiepochro)rrrp__init__s:    $             *            $         zBaseEpochs.__init__cCst|dr:t|jt|jks"tt|jt|jks:tt|jtdd|jDks\tt|dsjt|jjdrztt |jt stt dd|jDstt dd|jDstdS) z"Check invariants of epochs object.rcss|]}t|dkVqdSrNr)rdlrororpr_sz0BaseEpochs._check_consistency.._times_readonlyZ WRITEABLEcss|]}t|tVqdSNr r)rlogrororprcscss"|]}|D]}t|tVq qdSr:r r)rr<rrororprdsN) hasattrrrrrwrsumrflagsr rrrrororprYs   zBaseEpochs._check_consistencycCs2tt|j|_tft|j|_|dS)aReset the drop_log and selection entries. This method will simplify ``self.drop_log`` and ``self.selection`` so that they are meaningless (tuple of empty tuples and increasing integers, respectively). This can be useful when concatenating many Epochs instances, as ``drop_log`` can accumulate many entries which can become problematic when saving. N)rrrrrrrrrrororpreset_drop_log_selectionfs z#BaseEpochs.reset_drop_log_selectioncCs`|jr |S||_d|_d|_tddd|_d|_|j|_|jj dt |jksVt d|_ |S)zLoad the data if not already preloaded. Returns ------- epochs : instance of Epochs The epochs object. Notes ----- This function operates in-place. .. versionadded:: 0.10.0 TFNrr) r _get_datarrslice _decim_slicerrrr rrwrrrororpr#ss zBaseEpochs.load_datarcCs~t||j|jdd}|jr`|jdk r6|dkr6tdd|_|j}t|j |j|d|dd|_nt t |d|_||_|S)aBaseline correct epochs. Parameters ---------- %(baseline_epochs)s Defaults to ``(None, 0)``, i.e. beginning of the the data until time point zero. %(verbose)s Returns ------- epochs : instance of Epochs The baseline-corrected Epochs object. Notes ----- Baseline correction can be done multiple times, but can never be reverted once the data has been loaded. .. versionadded:: 0.10.0 rrNzSYou cannot remove baseline correction from preloaded data once it has been applied.TF)rr) r1rrrrrr_detrend_picksr/rrEr0)rrrFrrororpapply_baselineszBaseEpochs.apply_baselinec Cs t|j}|dk rt|nt}|dk r0t|nt}t||fdD]V\}}t|tsftdt|t| t| }t |dkrDt d||fqD| D]P}t ||dkrt ||t js||ddkrtd||fqt||fdD]B\}}|D].\}}|dks0|dkrtd ||fqq|jdk rZ|jnt} |jdk rr|jnt} d } t| t|D]}| |||<q|D]B}|| kr||| |krt| jd |||| |d d qt| t|D]}| |||<q|D]B}|| kr||| |krt| jd|||| |dd qd|_||_t |dkrr|nd|_t |dkr|nd|_|jdkr|jdkrd|_nl|jdkrd} nt |j|jkd} | d} |jdkrd}nt |j|jkd} | d}t| ||_dS)z1Set self._reject_time and self._channel_type_idx.N)rerfz,reject and flat must be dict or None, not %srz%Unknown channel types found in %s: %srz/No %s channel found. Cannot reject based on %s.)Z RejectionZFlatz(%s value must be a number >= 0, not "%s"zq{kind}["{key}"] == {new} {op} {old} (old value), new {kind} values must be at least as stringent as previous onesre>)kindrmnewoldrurf.csg|]}j|qSror]r)rchrrorpr}scsg|]}tj|qSro)r#r)rrrrorpr~scsg|]}|tkr|qSro)r'r)rt) diff_typesrorprs rrcsg|] }|qSrororj)diff_chrorprszBThe following data channels are missing in the evoked response: %szB The following channels are not included in the subtraction: %sgHz>z=Epochs and Evoked object do not contain the same time points.z,Evoked has SSP applied while Epochs has not.csg|]}jj|qSrormrj)rlrrorprsdtypez[done])rErr&averager$r]rrr differencerrrrrabsr*rHrZ apply_projrrrrzerosfloat64)rrlrZsel_chZdiff_idxZbad_idxZbad_strZep_picksro)rqrprlrrpsubtract_evoked[sJ    :  zBaseEpochs.subtract_evokedmeancCsP|r>t}|jD]&}||j||d}||_||qn|j||d}|S)aCompute an average over epochs. Parameters ---------- %(picks_all_data)s 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_time) returns an array of shape (n_channels, n_time). Note that due to file type limitations, the kind for all these will be "average". %(by_event_type)s Returns ------- %(evoked_by_event_type_returns)s Notes ----- Computes an average of all epochs in the instance, even if they correspond to different conditions. To average by condition, do ``epochs[condition].average()`` for each condition separately. When picks is None and epochs contain only ICA channels, no channels are selected, resulting in an error. This is because ICA channels are not considered data channels (they are of misc type) and only data channels are selected when picks is None. The ``method`` parameter allows e.g. robust averaging. For example, one could do: >>> from scipy.stats import trim_mean # doctest:+SKIP >>> trim = lambda x: trim_mean(x, 0.1, axis=0) # doctest:+SKIP >>> epochs.average(method=trim) # doctest:+SKIP This would compute the trimmed mean. )rmode)rrr_compute_aggregaterbappend)rrmethod by_event_typeZevokedsZ event_typerrororprts) zBaseEpochs.averagecCs|j|d|dS)zCompute standard error over epochs. Parameters ---------- %(picks_all_data)s %(by_event_type)s Returns ------- %(std_err_by_event_type_returns)s std)rr~r)rt)rrrrororpstandard_errors zBaseEpochs.standard_errorc Cs|dkr>dd|jD}t|r,tdnt|r>tdt|j}t|j}|jrt|j }t |dd}||j }t|j t|j kst |j |j j ddkrtd |j |j j ddn|d krtd t||f}d }|D],} t| r|tj}|| 7}|d7}q|d kr.||}n |tj|d kr|} |d|D]} || | d7}qZt||}|d krd} |t|}nd} |||j||| |jS)z?Compute the mean, median, or std over epochs and return Evoked.NcSsg|]}|dqS)ZICA) startswithrxrororprsz1BaseEpochs._compute_aggregate..zrzrzGIf data are not preloaded, can only compute mean or standard deviation.rrrrrt)r]rrrManyrHrrrrrVrrwr rrSrrwrr  complex128fillnanrsqrt_evoked_from_epoch_datar_name) rrr{Z check_ICA n_channelsr^r1funreZ data_meanrHrororpr|s\                 zBaseEpochs._compute_aggregatecCst|jdkr"tt|j}n^t|jdddf}t}|jD],\}}| dt ||t|j|fqHd |}|S)z5Give a nice string representation based on event ids.rNru %.2f × %sz + ) rrnextiterrrrrrr}rr)rrbcountcommentsrmrrororpr$s  zBaseEpochs._namec st|}t|||jd|||dd|j_|jt|j|dd}fdd|D}|t jddkrt d j d krt d S) z(Create an evoked object from epoch data.rN)rrbnaverHrZ data_or_icarocsg|]}j|qSrorirprkrorprAsz6BaseEpochs._evoked_from_epoch_data..r]z%No data channel found when averaging.rz3evoked object is empty (based on less than 1 epoch)) rr.rrrrr(rr$rrrrH)rrrrr1rHrbr]rorkrpr2s   z"BaseEpochs._evoked_from_epoch_datacCs |jdS)zChannel names.r]rrrororpr]LszBaseEpochs.ch_namesautorN)theme overview_modecCs6t|||||||||| | | | | |||||||||dS)N)rscalingsn_epochsrtitler event_colorordershowblockr) noise_cov butterflyshow_scrollbarsshow_scalebars epoch_colorsrgroup_by precompute use_openglrr)r=)rrrrrrrrrrrr)rrrrrrrrrrrrororpplotQs,zBaseEpochs.plotrlengthblackZlinearrgQ?rXcCs<t|||||||||| | | | | ||||||||||||dS)N)fminfmaxrrr* bandwidthadaptivelow_bias normalizationraxcolorxscale area_mode area_alphadBestimatern_jobsrt line_alphaspatial_colorssphererrF)r>)rrrrrr*rrrrrrrrrrrrrrrtrrrrrFrororpplot_psdes0 zBaseEpochs.plot_psdheadNNcCs4t|||||||||| | | | | ||||||||dS)N)bandsrrr*rrrrch_typecmapagg_funrr normalizecbar_fmtoutlinesaxesrrvlimrF)r?)rrrrr*rrrrrrrrrrrrrrrrrFrororpplot_psd_topomapxs0zBaseEpochs.plot_psd_topomaprRdBu_rffffff?rrwcCs(t|||||||||| | | | | ||dS)N)layoutsigmavminvmaxcolorbarrr layout_scalerrborder fig_facecolorfig_background font_colorr)rA)rrrrrrrrrrrrrrrrrororpplot_topo_images$zBaseEpochs.plot_topo_imageexistingcCsj|dkr |dkr|jrdS|j}|dkr.|j}tdd||fDrLtd||||jd|d|S)aLDrop bad epochs without retaining the epochs data. Should be used before slicing operations. .. warning:: This operation is slow since all epochs have to be read from disk. To avoid reading epochs from disk multiple times, use :meth:`mne.Epochs.load_data()`. .. note:: To constrain the time period used for estimation of signal quality, set ``epochs.reject_tmin`` and ``epochs.reject_tmax``, respectively. Parameters ---------- %(reject_drop_bad)s %(flat_drop_bad)s %(verbose)s Returns ------- epochs : instance of Epochs The epochs with bad epochs dropped. Operates in-place. Notes ----- Dropping bad epochs can be done multiple times with different ``reject`` and ``flat`` parameters. However, once an epoch is dropped, it is dropped forever, so if more lenient thresholds may subsequently be applied, `epochs.copy ` should be used. rNcss |]}t|to|dkVqdS)rNr=)rrWrororprsz&BaseEpochs.drop_bad..z/reject and flat, if strings, must be "existing"F)rfrF)rTrerfrrr rB)rrerfrFrororpdrop_bads! zBaseEpochs.drop_badrcCs t|j|S)aGCompute the channel stats based on a drop_log from Epochs. Parameters ---------- ignore : list The drop reasons to ignore. Returns ------- perc : float Total percentage of epochs dropped. See Also -------- plot_drop_log )_drop_log_statsr)rignorerororpdrop_log_statsszBaseEpochs.drop_log_stats?rr皙?c Cs(|jstdt|j|||||||dS)Nz_You cannot use plot_drop_log since bad epochs have not yet been dropped. Use epochs.drop_bad().)rwidthrr)rTrrBr)r thresholdZ n_max_plotsubjectrrrrrororprBs zBaseEpochs.plot_drop_logcCs0t|||||||||| | | | | ||||||dS)N)rrrrrrrunitsrrfigr overlay_timescombinerrlts_argsrclear)r@)rrrrrrrrrrrrrrrrrlrrrrororp plot_images$ zBaseEpochs.plot_imageUSERc Cst|}|jdkrtd|jtkr4t|d}t|dk|t|j|}|dk|t|jkB}| r||d}t d|t t t|j|}|j ||dddt|}td|t|dttt|f|S) aDrop epochs based on indices or boolean mask. .. note:: The indices refer to the current set of undropped epochs rather than the complete set of dropped and undropped epochs. They are therefore not necessarily consistent with any external indices (e.g., behavioral logs). To drop epochs based on external criteria, do not use the ``preload=True`` flag when constructing an Epochs object, and call this method before calling the :meth:`mne.Epochs.drop_bad` or :meth:`mne.Epochs.load_data` methods. Parameters ---------- indices : array of int or bool Set epochs to remove by specifying indices to remove or a boolean mask to apply (where True values get removed). Events are correspondingly modified. reason : str Reason for dropping the epochs ('ECG', 'timeout', 'blink' etc). Default: 'USER'. %(verbose)s Returns ------- epochs : instance of Epochs The epochs with indices dropped. Operates in-place. rz'indices must be a scalar or a 1-d arrayrzEpoch index %d is out of boundsF)r drop_event_idzDropped %d epoch%s: %sr)rZ atleast_1drrrsrrrrr IndexErrorrr_getitemrErrIrmaprsort) rindicesreasonrFZtry_idxZ out_of_boundsrkeeprrororprs"     zBaseEpochs.dropcCstdS)zGet a given epoch from disk.N)NotImplementedError)rrrFrororp_get_epoch_from_raw"szBaseEpochs._get_epoch_from_rawcCsF|dkst|tr|S|jp |j}|jdk rB|dkrBt|j|}|S)z/Process a raw epoch based on the delayed param.NT)r rr!r*r"rr%)rr4r*rororp_project_epoch&s  zBaseEpochs._project_epoch)rrrrFcCs|sp|jp(|jdddk o(|jdddk }t|dd} |jdkrp|jdkrp|rp|jdkrp| sptdd|_dS| ||\} } |dkrt d}n|jst d | |} t t|j| } t| }|jr|j}nt dt|jd t|jf}d |d t|jd }|jdkr |d7}t|jddrDtd|dntd|d|}|dkrxt|j|ddd}n t|j|}|dk r|rt|||}|jr|sdS|jr(|| }|dk r|dd|f}|dk r||ddt jf9}| dks| |jjkr$|d| | f}|S|j}t| D]l\}}||}|||}|jrb|}n | |}|dkrt j|t|j!t|jf|j"d}|||<q6ng}d}t#|j$}|t|j%kst&|js|j}t|j%D]"\}}|jr&|jr|j|}| |}nd}|j|}n ||}|||}| |}|jrR|n|}|j'||d\}}|st(|t)s~t&t*dd|Dst&|||||<q|+||s|jr|dkr|jst j||j,d|j,df|j"dd}|||<|d7}qt)||_$~d|_td|t||sB|jr|j-drz|j-d rz|j.|f|j,dddd!n|d|}|jr||_|j/|ddddd"|r|dk r|dd|f}|dk r||ddt jf9}| dks| |jjkr|d| | f}|SdSdS)#aHLoad all data, dropping bad epochs along the way. Parameters ---------- out : bool Return the data. Setting this to False is used to reject bad epochs without caching all the data, which saves memory. %(picks_all)s item : slice | array-like | str | list | None See docstring of get_data method. %(units)s tmin : int | float | None Start time of data to get in seconds. tmax : int | float | None End time of data to get in seconds. %(verbose)s r)rNrreject_by_annotationFz_get_data is a noop, returningTzgitem must be None in epochs.get_data() unless bads have been dropped. Consider using epochs.drop_bad().r]zfor z events and z original time pointsrz (prior to decimation)rzUsing data from preloaded Raw z ...z Loading data rror`.rrrcss|]}t|tVqdSr:r=rrororprsz'BaseEpochs._get_data..C)rsrz%d bad epochs droppedZOWNDATAZ C_CONTIGUOUS)Zrefcheck)rrZ select_data)0rrrjrerfrVrEdebugrTZ_handle_tmin_tmaxrCrZ_item_to_selectrrrrrrrrrrrr(r,rsizerEr$rar!rr]rsrrrrwr_r rrr}r r@resizer)rrfritemrrrrFZ in_boundsrstartstopselectuse_idxr1rr.Z orig_picksZ ch_factors detrend_picksr3rZ epoch_noprojZ epoch_outZgood_idxn_outrselr4Zis_good bad_tuplerororprB1s                             zBaseEpochs._get_datacCs |jrt|jddddSgSdS)NTro) with_ref_megZwith_auxr)rr&rrrororprEszBaseEpochs._detrend_pickscCs|j|||||dS)aGet all epochs as a 3D array. Parameters ---------- %(picks_all)s item : slice | array-like | str | list | None The items to get. See :meth:`mne.Epochs.__getitem__` for a description of valid options. This can be substantially faster for obtaining an ndarray than :meth:`~mne.Epochs.__getitem__` for repeated access on large Epochs objects. None (default) is an alias for ``slice(None)``. .. versionadded:: 0.20 %(units)s .. versionadded:: 0.24 tmin : int | float | None Start time of data to get in seconds. .. versionadded:: 0.24.0 tmax : int | float | None End time of data to get in seconds. .. versionadded:: 0.24.0 Returns ------- data : array of shape (n_epochs, n_channels, n_times) A view on epochs data. )rrrrr)rB)rrrrrrrororprs! zBaseEpochs.get_datac s t|dt|j|ddd}ts,td|j|dk rT||jjkrT|j||_|r tt |\}}|dkrt t f} |D]8} t | ddd| ddf|jdd| ddf<qnJ|fd d |D} t |D]$\} } | | |jdd| ddf<qnt f|_|S) aApply a function to a subset of channels. %(applyfun_summary_epochs)s Parameters ---------- %(fun_applyfun)s %(picks_all_data_noref)s %(dtype_applyfun)s %(n_jobs)s %(channel_wise_applyfun_epo)s %(verbose)s %(kwargs_fun)s Returns ------- self : instance of Epochs The epochs object with transformed data. zepochs.apply_functionroF)rrzfun needs to be a functionNrrc3s.|]&}dd|ddffVqdSr:rorZdata_inrkwargsZp_funrorpr2sz,BaseEpochs.apply_function..)rNr(rcallablerrrsr r8r7rrZapply_along_axisr$)rrrrsrZ channel_wiserFrparallelZ_funrZdata_picks_newpprrorrpapply_functions0  zBaseEpochs.apply_functioncCs|jS)z The filename.)r&rrororpr-;szBaseEpochs.filenamecsdtj}|jrdnd7}|djjf7}|d7}jdkrP|d7}nL|jdd d jd d d 7}jtjjjd ddkr|d7}|dt j f7}|dj rdnd7}|j dk rdnd7}d}fddt jd|D}tjdkr,|dddg|7}tj|krZtj|}|d|d7}jj}|dkrpdn|}d||fS) zBuild string representation.z %s events z (all good)z (good & bad)z , %g - %g secz , baseline Noffrg – r secradjust)rrZon_baseline_outside_dataz8 (baseline period was cropped after baseline correction)z, ~%sz, data%s loadedz notz, with metadata cs2g|]*\}}d|tjdddf|kfqS)z%r: %iNr)r?rrrrorprSsz'BaseEpochs.__repr__..,z z and z more events ...rEpochsz <%s | %s>)rrrTrrrr1rrrJ_sizerrrrrr __class____name__)rrZ max_eventsrZnot_shown_events class_namerorrp__repr__@s:  $ zBaseEpochs.__repr__cCsFddlm}|jdkrd}n,tdd|jD}|dd|dd}t|jtrg}t|jD]6\}}t |j ddd f|k}| |d |qfnt|jt rg}|jD]2}t |j ddd f|k}| |d |qn.rrrrz: zepochs.html.jinja)rkrr)Zhtml_templatesrrrr rrirrr?rr}rrrZ get_templaterender)rrrZ event_stringsrrr1rorororp _repr_html_^s,      zBaseEpochs._repr_html_cst|dtj|||d|jdk rN|j|jkrNtd|jd|j|_|jdk r|j|jkrtd|jd|j|_|S)aCrop a time interval from the epochs. Parameters ---------- tmin : float | None Start time of selection in seconds. tmax : float | None End time of selection in seconds. %(include_tmax)s %(verbose)s Returns ------- epochs : instance of Epochs The cropped epochs object, modified in-place. Notes ----- %(notes_tmax_included_by_default)s zModifying data of epochs)rr include_tmaxNzPreject_tmin is not in epochs time interval. Setting reject_tmin to epochs.tmin (z sec)zPreject_tmax is not in epochs time interval. Setting reject_tmax to epochs.tmax () rNsupercroprgrrErrhr)rrrrrFrrorpr!zs   zBaseEpochs.cropcCst|S)zReturn copy of Epochs instance. Returns ------- epochs : instance of Epochs A copy of the object. rrrororprszBaseEpochs.copycCsR|j}||}|jD]2\}}|dkr8||t|<n t||}||j|<q|S)zMake a deepcopy.)rrr9)r__new____dict__ridr)rZmemodictclsresultrrrororp __deepcopy__s   zBaseEpochs.__deepcopy__2GBrrrc Cs(t|ddt||d}t|}td|ddg|t|dkrRtdd}n(|d} | jd kslt | j t|}| d} |dkr|d }| d 7} | d 7} | t |j d t|j 7} ||jjd7}| tt|jd7} |jdk r|tt|j7}| d7} | d|jdk d7} tt|jd } | dt|jd7} | | 7} t|} | rz| tt| d 7} ||jjd7}| d 7} | t7} tdt| dtdt|dtdt|dt|} | r|| nd}|| }||kr4td|dt |d|dt!|d|| dd}|dks`t ||dkrt d|d|dkrtd |d!|d"t|jd#krtd$t|jd%t | d&t"#t"$| |}t%|D]<\}}|dkr||n|}|j|_t&|||||||qdS)'aSave epochs in a fif file. Parameters ---------- fname : str The name of the file, which should end with ``-epo.fif`` or ``-epo.fif.gz``. split_size : str | int Large raw files are automatically split into multiple pieces. This parameter specifies the maximum size of each piece. If the parameter is an integer, it specifies the size in Bytes. It is also possible to pass a human-readable string, e.g., 100MB. Note: Due to FIFF file limitations, the maximum split size is 2GB. .. versionadded:: 0.10.0 fmt : str Format to save data. Valid options are 'double' or 'single' for 64- or 32-bit float, or for 128- or 64-bit complex numbers respectively. Note: Data are processed with double precision. Choosing single-precision, the saved data will slightly differ due to the reduction in precision. .. versionadded:: 0.17 %(overwrite)s To overwrite original file (the same one that was loaded), data must be preloaded upon reading. This defaults to True in 0.18 but will change to False in 0.19. .. versionadded:: 0.18 %(split_naming)s .. versionadded:: 0.24 %(verbose)s Notes ----- Bad epochs will be dropped before saving the epochs to disk. rkz-epo.fifz -epo.fif.gzz_epo.fifz _epo.fif.gz)ryrtr|rrrzSaving epochs with no data)>f8zc16z.csg|] }|kqSroro)rid_idsrorprsTcs8g|]0tfddDr0fddDnqS)c3s|]}|kVqdSr:ro)rZid__rErorprsz>BaseEpochs.equalize_event_counts...cs&g|]tfddDrqS)c3s|]}|dkVqdS)rN)r)rtagrrorprszIBaseEpochs.equalize_event_counts....rrrDrHrprs  z?BaseEpochs.equalize_event_counts...rIrJrErKrprsz* not found in the epoch object's event_id.csh|] }|kqSroro)rZsub_idrErorp sz3BaseEpochs.equalize_event_counts..rz:Don't mix hierarchical and regular event_ids like in '%s'.rcs&g|]}t|jdddfqSr)rrrrrorprszHThe two sets of epochs are overlapping. Provide an orthogonal selection.csg|]}j|dfqSrrrrrrorprscSsg|]\}}||qSroro)rrrrororprsEQUALIZED_COUNTr)collections.abcr?r^r rrMrrrrTrrrr$rrO intersectionr}Z _keys_to_idx_get_drop_indicesrrrLr)rr@r~r?Zeq_indsZorig_idsZtaggingZids_r3rDerrZevents_Zdoubleseq event_timesrro)rFrrpequalize_event_counts]s^H         z BaseEpochs.equalize_event_countsc sZt}dddg} ddg} t|| }t|| }t|j|ddd}|d d |d d f} |j} | j\} }}t | j } |r| } t || ||} t t| | } t|| |} d| fd d |jDfd d |jd d dfD}dt||fdt|j|ftfddDs:tt|| |||dddgd}|S)a,Export data in tabular structure as a pandas DataFrame. Channels are converted to columns in the DataFrame. By default, additional columns "time", "epoch" (epoch number), and "condition" (epoch event description) are added, unless ``index`` is not ``None`` (in which case the columns specified in ``index`` will be used to form the DataFrame's index instead). Parameters ---------- %(picks_all)s %(index_df_epo)s Valid string values are 'time', 'epoch', and 'condition'. Defaults to ``None``. %(scalings_df)s %(copy_df)s %(long_format_df_epo)s %(time_format_df)s .. versionadded:: 0.20 %(verbose)s Returns ------- %(df_return)s timer4 conditionms timedeltarror`NcSsi|]\}}||qSrororrororprsz,BaseEpochs.to_data_frame..csg|] }|qSroror) rev_event_idrorprsz,BaseEpochs.to_data_frame..rc3s"|]}t|tdkVqdSr6r7)rZmdx)mindexrorprsz+BaseEpochs.to_data_frame..)Z default_index)rMrXr[r(rrrr rhstackrrrZrZtilerYr}rrrrepeatrrrwrW)rrrrrZ long_format time_formatrFpdZvalid_index_argsZvalid_time_formatsrrrZn_picksr^ conditionsZdfro)r^r]rp to_data_frames4        zBaseEpochs.to_data_framegradfastcCsddlm}||||dS)aCompute virtual epochs using interpolated fields. .. Warning:: Using virtual epochs 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 ------- epochs : instance of mne.EpochsArray The transformed epochs object containing only virtual channels. Notes ----- This method returns a copy and does not modify the data it operates on. It also returns an EpochsArray instance. .. versionadded:: 0.20.0 r)_as_meg_type_inst)rr{)forwardrg)rrr{rgrororpas_type%s zBaseEpochs.as_type)NrrrNNNNrNNNTrFNNNNr)r)N)N)F)N)NrzF)NF)rz)NNrrNNNNTFrNFTTNNrNNN)NNNFNFTrNNNTNFrrNTNrN)NrNNNNrrNNrrNrT)rrN)r)rrNrrrT)NrNNTNTNNNNNNNNTNNF)rN)N)TNN)NNNNN)NNNTN)NNTN)r)rFrrT)r)Nr>)NNNTFN)rerf):r __module__ __qualname____doc__rFr5rrAr#rFr r_rargryrartrr|propertyrrr]rLr=rr>rrQrr?rrArrrrBr@rrrrrBrErr r-rrr!rr(r:r=rXrdri __classcell__roror"rprTs4M  +P    H 3  =       -    1  +  # 2 '    .css"|]}|D]}t|tVq qdSr:r=)rr9rrororprWsz(drop_log must be a tuple of tuple of strr6cs.g|]&}tfdd|Dst|dkqS)c3s|]}|kVqdSr:ro)rrrrorprZsz-_drop_log_stats...r)rrrorqrorprYsz#_drop_log_stats..)r rrrMrrz)rrpercrorqrprFs rc* st}ttfddtdtttfddt|dtttfddt|dtttfddsdtddd } | | |}| |}t|t|@} | rtd d t | ~ t||d  D]P\} } | D]B} zt | gWqt k rtd | d| dYqXqqt tt }|rFtdd |~tt||}tt||d}|j|dd}dd D}|t|dddft}|j|dddf}fdd|D}fdd|D}dd|D}dd|D}d* ||||}tt|t|f}|j|||jd}d|jddd f<d}|t t||}tj|jdd||f<|}d|jdd|df<|jd!d"D]}|j}||j|j|df<|j|}|j|}|j|d#|k|d#|k@ddf} | jr"t| jd$d"D]R}!|!j|j}"|"|}#t |#d rZd n|#}#||!j}$t!|j||$fs|j||$f|#kst|$|krq.|#|j||$f<||D]}%|$t |%gkrԐq|%|krd%|%}&n d&|%}&|j||%f}'t!|'s:|%|kr"|'|#ks|%|kr:|'|#kr:q|%krn|$"|%d"d'd(#d(}(|(|j||&f<~(|#|j||%f<qq.qrfd)d D})|t|dddft|)}|j|d|)}t|t|kst|)||fS)+uFGenerate metadata from events for use with `mne.Epochs`. This function mimics the epoching process (it constructs time windows around time-locked "events of interest") and collates information about any other events that occurred within those time windows. The information is returned as a :class:`pandas.DataFrame` suitable for use as `~mne.Epochs` metadata: one row per time-locked event, and columns indicating presence/absence and latency of each ancillary event type. The function will also return a new ``events`` array and ``event_id`` dictionary that correspond to the generated metadata. Parameters ---------- events : array, shape (m, 3) The :term:`events array `. By default, the returned metadata :class:`~pandas.DataFrame` will have as many rows as the events array. To create rows for only a subset of events, pass the ``row_events`` parameter. event_id : dict A mapping from event names (keys) to event IDs (values). The event names will be incorporated as columns of the returned metadata :class:`~pandas.DataFrame`. tmin, tmax : float Start and end of the time interval for metadata generation in seconds, relative to the time-locked event of the respective time window. .. note:: If you are planning to attach the generated metadata to `~mne.Epochs` and intend to include only events that fall inside your epochs time interval, pass the same ``tmin`` and ``tmax`` values here as you use for your epochs. sfreq : float The sampling frequency of the data from which the events array was extracted. row_events : list of str | str | None Event types around which to create the time windows / for which to create **rows** in the returned metadata :class:`pandas.DataFrame`. If provided, the string(s) must be keys of ``event_id``. If ``None`` (default), rows are created for **all** event types present in ``event_id``. keep_first : str | list of str | None Specify subsets of :term:`hierarchical event descriptors` (HEDs, inspired by :footcite:`BigdelyShamloEtAl2013`) matching events of which the **first occurrence** within each time window shall be stored in addition to the original events. .. note:: There is currently no way to retain **all** occurrences of a repeated event. The ``keep_first`` parameter can be used to specify subsets of HEDs, effectively creating a new event type that is the union of all events types described by the matching HED pattern. Only the very first event of this set will be kept. For example, you might have two response events types, ``response/left`` and ``response/right``; and in trials with both responses occurring, you want to keep only the first response. In this case, you can pass ``keep_first='response'``. This will add two new columns to the metadata: ``response``, indicating at what **time** the event occurred, relative to the time-locked event; and ``first_response``, stating which **type** (``'left'`` or ``'right'``) of event occurred. To match specific subsets of HEDs describing different sets of events, pass a list of these subsets, e.g. ``keep_first=['response', 'stimulus']``. If ``None`` (default), no event aggregation will take place and no new columns will be created. .. note:: By default, this function will always retain the first instance of any event in each time window. For example, if a time window contains two ``'response'`` events, the generated ``response`` column will automatically refer to the first of the two events. In this specific case, it is therefore **not** necessary to make use of the ``keep_first`` parameter – unless you need to differentiate between two types of responses, like in the example above. keep_last : list of str | None Same as ``keep_first``, but for keeping only the **last** occurrence of matching events. The column indicating the **type** of an event ``myevent`` will be named ``last_myevent``. Returns ------- metadata : pandas.DataFrame Metadata for each row event, with the following columns: - ``event_name``, with strings indicating the name of the time-locked event ("row event") for that specific time window - one column per event type in ``event_id``, with the same name; floats indicating the latency of the event in seconds, relative to the time-locked event - if applicable, additional columns named after the ``keep_first`` and ``keep_last`` event types; floats indicating the latency of the event in seconds, relative to the time-locked event - if applicable, additional columns ``first_{event_type}`` and ``last_{event_type}`` for ``keep_first`` and ``keep_last`` event types, respetively; the values will be strings indicating which event types were matched by the provided HED patterns events : array, shape (n, 3) The events corresponding to the generated metadata, i.e. one time-locked event per row. event_id : dict The event dictionary corresponding to the new events array. This will be identical to the input dictionary unless ``row_events`` is supplied, in which case it will only contain the events provided there. Notes ----- The time window used for metadata generation need not correspond to the time window used to create the `~mne.Epochs`, to which the metadata will be attached; it may well be much shorter or longer, or not overlap at all, if desired. The can be useful, for example, to include events that occurred before or after an epoch, e.g. during the inter-trial interval. .. versionadded:: 0.23 References ---------- .. footbibliography:: r)rArBN row_events keep_first keep_lastz3event_id dictionary must contain at least one entrycSs(|dkr gSt|tr|gSt|SdSr:)r rr)rrororp _ensure_lists  z#make_metadata.._ensure_listz[The event names in keep_first and keep_last must be mutually exclusive. Specified in both: r)rtruzEvent "z", specified in z(, cannot be found in event_id dictionaryz2Present in row_events, but missing from event_id: r)sampleZprev_idr%)columnscSsi|]\}}||qSrororrororpr sz!make_metadata..rr%csg|]}|kr|qSrororcolrrorpr" sz!make_metadata..csg|]}|kr|qSrororyrrorpr# scSsg|]}d|qS)first_roryrororpr$ scSsg|]}d|qS)last_roryrororpr% s event_name)rrxrrrZRowEvent)namerwEventr{r|z//rcsi|]\}}|kr||qSroro)rr~rn)rsrorpr s)r})$rMr^rirrrrrrrrr;rOrrrZ DataFramerrrlocisinrrrr rZ itertuplesIndexr%rwrwrisnanreplacestrip)*rrrrrrsrtrurbrvZkeep_first_and_last param_namerZfirst_last_event_nameZevent_name_diffZ start_sampleZ stop_sampleZ events_dfZid_to_name_mapZkeep_first_colsZkeep_last_colsZ first_colsZ last_colsrxrrr2Zstop_idxZ row_eventZrow_idxZwindow_start_sampleZwindow_stop_sampleZevents_in_windoweventZ event_sample event_timer}Zevent_group_nameZfirst_last_colZold_timer~Zevent_id_timelockedro)rrsrp make_metadata^s$                     rcs4eZdZdZedfd d Zedd dZZS)ramEpochs extracted from a Raw instance. Parameters ---------- %(raw_epochs)s %(events_epochs)s %(event_id)s %(epochs_tmin_tmax)s %(baseline_epochs)s Defaults to ``(None, 0)``, i.e. beginning of the the data until time point zero. %(picks_all)s preload : bool %(epochs_preload)s %(reject_epochs)s %(flat)s %(proj_epochs)s %(decim)s %(epochs_reject_tmin_tmax)s %(detrend_epochs)s %(on_missing_epochs)s %(reject_by_annotation_epochs)s %(metadata_epochs)s %(event_repeated_epochs)s %(verbose)s Attributes ---------- %(info_not_none)s event_id : dict Names of conditions corresponding to event_ids. ch_names : list of string List of channel names. 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]). preload : bool Indicates whether epochs are in memory. drop_log : tuple of tuple A tuple of the same length as the event array used to initialize the Epochs 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`). filename : str The filename of the object. times : ndarray Time vector in seconds. Goes from ``tmin`` to ``tmax``. Time interval between consecutive time samples is equal to the inverse of the sampling frequency. See Also -------- mne.epochs.combine_event_ids mne.Epochs.equalize_event_counts Notes ----- When accessing data, Epochs are detrended, baseline-corrected, and decimated, then projectors are (optionally) applied. For indexing and slicing using ``epochs[...]``, see :meth:`mne.Epochs.__getitem__`. All methods for iteration over objects (using :meth:`mne.Epochs.__iter__`, :meth:`mne.Epochs.iter_evoked` or :meth:`mne.Epochs.next`) use the same internal state. If ``event_repeated`` is set to ``'merge'``, the coinciding events (duplicates) will be merged into a single event_id and assigned a new id_number as:: event_id['{event_id_1}/{event_id_2}/...'] = new_id_number For example with the event_id ``{'aud': 1, 'vis': 2}`` and the events ``[[0, 0, 1], [0, 0, 2]]``, the "merge" behavior will update both event_id and events to be: ``{'aud/vis': 3}`` and ``[[0, 0, 3]]`` respectively. There is limited support for :class:`~mne.Annotations` in the :class:`~mne.Epochs` class. Currently annotations that are present in the :class:`~mne.io.Raw` object will be preserved in the resulting :class:`~mne.Epochs` object, but: 1. It is not yet possible to add annotations to the Epochs object programmatically (via code) or interactively (through the plot window) 2. Concatenating :class:`~mne.Epochs` objects that contain annotations is not supported, and any annotations will be dropped when concatenating. 3. Annotations will be lost on save. NrrrFTrrrcszt|tstdt|j}| p$|j} ||_|jd}tt|j |d||||||||| | | | ||| ||||||j ddS)NzDThe first argument to `Epochs` must be an instance of mne.io.BaseRawr)rrr(rrerfr)rgrhr5r*r+r,rrFrr) r r+rrrr*rr rr5r)rr(rrrrrrrrerfr*r)rgrhr5r+rrrrFrrr"rorpr5 s>     zEpochs.__init__cCs|jdkrtd|jjd}|j|df}|jj}tt||jd|}||8}|t|j}|j }|dkr||jd}tt|||} | |8} |j } | dkr|jd} tt|jd| |} || } t d||f|j |||j| | |j} | S)aLoad one epoch from disk. Returns ------- data : array | str | None If string, it's details on rejection reason. If array, it's the data in the desired range (good segment) If None, it means no data is available. Nz`An error has occurred, no valid raw file found. Please report this to the mne-python developers.rrrz Getting epoch for %d-%d)rrrr first_samprrrrrgrhrErZ_check_bad_segmentrr)rrrFr event_samprrrrgZ reject_startrhrZ reject_stoprrororpr s2    zEpochs._get_epoch_from_raw)NrrrNFNNTrNNNrTNrN)NrrjrkrlrFr5rrnroror"rpr s*frcs&eZdZdZedfdd ZZS) EpochsArraya Epochs object from numpy array. Parameters ---------- data : array, shape (n_epochs, n_channels, n_times) The channels' time series for each epoch. See notes for proper units of measure. %(info_not_none)s Consider using :func:`mne.create_info` to populate this structure. events : None | array of int, shape (n_events, 3) The events typically returned by the read_events function. If some events don't match the events of interest as specified by event_id, they will be marked as 'IGNORED' in the drop log. If None (default), all event values are set to 1 and event time-samples are set to range(n_epochs). tmin : float Start time before event. If nothing provided, defaults to 0. event_id : int | list of int | dict | None The id of the event to consider. If dict, the keys can later be used to access associated events. Example: dict(auditory=1, visual=3). If int, a dict will be created with the id as string. If a list, all events with the IDs specified in the list are used. If None, all events will be used with and a dict is created with string integer names corresponding to the event id integers. %(reject_epochs)s %(flat)s reject_tmin : scalar | None Start of the time window used to reject epochs (with the default None, the window will start with tmin). reject_tmax : scalar | None End of the time window used to reject epochs (with the default None, the window will end with tmax). %(baseline_epochs)s Defaults to ``None``, i.e. no baseline correction. proj : bool | 'delayed' Apply SSP projection vectors. See :class:`mne.Epochs` for details. on_missing : str See :class:`mne.Epochs` docstring for details. metadata : instance of pandas.DataFrame | None See :class:`mne.Epochs` docstring for details. .. versionadded:: 0.16 selection : ndarray | None The selection compared to the original set of epochs. Can be None to use ``np.arange(len(events))``. .. versionadded:: 0.16 %(verbose)s See Also -------- create_info EvokedArray io.RawArray 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 EpochsArray does not set `Annotations`. If you would like to create simulated data with Annotations that are then preserved in the Epochs object, you would use `mne.io.RawArray` first and then create an `mne.Epochs` object. NrTrcs<tt|rtjntj}tj||d}|jdkr.Nrr)rrrr rrrirrrrroperatorrrr rrrpopupdate)rkZ old_event_idsZ new_event_idrZ new_event_numZold_event_numsindsrmrorrpcombine_event_ids s.    " rr>cCsptdd|Dstd|D]}|js|qdd|D}t||}t||D]\}}|j|ddqTdS) aEqualize the number of trials in multiple Epoch instances. Parameters ---------- epochs_list : list of Epochs instances The Epochs instances to equalize trial counts for. method : str If 'truncate', events will be truncated from the end of each event list. If 'mintime', timing differences between each event list will be minimized. Notes ----- This tries to make the remaining epochs occurring as close as possible in time. This method works based on the idea that if there happened to be some time-varying (like on the scale of minutes) noise characteristics during a recording, they could be compensated for (to some extent) in the equalization process. This method thus seeks to reduce any of those effects by minimizing the differences in the times of the events in the two sets of epochs. For example, if one had event times [1, 2, 3, 4, 120, 121] and the other one had [3.5, 4.5, 120.5, 121.5], it would remove events at times [1, 2] in the first epochs and not [120, 121]. Examples -------- >>> equalize_epoch_counts([epochs1, epochs2]) # doctest: +SKIP css|]}t|tVqdSr:)r rrOrororpr sz(equalize_epoch_counts..z#All inputs must be Epochs instancescSsg|]}|jdddfqSrrNrOrororpr sz)equalize_epoch_counts..rPrQN)rrrTrrTrLr) epochs_listr~rrWrrrororpequalize_epoch_counts s  rcCstdd|D}||}td|ddgt}|D]X}|dkrNt||}n&tj|jdtd}d||jdd <|t t |dq6|S) z5Get indices to drop from multiple event timing lists.cSsg|]}|jdqSrM)r rOrororpr sz%_get_drop_indices..r~r>truncaterrrFN) rargminrUr_minimize_time_diffonesr rr}rZ logical_not)rWr~Z small_idxZ small_e_timesrrmaskrororprT s rTcsddlm}tjttd}t|dkr`|dt|dkr\tt|}d||<|Stt}t t|}t dddd}|||fd |d i|}t tt|D]} |tj tj ttd|} d| d d |f<t t| d} tfd d | D} || | fd| d d d fd|} | ||}|| | }t||jddt||jdd||<d|t|<q|S)z3Find a boolean mask to minimize timing differences.r)interp1drrrFrT)rZ bounds_errorZ assume_sorted fill_valuerNcsg|] }|qSroro)rkmt_longerrorprA sz'_minimize_time_diff..)rrr)Zscipy.interpolaterrrrrrrrvrrirrQeyer r?)Z t_shorterrrrrZscoresx1rZshorter_interpr3Z keep_maskZx2Zt_keepsZ longer_interpZd1Zd2rorrpr( s<        ,rFc s^t}d} tjttd} d| tjfddDtd<t||gtjtjgddgD]\} } } | dk rX| D]\}}||| }tdkrr|}tj |d d tj |d d }| }t t| |||d}t|dkrrfd d|D}| std | ||fd } |s*dS|t|7}qrqX|sDd S|dkrRdSd|fSdS)zTest if data segment e is good according to reject and flat. If full_report=True, it will give True/False as well as a list of all offending channels. Frrcsg|] }|kqSroro)rc)r[rorprW sz_is_good..rrfNrrrcsg|]}|qSroro)ri)r]rrorprf sz' Rejecting %s epoch based on %s : %sTrorY)rrrrrr rLZgreaterlessrrRrrr logical_andrEr)rr]Zchannel_type_idxrerfrZr[rFrZ has_printedZ checkableZreflfrormZthreshr~Ze_idxZdeltasZ checkable_idxZ idx_deltasZ bad_namesro)r]rr[rpr\L sL&   r\c(s |}t||dd\}t||}t||\}}d}t|tj} t| dkr| ddD]2} | j} | j} | tj krZt || j }t |}qqZt|tj } ~t| dkrtdt|tj}t|dkrt|tj}t|dkrt|d}t|dkrtd|d}d}d}d \}}d}d}d}d}i}t|d D]}|d|j} |d|j} | tjkr|t || }t|j }q6| tjkrt || }t|j }q6| tjkr|| dt|}| |_|jd A|_n| tjd fkrt || }t|j }n| tjd fkr t || }t|j }n| tjkrDt || }t|j }nz| tjkr~t || }|j }t |}t!dd|D}n@| tj"krt || }t |j }n| tj#kr6t || }|j }q6|dk s|dk r||f}||d}t$%dt$%dd|dd|dfddk rBt$%dtd|dkrTtdtd|f}t|t&|}|jtj'krtj(} d}!nL|jtj)krtj(} d}!n2|jtj*krtj+} d}!n|jtj,krtj+} d}!t-|!j.}"|"dkst/|j0|"d|"}#|#|ks"td|#|ftfd d!td"Dtj(}$|rht ||jj 1| }||$9}|d}%|d}&|dkrd#d$t2|ddd%fDn|}'|dkrt3t|}|dkrd&t|}W5QRX||||'||%|&|||||$||!||fS)'zRead a single FIF file.T)Z clean_badsNr directoryzCould not find processed datazzCould not find epochs datarZnenti@i0i1css|]}t|VqdSr:)rrrororpr sz'_read_one_epoch_file..rz Found the data of interest:z t = %10.2f ... %10.2f msrcompsz. %d CTF compensation matrices availablezEpochs data not foundr]>f4r+>c8r,)r0r4r/r/z.Incorrect number of samples (%d instead of %d)cs2g|]*}d|dd|ddgqS)rrrr)rrrrorpr sz(_read_one_epoch_file..rcSsi|]}t||qSrorrOrororpr sz(_read_one_epoch_file..r)ro)4rrcr9rr rrrHposrrrrQrrrrrrrrseekrrNrrrrrr rrloadsrrrrErprodZ FIFFT_FLOATrxZ FIFFT_DOUBLEZFIFFT_COMPLEX_FLOATrZFIFFT_COMPLEX_DOUBLErsitemsizerwrr rr)(rtreerrZmeasrrZmappingsrZ metadata_treeddrHr processedZ epochs_nodeZ my_epochsrdata_tagrrrrrrrlrrGrrZn_samp epoch_shapeZ size_expecteddatatyper|Z fmt_itemsizeZ size_actualcalsrrrrorrp_read_one_epoch_filey s                                           $  rcCst||||S)aFRead epochs from a fif file. Parameters ---------- %(fname_epochs)s %(proj_epochs)s preload : bool If True, read all epochs from disk immediately. If ``False``, epochs will be read on demand. %(verbose)s Returns ------- epochs : instance of Epochs The epochs. ) EpochsFIF)ryr*rrFrororp read_epochs src@s eZdZdZddZddZdS) _RawContainerz Helper for a raw data container.cCs.||_||_||_||_||_d|_||_dS)NF)rr event_sampsrrr*r|)rrrrrrr|rororpr5) sz_RawContainer.__init__cCs|jdSr:)rcloserrororp__del__3 sz_RawContainer.__del__N)rrjrkrlr5rrorororpr& s rcs4eZdZdZedfdd Zed ddZZS) ra_Epochs read from disk. Parameters ---------- %(fname_epochs)s %(proj_epochs)s preload : bool If True, read all epochs from disk immediately. If False, epochs will be read on demand. %(verbose)s See Also -------- mne.Epochs mne.epochs.combine_event_ids mne.Epochs.equalize_event_counts TNc(st|r&t|dddt|ddd}n |s2td|g}t}t}|D]0}t|}td|t||d \} } } t | || } t | | |\} }}}}}}}}}}}}}}}}|ddd fd k r| }t d td t|d |ddd f<t| |||||d|d ||dd|d}||_d|_|||sh|tt|d ||ddd f |||| dk rH|| qH|dk}t||dd\ } }}}}}}}}}}tt|ddd ft|krtdt|t|d kstt|t|} t| t|d | }!t|}t|!dd|!d dD]P\}"}#||"|#}$tt||$D]*\}%\}&}'|&dkrX|'dkrX|'||%<qXq6t|d| }tt|j| |||||fd||dd |||||||d |||_d|_d|_ ||_!dS)Nrkr*)ryZfiletypeZendingsTread)ryZ must_existrtz+preload must be used with file-like objectszReading %s ...rrz[Incorrect events detected on disk, setting event numbers to consecutive increasing integersrrF)rrr+rrr*rFr) with_data add_offsetz"Event time samples were not uniquerr) rr(r*r,r+rrr-rrFrr)"r`rDrCrrr!rErrrrrrrHrrrrrrr}r_concatenate_epochsrrrwrLr$rr rr5rTZ_unsafe_annot_add)(rryr*rrFfnamesZep_listr(Z fname_reprr_rrrrrrrrrrrrrrrlr|rrr4Zunsafe_annot_addstepoffsetsi1i2Z other_lograrr"rorpr5K s       $"  zEpochsFIF.__init__c Cs|j|df}|jD]Z}t|j|kd}t|dkr|j}|d}t|jt |j }||d}qxqt d|j |jj|d|dkrd}n|dkrd}n|}t|j ||} ||kr| |} | tj} n | tj} |j| _| |j9} | S) zLoad one epoch from disk.rrr/zFCorrect epoch could not be found, please contact mne-python developersrrr,r+)rrrrrrr|rrrsrrrrrrZ frombufferrviewr rrxr r) rrrFrr(r|roffsetZread_fmtrrororpr s0       zEpochsFIF._get_epoch_from_raw)TTN)Nrroror"rpr7 s]rcCsD|jstdt|}|}t|j}t|d||}||}|S)zCompute epochs selected by bootstrapping. Parameters ---------- epochs : Epochs instance epochs data to be bootstrapped %(random_state)s Returns ------- epochs : Epochs instance The bootstrap samples zhModifying data of epochs is only supported when preloading is used. Use preload=True in the constructor.r)rrrGrrrr<)rkZ random_staterngZepochs_bootstrapr1rrororp bootstrap s rcCs|tdd|Ddkrtdtdd|Ddkr.rz'Epochs with unequal values for event_idcSsh|] }|jqSro)rrrororprL sz#Epochs with unequal values for tmincSsh|] }|jqSro)rrrororprL sz#Epochs with unequal values for tmaxcSsh|] }|jqSro)rrrororprL sz'Epochs with unequal values for baselineN)rr)rrororp_check_merge_epochs src s.tdd|Dstdtdd|D}dd|D}t||D] }t|t|dkrFtdqFtj|d d }t|d |jd krd }t||dj tfd d|d dD}|stdt dd|D}|d }||_ d|_ |_ d|_d|_||_t|j d|d\|_|_ |S)aLConcatenate channels, info and data from two Epochs objects. Parameters ---------- epochs_list : list of Epochs Epochs object to concatenate. %(verbose)s Defaults to True if any of the input epochs have verbose=True. Returns ------- epochs : instance of Epochs Concatenated epochs. css|] }|jVqdSr:rrOrororpr sz&add_channels_epochs..zAll epochs must be preloaded.cSsg|] }|jqSrorrrororpr sz'add_channels_epochs..cSsg|] }|jqSro)rrrororpr srz%all epochs must be of the same lengthrrrz.zN%d of %d epochs instances have metadata, either all or none must have metadata)strictrrr)2r rrrMrNr$rrjrrrHrr'rr}rrrrrrrrrrrrrrrallcloserrrrSrSrrrrr?rMconcatrwZcumsumrLrrr]rs)"rrrrZwarnedeirkrfrrrrrrrrrrrshiftZ events_offsetZevents_overflowr3Z common_keysrmr.ZevsZ max_timestampZn_haverbrrrZ this_datarororpr0 s      "                $ & rc CsFtdd| Dd} t|||||||| | dd||d } | | S)z3Finish concatenation for epochs not read from disk.cSsg|]}t|dkqSrMr7rorororpr sz"_finish_concat..rFr)rrrr*r+rr)rrrr) rrrrrrrrrrrrfrororp_finish_concat s$r)rrFcCstt|||dS)aConcatenate a list of `~mne.Epochs` into one `~mne.Epochs` object. .. note:: Unlike `~mne.concatenate_raws`, this function does **not** modify any of the input data. Parameters ---------- epochs_list : list List of `~mne.Epochs` instances to concatenate (in that order). add_offset : bool If True, a fixed offset is added to the event times from different Epochs sets, such that they are easy to distinguish after the concatenation. If False, the event times are unaltered during the concatenation. %(on_mismatch_info)s %(verbose)s .. versionadded:: 0.24 Returns ------- epochs : instance of Epochs The result of the concatenation. Notes ----- .. versionadded:: 0.9.0 )rr)rr)rrrrFrororpconcatenate_epochs srrr4rY@c ?Cszddlm} m}m}m}m}m}m}m}m }m }|dkr@t dddl m }t|tsht dt|f|dkrz|jdn|}t|}t|tjr||}|\}}}~||t||jd}|||jd }td t|jt|jddd ft|jddd fstd |j}||||| \}}}} }!||||| |\}"} t|jt|j}#}$tt |#|}%t!|#|$f}&d }'t"||| d d }(||| d})||(| d}*||d}+|||g\},}-d}.d}/|"| }0t#||d |d}1||},t$|D]z\}2}3|j|j%dd f|}4t&||4kd }5t|5d krL|dd}6n6|5d}5t't(||5||5gj)gddddggg}6d*dd|6dddfdD}7|/dkst+|/|6std|2d|7fd}8|6}/ntd|2dfd }8|3}3|8s8| |1|*|6|0d}9tj,-|9ddd|,f}:|9|:9}9|.|97}.|3|rPt.dn||:9<|&|37}&|+|:7}+|'d7}'q~(d};|'d kr|&/tj0n|&||+<|&|%|r|+n|'<|.|+}.d |1d<| |1|)|}<||1d<|<|"}<||.d d|,}=|=|0j)9}=t1|<|=};t1|;|&|| |&|<||d<|j2|&|||'d|j3d }>||>td!|'f| rv|>|;fS|>S)"uAverage data using Maxwell filtering, transforming using head positions. Parameters ---------- epochs : instance of Epochs The epochs to operate on. %(head_pos_maxwell)s orig_sfreq : float | None The original sample frequency of the data (that matches the event sample numbers in ``epochs.events``). Can be ``None`` if data have not been decimated or resampled. %(picks_all_data)s %(origin_maxwell)s weight_all : bool If True, all channels are weighted by the SSS basis weights. If False, only MEG channels are weighted, other channels receive uniform weight per epoch. %(int_order_maxwell)s %(ext_order_maxwell)s %(destination_maxwell_dest)s %(ignore_ref_maxwell)s return_mapping : bool If True, return the mapping matrix. %(mag_scale_maxwell)s .. versionadded:: 0.13 %(verbose)s Returns ------- evoked : instance of Evoked The averaged epochs. See Also -------- mne.preprocessing.maxwell_filter mne.chpi.read_head_pos Notes ----- The Maxwell filtering version of this algorithm is described in [1]_, in section V.B "Virtual signals and movement correction", equations 40-44. For additional validation, see [2]_. Regularization has not been added because in testing it appears to decrease dipole localization accuracy relative to using all components. Fine calibration and cross-talk cancellation, however, could be added to this algorithm based on user demand. .. versionadded:: 0.11 References ---------- .. [1] Taulu S. and Kajola M. "Presentation of electromagnetic multichannel data: The signal space separation method," Journal of Applied Physics, vol. 97, pp. 124905 1-10, 2005. .. [2] Wehner DT, Hämäläinen MS, Mody M, Ahlfors SP. "Head movements of children in MEG: Quantification, effects on source estimation, and compensation. NeuroImage 40:541–550, 2008. r) _trans_sss_basis_reset_meg_bads _check_usable_col_norm_pinv_get_n_moments_get_mf_picks_fix_mags_prep_mf_coils_check_destination_remove_meg_projs_get_coil_scaleNz,head_pos must be provided and cannot be None)head_pos_to_trans_rot_tz,epochs must be an instance of Epochs, not %srrTz&Aligning and averaging up to %s epochsrz0Epochs must have monotonically increasing events)r) ignore_refr) int_order ext_orderZ head_frameoriginZ dev_head_ttransrrrcss|]}d|VqdS)z%0.1fNro)rtrrororprXsz$average_movements..rrz0 Processing epoch %s (device location: %s mm)Fz/ Processing epoch %s (device location: same)) coil_scalerrt)r1rHrbz%Created Evoked dataset from %s epochs)4Zpreprocessing.maxwellrrrrrrrrrrrMZchpirr rrNrrrZndarrayr-rErrrrrrr]rrrrwr%rir$rrZvstackr_rrrZlinalgZnormrCrrr%rr)?rkZhead_posZ orig_sfreqrrZ weight_allrrZ destinationrZreturn_mappingZ mag_scalerFrrrrrrrrrrrZtrnZrotroZ recon_transZinfo_toZ meg_picksZ mag_picksZ grad_picksZ good_maskrrrr^Z other_picksrrZ info_fromZall_coils_reconZ all_coilsZw_sumZn_inrZS_decompZ last_transZdecomp_coil_scaleexprr4rrrZloc_strZreuseSweightmappingZS_reconZpS_averlrororpaverage_movements sA0    0     $       rrrc Cs@t||||d}d|jd} t|||gd|| d||||d S)aDivide continuous raw data into equal-sized consecutive epochs. Parameters ---------- raw : instance of Raw Raw data to divide into segments. duration : float Duration of each epoch in seconds. Defaults to 1. %(preload)s %(reject_by_annotation_epochs)s .. versionadded:: 0.21.0 %(proj_epochs)s .. versionadded:: 0.22.0 overlap : float The overlap between epochs, in seconds. Must be ``0 <= overlap < duration``. Default is 0, i.e., no overlap. .. versionadded:: 0.23.0 id : int The id to use (default 1). .. versionadded:: 0.24.0 %(verbose)s Returns ------- epochs : instance of Epochs Segmented data. Notes ----- .. versionadded:: 0.20 )r%durationoverlaprrrN)rrrrrrr*rF)r:rr) r(rrrr*rr%rFrdeltarororpmake_fixed_length_epochss'r)r)NNN)T)r>)TTN)N)N)TT)T) NNNrTr4rNFFrN)rFTTrrN)rl functoolsr collectionsrrrrros.pathpathrunumpyrZio.utilsrZio.writerr r r r r rrrrrrrrZ io.meas_inforrrrrZio.openrrZio.treerZio.tagrrZ io.constantsr Z io.fiff.rawr!Zio.pickr"r#r$r%r&r'r(Zio.projr)r*Zio.baser+r,Zbemr-rlr.rr/r0r1Zchannels.channelsr2r3r4filterr5r6r7r r8rr9r:r;fixesr<Zvizr=r>r?r@rArButilsrCrDrErFrGrHrIrJrKrLrMrNrOrPrQrRrSrTrUrVrWrXrYrZr[r\r]r^r_r`Z utils.docsrarrbrcrdrqrrxrrrrrrrrrrrTrr\rrobjectrrrrrrrrrrrorororps     @   $       "hE1~  13r ; )$ ,    2 } # 6