U f{j @sdZddlmZddlmZddlZddlm Z m Z m Z m Z m Z mZmZmZmZmZmZddlmZddlmZddlmZdd lmZdd lmZmZmZm Z dd l!m"Z"ed9d dZ#d:ddZ$ddZ%e d;ddZ&e d ddddZ'ddd Z*d!d"Z+e d?d$d%Z,d&d'Z-d@d)d*Z.ed+d,Z/edAd/d0Z0d1d2Z1eGd3d4d4e2Z3d5d6d7d8Z4dS)Bz$IO with fif files containing events.N)Sequence) check_fnameloggerverbose_get_stim_channelwarn_validate_type _check_optionfill_doc _check_fname _on_missing_check_on_missing)FIFF) dir_tree_find)read_tag) fiff_open) write_int start_blockstart_and_end_file end_block) pick_channelsFcCs|dk rzt|ts|g}tjt|td}|D]@}t||dddf|k}|r.t||dddf|k}q.||}n|dk rt|ts|g}tjt|td}|D]@}t||dddf|k}|rt||dddf|k}q||}n t |}t|dkrt d|S)aSelect some :term:`events`. Parameters ---------- %(events)s include : int | list | None A event id to include or a list of them. If None all events are included. exclude : int | list | None A event id to exclude or a list of them. If None no event is excluded. If include is not None the exclude parameter is ignored. step : bool If True (default is False), events have a step format according to the argument output='step' in the function find_events(). In this case, the two last columns are considered in inclusion/ exclusion criteria. Returns ------- events : array, shape (n_events, 3) The list of events. NdtyperrzNo events found) isinstancelistnpzeroslenbool logical_orones logical_andcopy RuntimeError)eventsincludeexcludestepmasker,H/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/event.py pick_eventss,     r.c Csr|dkr |}d|}t||} t||} g} g} |tD]} | d|krB| d| }| d| }||dddf|k|dddf|k@|dddf|k@}|r| | d|ddg7} || d<| | g7} qB|dk rB|| d<| | g7} | tjqBt| } tjddtj | dd} W5QRX| rL| |9} n tg} | rd| ntg| fS) aDefine new events by co-occurrence of existing events. This function can be used to evaluate events depending on the temporal lag to another event. For example, this can be used to analyze evoked responses which were followed by a button press within a defined time window. Parameters ---------- events : ndarray Array as returned by mne.find_events. reference_id : int The reference event. The event defining the epoch of interest. target_id : int The target event. The event co-occurring in within a certain time window around the reference event. sfreq : float The sampling frequency of the data. tmin : float The lower limit in seconds from the target event. tmax : float The upper limit border in seconds from the target event. new_id : int New ID for the new event. fill_na : int | None Fill event to be inserted if target is not available within the time window specified. If None, the 'null' events will be dropped. Returns ------- new_events : ndarray The new defined events. lag : ndarray Time lag between reference and target in milliseconds. Ng@@rrignore)invalidZf8r) intr$astypeanyappendrnanarrayZerrstateabs)r&Z reference_idZ target_idsfreqtmintmaxnew_idZfill_naZtsampleZiminZimaxZ new_eventsZlageventlowerupperresr,r,r-define_target_eventsNs>%           r@c CsRt|tj}t|dkr(|td|d}d}d}|dD]4}|j}|j}|tjkr@t ||}|j }d|_ qvq@|dkrtd|dD]}|j}|j}|tj krt ||}|j }dd| d D} d d | D}qJq|tjkrt ||}|j }|d  d dd}t|t|ks.tdd t||D}qJq||fS)z Aux function.rzCould not find event dataN directory)zCould not find any eventscSs,g|]$}dd|dddddDqS)cSsg|]}|dddqS)NrBr,).0sr,r,r- sz/_read_events_fif...NrB:r)split)rDmr,r,r-rFsz$_read_events_fif..;cSsi|]\}}|t|qSr,)r1)rDvkr,r,r- sz$_read_events_fif..zlatin-1rBcSsi|]\}}||dqSrr,rDrLrKr,r,r-rMs)rrFIFFB_MNE_EVENTSrclose ValueErrorkindposFIFF_MNE_EVENT_LISTrdatashapeZFIFF_DESCRIPTIONrHZFIFF_MNE_EVENT_COMMENTStobytesdecodeAssertionErrorzip) fidtreer& event_listevent_iddrTrUtagZm_r,r,r-_read_events_fifsH          rcandc Cst|ddt|d}|dks.|dkrft|\}} } |} t| | \} } W5QRX| t} ntj |tj dt}t |dkrt d|j dkr|tjd d f}t |dd krdd d g}n$t |dd krddd g}nt d |d d |f} |d k r8| jddkr8| ddkr8| dd } tdd } t| ||} | jd}|d k rt| ||} | jd}||krtd|||| }|r| d krtd|| f}|S)a Read :term:`events` from fif or text file. See :ref:`tut-events-vs-annotations` and :ref:`tut-event-arrays` for more information about events. Parameters ---------- filename : str Name of the input file. If the extension is .fif, events are read assuming the file is in FIF format, otherwise (e.g., .eve, .lst, .txt) events are read as coming from text. Note that new format event files do not contain the "time" column (used to be the second column). include : int | list | None A event id to include or a list of them. If None all events are included. exclude : int | list | None A event id to exclude or a list of them. If None no event is excluded. If include is not None the exclude parameter is ignored. mask : int | None The value of the digital mask to apply to the stim channel values. If None (default), no masking is performed. mask_type : 'and' | 'not_and' The type of operation between the mask and the trigger. Choose 'and' (default) for MNE-C masking behavior. .. versionadded:: 0.13 return_event_id : bool If True, ``event_id`` will be returned. This is only possible for ``-annot.fif`` files produced with MNE-C ``mne_browse_raw``. .. versionadded:: 0.20 %(verbose)s Returns ------- %(events)s event_id : dict Dictionary of ``{str: int}`` mappings of event IDs. See Also -------- find_events, write_events Notes ----- This function will discard the offset line (i.e., first line with zero event number) if it is present in a text file. For more information on ``mask`` and ``mask_type``, see :func:`mne.find_events`. r&) .eve-eve.fif -eve.fif.gz-eve.lst-eve.txt_eve.fif _eve.fif.gz_eve.lst_eve.txtz -annot.fifr.fif.gzrrzNo text lines foundNrrCz,Unknown number of columns in event text file)rrz/first row of event file discarded (zero-valued)z{} of {} events maskedzNo event_id found in the file)ropsplitextr=rrcr2r1rZloadtxtZfloat64rrSndimnewaxisrXrr. _mask_trigsformatr%)filenamer'r(r* mask_typeZreturn_event_idrextr]r^_fr_r`linesZgoodsZ unmasked_lenZ masked_lenoutr,r,r- read_eventssN9                r~) overwriterc Cst||d}t|ddt|d}|dkrpt|.}t|tjt |tj |j t |tjW5QRXn2t |d"}|D]}|dt|qW5QRXdS) aWrite :term:`events` to file. Parameters ---------- filename : str Name of the output file. If the extension is .fif, events are written in binary FIF format, otherwise (e.g., .eve, .lst, .txt) events are written as plain text. Note that new format event files do not contain the "time" column (used to be the second column). %(events)s %(overwrite)s %(verbose)s See Also -------- read_events )rr&) rerfrgrhrirjrkrlrmr)rnrowz %6d %6d %3d N)r rrqrrr=rrrrQrrVTropenwritetuple)rwr&rrryr]r{r+r,r,r- write_events/s     rcCstj|dddk}ttj|ddd}t|dkrDtjdddS|d|f}|d7}|d|f}||7}tj|||f} |dk r| d} | |krtj| dd|| gdd} |dk r| d} | |krt|d|} tj| | | |ggdd} |dkrt| dddf} | t |k}t |rt|d} t |}|dkrl| | df| | ddf<t|d }n&| | dd f| | d f<t|dd }| dddf| ddd fk}t ||}| |} | S) NrZaxisrrrCint32r)rr)rBrTr) rdiffwhereallremptyc_insertr4r7r3Z logical_notr#)rW first_samp pad_startpad_stopmergechangedidxZpre_stepZ post_stepZstepsrKZlast_idxrrZkeepis_stepr,r,r-_find_stim_stepsUsB          rcCst||j}t|jd|d}t|dkr2td||ddf\}}t|dkrftdt|}| tj }t ||j |||dS)a\Find all steps in data from a stim channel. Parameters ---------- raw : Raw object The raw data. pad_start : None | int Values to assume outside of the stim channel (e.g., if pad_start=0 and the stim channel starts with value 5, an event of [0, 0, 5] will be inserted at the beginning). With None, no steps will be inserted. pad_stop : None | int Values to assume outside of the stim channel, see ``pad_start``. merge : int Merge steps occurring in neighboring samples. The integer value indicates over how many samples events should be merged, and the sign indicates in which direction they should be merged (negative means towards the earlier event, positive towards the later event). stim_channel : None | str | list of str Name of the stim channel or all the stim channels affected by the trigger. If None, the config variables 'MNE_STIM_CHANNEL', 'MNE_STIM_CHANNEL_1', 'MNE_STIM_CHANNEL_2', etc. are read. If these are not found, it will default to 'STI101' or 'STI 014', whichever is present. Returns ------- steps : array, shape = (n_samples, 3) For each step in the stim channel the values [sample, v_from, v_to]. The first column contains the event time in samples (the first sample with the new value). The second column contains the stim channel value before the step, and the third column contains value after the step. See Also -------- find_events : More sophisticated options for finding events in a Raw file. ch_namesr'r0No stim channel found to extract event triggers.Nz?Trigger channel contains negative values, using absolute value.)rrr) rinforrrSrr3rr7r2int64rr)rawrrr stim_channelpicksrWrzr,r,r-find_stim_stepss'     ronset increasingc Cs|jddkst|dkr8t|d} | |kr<| d8} nd} |tj}|r`|tjtj}|dkr~tdt |}t ||d| d} |d} | dkr| rtj | d|d| gdd} nt d| t| ||} |dkr8| d d d f| d d dfk} tt| | d d d fdk| d d dfdk}nX|rh| d d d fdk} | d d dfdk}n(| d d dfdk} | d d d fdk}t| d}t|d}t|dkst|dkrtjd d d S|d|dkrt dt|d}|d|dkr&t dt|d}|dkr:| |} n|dkrZt||}| |} np|dkr| |d f}| |} | d d d f| d d df<|| d d d f<| d d dfd8<n td|t dt| t dt| d d d f| S)zHelp find events.rrzTrigger channel contains negative values, using absolute value. If data were acquired on a Neuromag system with STI016 active, consider using uint_cast=True to work around an acquisition bug)rr)rrrzkTrigger channel has a non-zero initial value of {} (consider using initial_event=True to detect this event)rNrrrrz6Removing orphaned offset at the beginning of the file.rBz/Removing orphaned onset at the end of the file.rr)offsetzInvalid output parameter %rz%s events foundz Event IDs: %s)rXr[r1r2rrZuint16minrr7rrrrrvrur#r!rrrdeleteZunion1drSunique)rWrroutput consecutive min_samplesr* uint_castrx initial_eventrr& initial_valueZonsetsoffsetsZ onset_idxZ offset_idxrr`r,r,r- _find_eventssz                     rcCsht|ttj|jj|jdf}tj|dd\}}t|t|}|dkr`t d|||S)z+Uniquify events (ie remove duplicated rows.rT)Z return_indexrzhSome events are duplicated in your different stim channels. %d events were ignored during deduplication.) rZascontiguousarrayviewrvoiditemsizerXrrr)r&r+rzrZn_dupesr,r,r-_find_unique_events s rrc  Cs4||jd} zt||j}Wn.tk rLt|jdkrFtdnYnXt|jd|d} t| dkrttd|| ddf\} }g}| D]n}t|tjddf|j | ||| |||| d }t t |dddf|k}|dkrtd || |qtj |dd }t|}|t|dddf}|S) a+Find :term:`events` from raw file. See :ref:`tut-events-vs-annotations` and :ref:`tut-event-arrays` for more information about events. Parameters ---------- raw : Raw object The raw data. stim_channel : None | str | list of str Name of the stim channel or all the stim channels affected by triggers. If None, the config variables 'MNE_STIM_CHANNEL', 'MNE_STIM_CHANNEL_1', 'MNE_STIM_CHANNEL_2', etc. are read. If these are not found, it will fall back to 'STI 014' if present, then fall back to the first channel of type 'stim', if present. If multiple channels are provided then the returned events are the union of all the events extracted from individual stim channels. output : 'onset' | 'offset' | 'step' Whether to report when events start, when events end, or both. consecutive : bool | 'increasing' If True, consider instances where the value of the events channel changes without first returning to zero as multiple events. If False, report only instances where the value of the events channel changes from/to zero. If 'increasing', report adjacent events only when the second event code is greater than the first. min_duration : float The minimum duration of a change in the events channel required to consider it as an event (in seconds). shortest_event : int Minimum number of samples an event must last (default is 2). If the duration is less than this an exception will be raised. mask : int | None The value of the digital mask to apply to the stim channel values. If None (default), no masking is performed. uint_cast : bool If True (default False), do a cast to ``uint16`` on the channel data. This can be used to fix a bug with STI101 and STI014 in Neuromag acquisition setups that use channel STI016 (channel 16 turns data into e.g. -32768), similar to ``mne_fix_stim14 --32`` in MNE-C. .. versionadded:: 0.12 mask_type : 'and' | 'not_and' The type of operation between the mask and the trigger. Choose 'and' (default) for MNE-C masking behavior. .. versionadded:: 0.13 initial_event : bool If True (default False), an event is created if the stim channel has a value different from 0 as its first sample. This is useful if an event at t=0s is present. .. versionadded:: 0.16 %(verbose)s Returns ------- %(events)s See Also -------- find_stim_steps : Find all the steps in the stim channel. read_events : Read events from disk. write_events : Write events to disk. Notes ----- .. warning:: If you are working with downsampled data, events computed before decimation are no longer valid. Please recompute your events after decimation, but note this reduces the precision of event timing. Examples -------- Consider data with a stim channel that looks like:: [0, 32, 32, 33, 32, 0] By default, find_events returns all samples at which the value of the stim channel increases:: >>> print(find_events(raw)) # doctest: +SKIP [[ 1 0 32] [ 3 32 33]] If consecutive is False, find_events only returns the samples at which the stim channel changes from zero to a non-zero value:: >>> print(find_events(raw, consecutive=False)) # doctest: +SKIP [[ 1 0 32]] If consecutive is True, find_events returns samples at which the event changes, regardless of whether it first returns to zero:: >>> print(find_events(raw, consecutive=True)) # doctest: +SKIP [[ 1 0 32] [ 3 32 33] [ 4 33 32]] If output is 'offset', find_events returns the last sample of each event instead of the first one:: >>> print(find_events(raw, consecutive=True, # doctest: +SKIP ... output='offset')) [[ 2 33 32] [ 3 32 33] [ 4 0 32]] If output is 'step', find_events returns the samples at which an event starts or ends:: >>> print(find_events(raw, consecutive=True, # doctest: +SKIP ... output='step')) [[ 1 0 32] [ 3 32 33] [ 4 33 32] [ 5 32 0]] To ignore spurious events, it is also possible to specify a minimum event duration. Assuming our events channel has a sample rate of 1000 Hz:: >>> print(find_events(raw, consecutive=True, # doctest: +SKIP ... min_duration=0.002)) [[ 1 0 32]] For the digital mask, if mask_type is set to 'and' it will take the binary representation of the digital mask, e.g. 5 -> '00000101', and will allow the values to pass where mask is one, e.g.:: 7 '0000111' <- trigger value 37 '0100101' <- mask ---------------- 5 '0000101' For the digital mask, if mask_type is set to 'not_and' it will take the binary representation of the digital mask, e.g. 5 -> '00000101', and will block the values where mask is one, e.g.:: 7 '0000111' <- trigger value 37 '0100101' <- mask ---------------- 2 '0000010' r8rzNo stim channels found, but the raw object has annotations. Consider using mne.events_from_annotations to convert these to events.rrrN)rrrrr*rrxrzYou have %i events shorter than the shortest_event. These are very unusual and you may want to set min_duration to a larger value e.g. x / raw.info['sfreq']. Where x = 1 sample shorter than the shortest event length.r)rrrSr annotationsrrrrtrsumrr4 concatenaterZargsort)rrrrZ min_durationshortest_eventr*rrxrrrrrWrzZ events_listrar&Zn_short_eventsr,r,r- find_eventssD    rcCstd|ddg|dk r&t|dddt|}|dkr>|S|dk r|dkrZt|}n|dkrntd |t|ddd df||ddd df<||ddd f|ddd fk}|S) zMask digital trigger values.rxZnot_andrdNr1r*z int or Nonerz@'mask_type' should be either 'and' or 'not_and', instead of '%s'rr)r r rr$rZ bitwise_notrS bitwise_and)r&r*rxn_eventsr,r,r-rus  ,$ruTc Cst|}|}g}dD]B}|D]8}|dd|f|k}||||f<|t|dq"q|stt|}tj|||fdd}|t|jddd}|S)aMerge a set of :term:`events`. Parameters ---------- events : array, shape (n_events_in, 3) Events. ids : array of int The ids of events to merge. new_id : int The new id. replace_events : bool If True (default), old event ids are replaced. Otherwise, new events will be added to the old event list. Returns ------- new_events : array, shape (n_events_out, 3) The new events. Notes ----- Rather than merging events you can use hierarchical event_id in Epochs. For example, here:: >>> event_id = {'auditory/left': 1, 'auditory/right': 2} And the condition 'auditory' would correspond to either 1 or 2. Examples -------- Here is quick example of the behavior:: >>> events = [[134, 0, 1], [341, 0, 2], [502, 0, 3]] >>> merge_events(events, [1, 2], 12, replace_events=True) array([[134, 0, 12], [341, 0, 12], [502, 0, 3]]) >>> merge_events(events, [1, 2], 12, replace_events=False) array([[134, 0, 1], [134, 0, 12], [341, 0, 2], [341, 0, 12], [502, 0, 3]]) )rrNrrrB) rZasarrayr$r4rrrZlexsortr) r&idsr;Zreplace_events events_outZ idx_touchedcolir*r,r,r- merge_eventss-  rcCsR|}|dkrtd}nt|dddf|}||dft||7<|S)aShift a set of :term:`events`. Parameters ---------- %(events)s ids : ndarray of int | None The ids of events to shift. tshift : float Time-shift event. Use positive value tshift for forward shifting the event and negative value for backward shift. sfreq : float The sampling frequency of the data. Returns ------- new_events : array of int, shape (n_new_events, 3) The new events. Nrr)r$slicerZin1dr1)r&rZtshiftr8r*r,r,r-shift_time_events.s  r?c Csnddlm}t||dt|tdt|ddt|ddt|t|}}d|krb|kstntd ||f|j|d d d}|d k r|j|d d d}n |jd}|r||j}t ||j|jdg}nt |t |j g}|tt |jd |8}t ||d|jd ||t}t |} | dkrBtdt j|t j| td|t j| tdf} | S)aMake a set of :term:`events` separated by a fixed duration. Parameters ---------- raw : instance of Raw A raw object to use the data from. id : int The id to use (default 1). start : float Time of first event (in seconds). stop : float | None Maximum time of last event (in seconds). If None, events extend to the end of the recording. duration : float The duration to separate events by (in seconds). first_samp : bool If True (default), times will have :term:`first_samp` added to them, as in :func:`mne.find_events`. This behavior is not desirable if the returned events will be combined with event times that already have :term:`first_samp` added to them, e.g. event times that come from :func:`mne.find_events`. overlap : float The overlap between events (in seconds). Must be ``0 <= overlap < duration``. .. versionadded:: 0.18 Returns ------- %(events)s r)BaseRawridnumericdurationoverlaprz/overlap must be >=0 but < duration (%s), got %sT)Z use_roundingNr8zANo events produced, check the values of start, stop, and durationr)Zio.baserr r1floatrSZ time_as_indexZ last_samprrrtimesrroundrZaranger2rrr") rrstartstoprrrrtsrr&r,r,r-make_fixed_length_eventsLs>"         rc Cst|tdt|t|kr,t|t|ks4tdt|}t|}t||d}|d}t|dd|dd|ddD]\\}}}|}|dddf|8<|dddf||d7<tj ||fdd}q|S)aConcatenate event lists to be compatible with concatenate_raws. This is useful, for example, if you processed and/or changed events in raw files separately before combining them using :func:`mne.concatenate_raws`. Parameters ---------- events : list of array List of :term:`events` arrays, typically each extracted from a corresponding raw file that is being concatenated. first_samps : list or array of int First sample numbers of the raw files concatenated. last_samps : list or array of int Last sample numbers of the raw files concatenated. Returns ------- events : array The concatenated events. See Also -------- mne.concatenate_raws r&zBevents, first_samps, and last_samps must all have the same lengthsrrNrBr) r rrrSrr6Zcumsumr\r$r) r&Z first_sampsZ last_sampsZn_sampsrr+r{ne2r,r,r-concatenate_eventss   . rc@seZdZdZddddgZdZdZdZed Zed Z d d Z d dZ ddZ ddZ ddZddZddZddZddZeddZedd Zed!d"Zed#d$Zd*d(d)Zd%S)+ AcqParserFIFaParser for Elekta data acquisition settings. This class parses parameters (e.g. events and averaging categories) that are defined in the Elekta TRIUX/VectorView data acquisition software (DACQ) and stored in ``info['acq_pars']``. It can be used to reaverage raw data according to DACQ settings and modify original averaging settings if necessary. Parameters ---------- %(info_not_none)s This is where the DACQ parameters will be taken from. Attributes ---------- categories : list List of averaging categories marked active in DACQ. events : list List of events that are in use (referenced by some averaging category). reject : dict Rejection criteria from DACQ that can be used with mne.Epochs. Note that mne does not support all DACQ rejection criteria (e.g. spike, slope). flat : dict Flatness rejection criteria from DACQ that can be used with mne.Epochs. acq_dict : dict All DACQ parameters. See Also -------- mne.io.Raw.acqparser : Access the parser through a Raw attribute. Notes ----- Any averaging category (also non-active ones) can be accessed by indexing as ``acqparserfif['category_name']``. ERFZDEFZACQZTCP)ZmegMaxZmegMinZmegNoiseZmegSlopeZmegSpikeZeegMaxZeegMinZeegNoiseZeegSlopeZeegSpikeZeogMaxZecgMaxncategneventZ stimSourceZ triggerMapupdateZ artefIgnoreZ averUpdate)CommentZDelay) rZDisplayZStartStateZEndEventZNaveZReqEventZReqWhenZ ReqWithinZSubAve)ZmagMaxZmagMinZmagNoiseZmagSlopeZmagSpikeversion)NameZChannelZNewBitsZOldBitsZNewMaskZOldMaskcCs|d}|stdt|||_d|jkr6d|_nd|jkrHd|_ntd|jr\|jn|j}|D]L}|jd|}|dd d krt|}n|d krt|}t || |qf|j d krd nd|_ | |_ ||_|jD]:}|drd|j |dd<|drd|j |dd<q|j|j|j|jd|_|jsN|j|jd<dd|jD|_|j|jd|_|js|j|jd<dd|jD|_dS)Nacq_parszNo acquisition parametersZ ERFversionFZ ERFncategT#Cannot parse acquisition parametersrrC)magZmegeegeogecg)rr1ZInternalZExternalr<in_usereqevent)gradrrrrcSs&i|]\}}t|dkr|t|qSrrrPr,r,r-rM s z)AcqParserFIF.__init__..)rrcSs&i|]\}}t|dkr|t|qSrrrPr,r,r-rM%s )rSdict _acqpars_genacq_dictcompat_dacq_vars_compat _dacq_varsrr1setattrr=Z stimsource_events_from_acq_pars_events_categories_from_acq_pars _categoriesvaluesZmegmaxZeegmaxZeogmaxZecgmaxZrejectZmagmaxitemsZmegminZeegminZflatZmagmin)selfrrZ dacq_varsvarvalcatr,r,r-__init__sJ        zAcqParserFIF.__init__cCsd}|d|j7}t|j}|d|7}|d|j7}t|j}|d|7}|jr~|d7}|jD]}|d|d|d f7}q`|d 7}|S) Nz)rr_categories_in_user_events_in_use categories)rrEZ cats_in_useZ evs_in_userr,r,r-__repr__(s     zAcqParserFIF.__repr__cCslt|tr|g}nt|tddt}|D](}||jkrJ||j|q*tdq*t|dkrh|dS|S)aReturn an averaging category, or list of categories. Parameters ---------- item : str | list of str Name of the category (comment field in DACQ). Returns ------- conds : dict | list of dict Each dict should have the following keys: comment: str The comment field in DACQ. state : bool Whether the category was marked enabled in DACQ. index : int The index of the category in DACQ. Indices start from 1. event : int DACQ index of the reference event (trigger event, zero time for the corresponding epochs). Note that the event indices start from 1. start : float Start time of epoch relative to the reference event. end : float End time of epoch relative to the reference event. reqevent : int Index of the required (conditional) event. reqwhen : int Whether the required event is required before (1) or after (2) the reference event. reqwithin : float The time range within which the required event must occur, before or after the reference event. display : bool Whether the category was displayed online in DACQ. nave : int Desired number of averages. DACQ stops collecting averages once this number is reached. subave : int Whether to compute normal and alternating subaverages, and how many epochs to include. See the Elekta data acquisition manual for details. Currently the class does not offer any facility for computing subaverages, but it can be done manually by the user after collecting the epochs. ZKeyszcategory nameszNo such categoryrr)rstrr rrr4KeyErrorr)ritemcatsitr,r,r- __getitem__7s0   zAcqParserFIF.__getitem__cCs t|jS)zReturn number of averaging categories marked active in DACQ. Returns ------- n_cat : int The number of categories. )rrrr,r,r-__len__sszAcqParserFIF.__len__c Csddddddddd d d d d ddddd}t}td|jdD]}t|d}t}|jrb|jn|j}|D]T}d||}|} |j |} | dkrt | } n| dkrt | } | || <d|d<ql||d<|jrt||d<d|d<d|d<d|d<|||d<|||<q>|S) zCollect DACQ events into a dict. Events are keyed by number starting from 1 (DACQ index of event). Each event is itself represented by a dict containing the event parameters. rrrp rC )rrrCrpr r r rrrrrrrrr ZERFevent)newbitsoldbitsnewmaskoldmask)delayFrrname?rrrrr) rrangerrzfillr_event_vars_compat _event_varsr=rr1r) rZ_compat_event_lookupr&ZevnumZevnum_sZevdiZ event_varsracq_keyZdict_keyrr,r,r-r}sL        z"AcqParserFIF._events_from_acq_parsc#sfd\}}|D]Ptfdd|jDr6}d}n |sBtd||rPdn7}||fVqdS)z1Yield key/value pairs from ``info['acq_pars'])``.)r"csg|]}|qSr,) startswithrDxliner,r-rFsz-AcqParserFIF._acqpars_gen..r"r N)rHr3_acq_var_magicrS)rrkeyrr,r&r-rs zAcqParserFIF._acqpars_genc Cst}ddtd|jdDD]}t}|jD]*}d||}|}|j|}|||<q0|ddk|d<|ddk|d<dD]}t||||<qd D]}t||||<qt||d <|||d <q |S) zCollect DACQ averaging categories into a dict. Categories are keyed by the comment field in DACQ. Each category is itself represented a dict containing the category parameters. cSsg|]}t|dqSrO)rrr$r,r,r-rFsz:AcqParserFIF._categories_from_acq_pars..rZERFcatdisplayrstate)rend reqwithin)Znaver<rreqwhenZsubaverr)rrr _cat_varsr=rrr1) rrZcatnumZcatdirr!Z class_keyrr*r,r,r-rs"     z&AcqParserFIF._categories_from_acq_parscCs|}d|ddddf<|jD]\}}|dr&t|d|dddf|dk}t|d|ddd f|d k}t||@}||d fd|d>O<q&|S) aCreate list of DACQ events based on mne trigger transitions list. mne_events is typically given by mne.find_events (use consecutive=True to get all transitions). Output consists of rows in the form [t, 0, event_codes] where t is time in samples and event_codes is all DACQ events compatible with the transition, bitwise ORed together: e.g. [t1, 0, 5] means that events 1 and 3 occurred at time t1, as 2**(1 - 1) + 2**(3 - 1) = 5. rNrrCrrrrrr)r$rrrrr)r mne_eventsZevents_revZpre_okZpost_okZok_indr,r,r-_events_mne_to_dacqs&   z AcqParserFIF._events_mne_to_dacqcCsX|d}|d}||}|dddf}t|dddfd|d>@d}||} |r4t|dddfd|d>@d} || } dd|d|d g} ttt| |} | dddf| }tj|jtd }| D]8}t ||dddfk||dddfk}||O}q|t|}||} | t t|j |d |7} | S) a!Translate mne_events to epoch zero times (t0). First mne events (trigger transitions) are converted into DACQ events. Then the zero times for the epochs are obtained by considering the reference and conditional (required) events and the delay to stimulus. r<rNrrrrBr/r.rr) r3rrrr6sortedrrXr r#r1r)rrr1r8Zcat_evZ cat_reqevr&rZrefEvents_indsZ refEvents_tZreqEvents_indsZ reqEvents_tZtwinwinZrefEvents_winsZreq_acctZreqEvent_in_winr,r,r-_mne_events_to_category_t0s6 &   z'AcqParserFIF._mne_events_to_category_t0cCst|jddd}|S)z{Return list of averaging categories ordered by DACQ index. Only returns categories marked active in DACQ. cSs|dSNrr,)rr,r,r-z)AcqParserFIF.categories..r*)r4rr)rrr,r,r-r s zAcqParserFIF.categoriescCst|jddd}|S)zwReturn events ordered by DACQ index. Only returns events that are in use (referred to by a category). cSs|dSr8r,)r2r,r,r-r9r:z%AcqParserFIF.events..r;)r4rr)rZevsr,r,r-r&szAcqParserFIF.eventscCsdd|jDS)NcSsi|]\}}|dr||qS)r,r,rPr,r,r-rM"sz3AcqParserFIF._categories_in_use..)rrrr,r,r-r szAcqParserFIF._categories_in_usecCsdd|jDS)NcSsi|]\}}|dr||qS)rr,rPr,r,r-rM&sz/AcqParserFIF._events_in_use..)rrrr,r,r-r$szAcqParserFIF._events_in_useNrdTc Cs`|dkr|j}t|ts|g}t}|D]} t| tr@|| } t||||d|dddd } |rtt| dddfdkd} dt| krtd| | dd f| | d f<tj | | ddd } |j d } | | | | } tj | t | j| d t| jftj}| d | d i}| d| d}}|t||||dq(t|dkr\|dS|S)aJ Get averaging parameters for a condition (averaging category). Output is designed to be used with the Epochs class to extract the corresponding epochs. Parameters ---------- raw : Raw object An instance of Raw. condition : None | str | dict | list of dict Condition or a list of conditions. Conditions can be strings (DACQ comment field, e.g. 'Auditory left') or category dicts (e.g. acqp['Auditory left'], where acqp is an instance of AcqParserFIF). If None, get all conditions marked active in DACQ. stim_channel : None | str | list of str Name of the stim channel or all the stim channels affected by the trigger. If None, the config variables 'MNE_STIM_CHANNEL', 'MNE_STIM_CHANNEL_1', 'MNE_STIM_CHANNEL_2', etc. are read. If these are not found, it will fall back to 'STI101' or 'STI 014' if present, then fall back to the first channel of type 'stim', if present. mask : int | None The value of the digital mask to apply to the stim channel values. If None (default), no masking is performed. uint_cast : bool If True (default False), do a cast to ``uint16`` on the channel data. This can be used to fix a bug with STI101 and STI014 in Neuromag acquisition setups that use channel STI016 (channel 16 turns data into e.g. -32768), similar to ``mne_fix_stim14 --32`` in MNE-C. mask_type : 'and' | 'not_and' The type of operation between the mask and the trigger. Choose 'and' for MNE-C masking behavior. delayed_lookup : bool If True, use the 'delayed lookup' procedure implemented in Elekta software. When a trigger transition occurs, the lookup of the new trigger value will not happen immediately at the following sample, but with a 1-sample delay. This allows a slight asynchrony between trigger onsets, when they are intended to be synchronous. If you have accurate hardware and want to detect transitions with a resolution of one sample, use delayed_lookup=False. Returns ------- conds_data : dict or list of dict Each dict has the following keys: events : array, shape (n_epochs_out, 3) List of zero time points (t0) for the epochs matching the condition. Use as the ``events`` parameter to Epochs. Note that these are not (necessarily) actual events. event_id : dict Name of condition and index compatible with ``events``. Should be passed as the ``event_id`` parameter to Epochs. tmin : float Epoch starting time relative to t0. Use as the ``tmin`` parameter to Epochs. tmax : float Epoch ending time relative to t0. Use as the ``tmax`` parameter to Epochs. Nr)TFr)rr*rxrrrrrrzThere are several subsequent transitions on the trigger channel. This will not work well with delayed_lookup=True. You may want to check your trigger data and set delayed_lookup=False.rrr8rrrr-)r&r`r9r:)rrrrrrrrrSrrr7rrrXr"r2Zuint32r4rr)rr conditionrr*rrxZdelayed_lookupZ conds_datarr1indr8Zcat_t0_Zcat_t0Zcat_idr9r:r,r,r- get_condition(sHA   $   zAcqParserFIF.get_condition)NNNNrdT)__name__ __module__ __qualname____doc__r)rrr0rr rrrrrrrr3r7propertyrr&rrr>r,r,r,r-rs:& ,< ('    rraise) on_missingcst|t|trt|}t|ttjfr>t|ts>t|}n|g}g}|D]@ttsttdt dd| fdd|DqL|st |ddd |t d tt|}|S) aSearch a collection of event names for matching (sub-)groups of events. This function is particularly helpful when using grouped event names (i.e., event names containing forward slashes ``/``). Please see the Examples section below for a working example. Parameters ---------- event_names : array-like of str | dict Either a collection of event names, or the ``event_id`` dictionary mapping event names to event codes. keys : array-like of str | str One or multiple event names or groups to search for in ``event_names``. on_missing : 'raise' | 'warn' | 'ignore' How to handle situations when none of the ``keys`` can be found in ``event_names``. If ``'warn'`` or ``'ignore'``, an empty list will be returned. Returns ------- matches : list of str All event names that match any of the ``keys`` provided. Notes ----- .. versionadded:: 1.0 Examples -------- Assuming the following grouped event names in the data, you could easily query for all ``auditory`` and ``left`` event names:: >>> event_names = [ ... 'auditory/left', ... 'auditory/right', ... 'visual/left', ... 'visual/right' ... ] >>> match_event_names( ... event_names=event_names, ... keys=['auditory', 'left'] ... ) ['auditory/left', 'auditory/right', 'visual/left'] zkeys must be strings, got z ()c3s,|]$}td|dr|VqdS)/N)setrHissubset)rDrr;r,r- sz$match_event_names..z Event name "zD" could not be found. The following events are present in the data: z, )rEmsgZ error_klass)rrrrrrZndarrayrrStypeextendr joinrr4rH)Z event_nameskeysrEmatchesr,r;r-match_event_namess0-     rQ)NNF)NN)NNNrdFN)NNr)NNrN)NrrrNFrdF) NrrrrNFrdFN)T)rrNrTr)5rBos.pathpathrqcollections.abcrnumpyrutilsrrrrrr r r r r rZ io.constantsrZio.treerZio.tagrZio.openrZio.writerrrrZio.pickrr.r@rcr~rrrrrrrurrrrobjectrrQr,r,r,r-s  4      4 I* m% - 6 S  D =  C.Q