U f{jNe@sdZddlmZddlmZddlZddlZddlZddl m Z m Z m Z ddl mZmZddlmZmZmZed Zd e_Gd d d eZGd ddeZdddZGdddeZddZddZGdddeZdS)zSome utility functions.) OrderedDict)deepcopyN)_check_pandas_installed_check_preload_validate_type)warnverbose) object_size object_hash _time_maskmneFc@s,eZdZdZddZeddZddZdS) SizeMixinzEstimate MNE object sizes.cCst|t|ot|t|kS)zCompare self to other. Parameters ---------- other : object The object to compare to. Returns ------- eq : bool True if the two objects are equal. ) isinstancetypehash)selfotherrN/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/utils/mixin.py__eq__s zSizeMixin.__eq__cCsdzt|j}Wntk r,tdYdSXt|drH|t|j7}nt|dr`|t|j7}|S)zEstimate the object size.z Could not get size for self.infodata_data)r info Exceptionrhasattrrr)rsizerrr_size)s  zSizeMixin._sizecCsddlm}ddlm}ddlm}t||rBtt|j |j dSt|||frnt |dtt|j |j dSt dt|dS) zbHash the object. Returns ------- hash : int The hash )Evoked BaseEpochs)BaseRaw)rrzHashing zHashing unknown object type: %sN)Zevokedr epochsr"Zio.baser#rr dictrrrr RuntimeErrorr)rr r"r#rrr__hash__7s     zSizeMixin.__hash__N)__name__ __module__ __qualname____doc__rpropertyrr'rrrrrs  rc@seZdZdZddZddZdd d Zd d Zd dZddZ dddZ ddZ e Z dddZ eddZejedddZdS)GetEpochsMixinz=Class to add epoch selection and metadata to certain classes.cCs ||S)a Return an Epochs object with a copied subset of epochs. Parameters ---------- item : slice, array-like, str, or list See below for use cases. Returns ------- epochs : instance of Epochs See below for use cases. Notes ----- Epochs can be accessed as ``epochs[...]`` in several ways: 1. **Integer or slice:** ``epochs[idx]`` will return an `~mne.Epochs` object with a subset of epochs chosen by index (supports single index and Python-style slicing). 2. **String:** ``epochs['name']`` will return an `~mne.Epochs` object comprising only the epochs labeled ``'name'`` (i.e., epochs created around events with the label ``'name'``). If there are no epochs labeled ``'name'`` but there are epochs labeled with /-separated tags (e.g. ``'name/left'``, ``'name/right'``), then ``epochs['name']`` will select the epochs with labels that contain that tag (e.g., ``epochs['left']`` selects epochs labeled ``'audio/left'`` and ``'visual/left'``, but not ``'audio_left'``). If multiple tags are provided *as a single string* (e.g., ``epochs['name_1/name_2']``), this selects epochs containing *all* provided tags. For example, ``epochs['audio/left']`` selects ``'audio/left'`` and ``'audio/quiet/left'``, but not ``'audio/right'``. Note that tag-based selection is insensitive to order: tags like ``'audio/left'`` and ``'left/audio'`` will be treated the same way when selecting via tag. 3. **List of strings:** ``epochs[['name_1', 'name_2', ... ]]`` will return an `~mne.Epochs` object comprising epochs that match *any* of the provided names (i.e., the list of names is treated as an inclusive-or condition). If *none* of the provided names match any epoch labels, a ``KeyError`` will be raised. If epoch labels are /-separated tags, then providing multiple tags *as separate list entries* will likewise act as an inclusive-or filter. For example, ``epochs[['audio', 'left']]`` would select ``'audio/left'``, ``'audio/right'``, and ``'visual/left'``, but not ``'visual/right'``. 4. **Pandas query:** ``epochs['pandas query']`` will return an `~mne.Epochs` object with a subset of epochs (and matching metadata) selected by the query called with ``self.metadata.eval``, e.g.:: epochs["col_a > 2 and col_b == 'foo'"] would return all epochs whose associated ``col_a`` metadata was greater than two, and whose ``col_b`` metadata was the string 'foo'. Query-based indexing only works if Pandas is installed and ``self.metadata`` is a :class:`pandas.DataFrame`. .. versionadded:: 0.16 )_getitem)ritemrrr __getitem__NsBzGetEpochsMixin.__getitem__cCszt|tr|g}t|ttfrDt|dkrDt|dtrD||}n2t|trT|}n"t|}t|dkrvt gt }|SNr) rstrlisttuplelen _keys_to_idxslicenp atleast_1darrayint)rr/selectrrr_item_to_selects       zGetEpochsMixin._item_to_selectIGNOREDTFcsT|j}|`|r|n|||__~|}td} | rj|} tj} |dk rztj| D]} |f| | <qjt | _| _~ t j |_ j dk rt dd} | rЈj j|}| rj|_ntj d|}tj j|ddjr|rtjj|dgd_|r>fd d jD_|rL|fSSdS) a Select epochs from current object. Parameters ---------- item: slice, array-like, str, or list see `__getitem__` for details. reason: str entry in `drop_log` for unselected epochs copy: bool return a copy of the current object drop_event_id: bool remove non-existing event-ids after selection select_data: bool apply selection to data (use `select_data=False` if subclasses do not have a valid `_data` field, or data has already been subselected) return_indices: bool return the indices of selected epochs from the original object in addition to the new `Epochs` objects Returns ------- `Epochs` or tuple(Epochs, np.ndarray) if `return_indices` is True subset of epochs (and optionally array with kept epoch indices) selectionNFstrictobject)r O) requirementscs,i|]$\}}|jdddfkr||qSNr)events).0kvinstrr sz+GetEpochsMixin._getitem..)rcopyr=rr?r3drop_logr8Z setdiff1dr4Z atleast_2drFmetadatarZilocindexr:tolistr-fsetpreloadrequireevent_iditems)rr/reasonrMZ drop_event_idZ select_dataZreturn_indicesrr<Z has_selectionZ key_selectionrNrHpdrOrrJrr.s@           zGetEpochsMixin._getitemc sRddlm}t|ttfr|n|g}z6ttjtfdd|j |DdddWSt k rL}zt |dksj dkrt |jd}td d }|r,td rj nd}j|d z j j|dd djj}Wn8tk r}z|d|jdf7}W5d}~XYnX|WYSn|d7}t |W5d}~XYnXdS)zFind entries in event dict.r)match_event_namescs(g|] }jdddfj|kqSrE)rFrU)rGrHrrr sz/GetEpochsMixin._keys_to_idx..r)ZaxisrNFr@ _metadatarOpython)Zenginez? The epochs.metadata Pandas query did not yield any results: %szU The epochs.metadata Pandas query could not be performed, consider installing Pandas.)eventrYrr3r4r8whereanyr:rUKeyErrorr5rOr2argsrr_check_metadata reset_indexqueryrPvaluesr) rkeysrYerrmsgrXmdvalsexprrZrr6s>      zGetEpochsMixin._keys_to_idxcCs.ddlm}t||r$|js$tdt|jS)aReturn the number of epochs. Returns ------- n_epochs : int The number of remaining epochs. Notes ----- This function only works if bad epochs have been dropped. Examples -------- This can be used as:: >>> epochs.drop_bad() # doctest: +SKIP >>> len(epochs) # doctest: +SKIP 43 >>> len(epochs.events) # doctest: +SKIP 43 rr!zSince bad epochs have not been dropped, the length of the Epochs is not known. Load the Epochs with preload=True, or call Epochs.drop_bad(). To find the number of events in the Epochs, use len(Epochs.events).)r$r"rZ _bad_droppedr&r5rF)rr"rrr__len__s zGetEpochsMixin.__len__cCsd|_|j|_|S)aFacilitate iteration over epochs. This method resets the object iteration state to the first epoch. Notes ----- This enables the use of this Python pattern:: >>> for epoch in epochs: # doctest: +SKIP >>> print(epoch) # doctest: +SKIP Where ``epoch`` is given by successive outputs of :meth:`mne.Epochs.next`. r)_currentZ_detrend_picks_current_detrend_picksrZrrr__iter__0szGetEpochsMixin.__iter__cCst|ds||jrL|jt|jkr0||j|j}|jd7_nld}|s|jt|jkrl|||j}| ||j }| |}|jd7_| |\}}qP|j r|}|s|S||j|jddfSdS)a}Iterate over epoch data. Parameters ---------- return_event_id : bool If True, return both the epoch data and an event_id. Returns ------- epoch : array of shape (n_channels, n_times) The epoch data. event_id : int The event id. Only returned if ``return_event_id`` is ``True``. rprFrN)rrqrSror5r _stop_iterrFZ_get_epoch_from_rawZ_detrend_offset_decimrpZ_project_epochZ_is_good_epochZ_do_delayed_proj)rZreturn_event_idepochZis_goodZ epoch_noproj_rrr__next__Cs0    zGetEpochsMixin.__next__cCs|`|`tdS)N)rorp StopIterationrZrrrrrmszGetEpochsMixin._stop_iterNcCs|dkr dStdd}|rt||jddt|t|jkrVtdt|t|jf|rt|drz|jdd }|j|_ qt |}nt|t dd|rt |}|S) zCheck metadata consistency.NFr@rO)types item_namez>metadata must have the same number of rows (%d) as events (%d)r?T)Zdrop) rr DataFramer5rF ValueErrorrrer?rPrr3)rrOrerXrrrrdts,     zGetEpochsMixin._check_metadatacCs|jS)zGet the metadata.)r\rZrrrrOszGetEpochsMixin.metadatacCs|j|dd}|dk rBtddr,|jd}n t|d}d|}nd}t|d rt|jdk rt|dkrfd nd }|d 7}n|dkrd nd}td||f||_dS)NT)reFr@rrz with %d columnsr\ZRemovingZ Replacingz existingz Not settingAddingz %s metadata%s)rdrshaper5rr\loggerr)rrOr Zn_colactionrrrrOs     )r>TTTF)F)NF)N)r(r)r*r+r0r=r.r6rnrqrurrnextrdr,rOsetterr rrrrr-Ks&D G'  *  r-TcCs|dks|t|krtdt|}|dt|}t|}d|krP|ksfntd|d||r|d}|dkr|dkrtd |d |d n0|dkr|d |krtd |d|d |d |||fS)zCheck decimation parameters.rzdecim must be an integer > 0sfreqrz'decim must be at least 0 and less than z, got lowpassNzOThe measurement information indicates data is not low-pass filtered. The decim=z2 parameter will result in a sampling frequency of z( Hz, which can cause aliasing artifacts.z>The measurement information indicates a low-pass frequency of z Hz. The decim=)r;rzfloatr)rdecimoffset check_filter new_sfreqrrrr _check_decimsrc@s|eZdZdZeddZddZeddZedd Ze dd d Z e dddZ dddZ ddZ dddZddZd S) TimeMixinz3Class to handle operations on time for MNE objects.cCs|jS)zTime vector in seconds.)_times_readonlyrZrrrtimesszTimeMixin.timescCs||_d|jjd<dS)z1Set self._times_readonly (and make it read only).FZ WRITEABLEN)rMrflags)rrrrr _set_timess zTimeMixin._set_timescCs |jdS)zFirst time point.rrrZrrrtminszTimeMixin.tmincCs |jdS)zLast time point.rrrZrrrtmaxszTimeMixin.tmaxNTcCs|dkr|j}n.||jkr>tdt|d|jdd|j}|dkrN|j}n2||jkrtdt|d|jdd|j}d}t|j|||jd |d }||j||j||_| |j d |f|_ |S) a Crop data to a given time interval. 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 ------- inst : instance of Raw, Epochs, Evoked, AverageTFR, or SourceEstimate The cropped time-series object, modified in-place. Notes ----- %(notes_tmax_included_by_default)s Nz-tmin is not in time interval. tmin is set to z.tmin (gz sec)z-tmax is not in time interval. tmax is set to z.tmax (Tr)r include_tmax.) rrrrr rrr _raw_times_update_first_lastr)rrrrr maskrrrcrops&   zTimeMixin.croprc Cst|j||t|d d\}}}tt|jd |jd|j}|j|9_||j|}t|d|j}|j||jd<W5QRX|j r|dkr|j d|f |_ |j| |_nt |j |_ td|_d|_n||_||j|j||S)a,Decimate the time-series data. Parameters ---------- %(decim)s %(offset_decim)s %(verbose)s Returns ------- inst : MNE-object The decimated object. See Also -------- mne.Epochs.resample mne.io.Raw.resample Notes ----- %(decim_notes)s If ``decim`` is 1, this method does not copy the underlying data. .. versionadded:: 0.10.0 References ---------- .. footbibliography:: Zfreqs)rrrNr.)rrrr;roundrZ_decimr7Z_unlockrSrrMr8ZascontiguousarrayZ _decim_slicerr)rrrr rZ start_idxZi_startZ decim_slicerrrdecimate s2#    zTimeMixin.decimateFcCs\ddlm}t||r"d|j}n |jd}t||jd|}|rRt|}| t S)aConvert time to indices. Parameters ---------- times : list-like | float | int List of numbers or a number representing points in time. use_rounding : bool If True, use rounding (instead of truncation) when converting times to indices. This can help avoid non-unique indices. Returns ------- index : ndarray Indices corresponding to the times supplied. r)_BaseSourceEstimateg?rr) Zsource_estimaterrZtsteprr8r9rrZastyper;)rrZ use_roundingrrrPrrr time_as_indexFs     zTimeMixin.time_as_indexcCst|ddddt|dddd|jj}|dkr4dn ||d}|dkrN|n ||d}ttd||}ttd||}||fS)aConvert seconds to index into data. Parameters ---------- tmin : int | float | None Start time of data to get in seconds. tmax : int | float | None End time of data to get in seconds. Returns ------- start : int Integer index into data corresponding to tmin. stop : int Integer index into data corresponding to tmax. )numericNrzint, float, None)rwrx type_namerNr)rrrrminmax)rrrZn_timesstartstoprrr_handle_tmin_tmax`szTimeMixin._handle_tmin_tmaxcCsTt|d||r|jdnd}|tt|j|jd}||||S)amShift time scale in epoched or evoked data. Parameters ---------- tshift : float The (absolute or relative) time shift in seconds. If ``relative`` is True, positive tshift increases the time value associated with each sample, while negative tshift decreases it. relative : bool If True, increase or decrease time values by ``tshift`` seconds. Otherwise, shift the time values such that the time of the first sample equals ``tshift``. Returns ------- epochs : MNE-object The modified instance. Notes ----- This method allows you to shift the *time* values associated with each data sample by an arbitrary amount. It does *not* resample the signal or change the *data* values in any way. shift_timergr)rrr8Zaranger5rrr)rZtshiftrelativerZ new_timesrrrrs   zTimeMixin.shift_timecCs8tt|jd|jd|_t|j|jd|_dS)z1Update self.first and self.last (sample indices).rrrN)r;rrrfirstr5lastrZrrrrszTimeMixin._update_first_last)NNTN)rN)F)T)r(r)r*r+r,rrrrr rrrrrrrrrrrs     - ; " rcCs<|dk r8t|ts |jdd}n t|}t|ts8t|S)z$Convert metadata to JSON for saving.Nrecords)Zorient)rr3to_jsonjsondumpsr2AssertionErrorr]rrr_prepare_write_metadatas   rcCsR|dk rNtdd}tj|td}t|ts.t|rN|j|}t||jsNt|S)z&Convert saved metadata back from JSON.NFr@)object_pairs_hook) rrloadsrrr3rryZ from_records)rOrXrrr_prepare_read_metadatas  rc@seZdZddZddZdS) _FakeNoPandascCs.ddd}ddl}t|_||j_||jj_dS)NTcSs|rtdndSdS)NzPandas not installedF)r&r@rrr_checks z'_FakeNoPandas.__enter__.._checkr)T)r r _old_checkr$utilsmixin)rrr rrr __enter__s  z_FakeNoPandas.__enter__cGs"ddl}|j|j_|j|jj_dSr1)r rr$rrr)rrcr rrr__exit__s z_FakeNoPandas.__exit__N)r(r)r*rrrrrrrs r)T)r+ collectionsrrMrloggingrnumpyr8checkrrrZ_loggingrr Znumericsr r r getLoggerr~ propagaterBrr-rrrrrrrrrs(   4a f