U f{j@sddlmZddlmZddlZddlmZddlm Z m Z ddl m Z m Z ddlmZdd lmZmZmZmZmZmZmZd d lmZmZmZd d lmZmZmZm Z m!Z!Gd dde"Z#Gddde$Z%d4ddZ&edddddZ'ddddZ(d5ddZ)d6ddZ*d7d d!Z+d"d#Z,e d8d$d%Z-ed9d&d'Z.ed:d(d)Z/ed;d*d+Z0dd2d3Z4dS)?)deepcopy)countN)FIFF) pick_types pick_info)find_tag _rename_list) dir_tree_find) write_int write_float write_stringwrite_name_listwrite_float_matrix end_block start_block)_INTERPOLATION_DEFAULT_BORDER_DEFAULT_EXTRAPOLATE_DEFAULT)loggerverbosewarnfill_doc_validate_typecsfeZdZdZdejdddfdd Zdd Zd d Ze dd dd dd dde ddde f ddZ Z S) Projectiona)Projection vector. A basic class to proj a meaningful print for projection vectors. .. warning:: This class is generally not meant to be instantiated directly, use ``compute_proj_*`` functions instead. Parameters ---------- data : dict The data dictionary. desc : str The projector description. kind : int The projector kind. active : bool Whether or not the projector has been applied. explained_var : float | None The explained variance (proportion). FN)desckindactive explained_varcstj|||||ddS)N)rrrdatar )super__init__)selfr!rrrr  __class__J/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/io/proj.pyr#.szProjection.__init__cCsdd|d}|d|d7}|dt|dd7}|ddk r\|d |dd d d 7}d |S)Nz%srz , active : %srz, n_channels : r! col_namesr z , exp. var : d0.2f%z)len)r$sr'r'r(__repr__3s   zProjection.__repr__cCsX|j}||}|D]:\}}|dkrJ|}|d|d<|||<q|||<q|S)zMake a deepcopy.r!)r&__new__itemscopy)r$Zmemodictclsresultkvr'r'r( __deepcopy__<s   zProjection.__deepcopy__T@rheadNNcCs2ddlm}||||||||||| | | | | |dS)aPlot topographic maps of SSP projections. Parameters ---------- %(info_not_none)s Used to determine the layout. %(proj_topomap_kwargs)s %(sphere_topomap_auto)s %(border_topomap)s Returns ------- fig : instance of Figure Figure distributing one image per channel across sensor topography. Notes ----- .. versionadded:: 0.15.0 rplot_projs_topomap) colorbarressizeshowoutlinescontours image_interpaxesvlimsphereborder) viz.topomapr=)r$infocmapsensorsr>r?r@rArBrCrDrErFrGrHr=r'r'r( plot_topomapIs$ zProjection.plot_topomap)__name__ __module__ __qualname____doc__rFIFFV_PROJ_ITEM_FIELDr#r/r7rrrrM __classcell__r'r'r%r(rs*  rc@sxeZdZdZeddZedddZeddd Zdd d Z e ddd dddd dde ddde e fddZdddZdS) ProjMixinaMixin class for Raw, Evoked, Epochs. Notes ----- This mixin adds a proj attribute as a property to data containers. It is True if at least one proj is present and all of them are active. The projs might not be applied yet if data are not preloaded. In this case it's the _projector attribute that does the job. If a private _data attribute is present then the projs applied to it are the ones marked as active. A proj parameter passed in constructor of raw or epochs calls apply_proj and hence after the .proj attribute is True. As soon as you've applied the projs it will stay active in the remaining pipeline. The suggested pipeline is proj=True in epochs (it's cheaper than for raw). When you use delayed SSP in Epochs, projs are applied when you call get_data() method. They are not applied to the evoked._data unless you call apply_proj(). The reason is that you want to reject with projs although it's not stored in proj mode. cCs*t|jddko(tdd|jdDS)z&Whether or not projections are active.projsrcss|]}|dVqdSrNr'.0pr'r'r( sz!ProjMixin.proj..)r-rJall)r$r'r'r(projszProjMixin.projFNc Cst|tr|g}t|ts4tdd|Ds4tdt|dd}|rtdd|jdDrdtd|j||jd<W5QRXn|jd ||j t |jdd d d |jd<W5QRX|S) apAdd SSP projection vectors. Parameters ---------- projs : list List with projection vectors. remove_existing : bool Remove the projection vectors currently in the file. %(verbose)s Returns ------- self : instance of Raw | Epochs | Evoked The data container. css|]}t|tVqdSN) isinstancerrWr'r'r(rZsz%ProjMixin.add_proj..z5Only projs can be added. You supplied something else.Tr2css|]}|dVqdSrVr'rWr'r'r(rZsrUz7Cannot remove projectors that have already been appliedF) check_activesort) r^rlistr[ ValueErrordeactivate_projanyrJ_unlockextend_uniquify_projs)r$rUZremove_existingrr'r'r(add_projs&      zProjMixin.add_projc CsBddlm}ddlm}ddlm}|jddksDt|jddkrRtd |St ||rr|j rrtd d |_ t d d |jdDrtd|St t |jd dd\}}|dkrtd|S|||_|_t |||fr|jrt|j|j|_n8|jr,t|jD]\}}|||j|<qn|td|S)aApply the signal space projection (SSP) operators to the data. Parameters ---------- %(verbose)s Returns ------- self : instance of Raw | Epochs | Evoked The instance. Notes ----- Once the projectors have been applied, they can no longer be removed. It is usually not recommended to apply the projectors at too early stages, as they are applied automatically later on (e.g. when computing inverse solutions). Hint: using the copy method individual projection vectors can be tested without affecting the original data. With evoked data, consider the following example:: projs_a = mne.read_proj('proj_a.fif') projs_b = mne.read_proj('proj_b.fif') # add the first, copy, apply and see ... evoked.add_proj(a).copy().apply_proj().plot() # add the second, copy, apply and see ... evoked.add_proj(b).copy().apply_proj().plot() # drop the first and see again evoked.copy().del_proj(0).apply_proj().plot() evoked.apply_proj() # finally keep both r) BaseEpochs)Evokedr)BaseRawrUNrzRNo projector specified for this dataset. Please consider the method self.add_proj.zLeaving delayed SSP mode.Fcss|]}|dVqdSrVr'rWr'r'r(rZsz'ProjMixin.apply_proj..zFProjections have already been applied. Setting proj attribute to True.T) add_eeg_refactivatez9The projections don't apply to these data. Doing nothing.zSSP projectors applied...)ZepochsrjZevokedrkbaserlrJr-rr^Z_do_delayed_projr[ setup_projr _projectorZpreloadnpdot_data enumerateZ_project_epochZ load_data) r$rrjrkrlrqrJiier'r'r( apply_projs8!           zProjMixin.apply_projr[c Cst|tr(|dkr(ttt|jd}tt|t  }|D]J}|jd|}|drBt |jdt |dd@rBd|}t |qBt t|jd}d||<|j&d d t|jd|D|jd<W5QRX|S) aRemove SSP projection vector. .. note:: The projection vector can only be removed if it is inactive (has not been applied to the data). Parameters ---------- idx : int | list of int | str Index of the projector to remove. Can also be "all" (default) to remove all projectors. Returns ------- self : instance of Raw | Epochs | Evoked The instance. r[rUrch_namesr!r)zCannot remove projector that has already been applied, unless you first remove all channels it applies to. The problematic projector is: FcSsg|]\}}|r|qSr'r')rXrYr5r'r'r( sz&ProjMixin.del_proj..)r^strrbranger-rJrrZ atleast_1darrayintZravelsetrconesrfzip)r$idxrvr\msgZkeepr'r'r(del_projs"    *zProjMixin.del_projTr8rr9r:r;cCsj|jddk s t|jddkr^ddlm}||jd|j|||||||| | | | | ||d}ntd|S)aPlot SSP vector. Parameters ---------- ch_type : 'mag' | 'grad' | 'planar1' | 'planar2' | 'eeg' | None | list The channel type to plot. For 'grad', the gradiometers are collec- ted in pairs and the RMS for each pair is plotted. If None (default), it will return all channel types present. If a list of ch_types is provided, it will return multiple figures. %(proj_topomap_kwargs)s %(sphere_topomap_auto)s %(image_interp_topomap)s %(extrapolate_topomap)s .. versionadded:: 0.20 %(border_topomap)s Returns ------- fig : instance of Figure Figure distributing one image per channel across sensor topography. rUNrrr<)rKrLr>r?r@rArBrCrDrErFrG extrapolaterHz'Info is missing projs. Nothing to plot.)rJr-rIr=rc)r$Zch_typerKrLr>r?r@rArBrCrDrErFrGrrHr=Zfigr'r'r(r="s&  zProjMixin.plot_projs_topomapaccurateautoc Csddlm}t|jddkr"|S|dD]}tdd}d||<t|jf|}t|dkr`q.t|j|}|}| 4g|d<|d krt |drt |dd g|d<W5QRX|||||d } t | |jd |ddf|jd |ddf<q.|S) Nr)_map_meg_or_eeg_channelsrUr)megeegF)rTr)r)modeorigin.)forwardrr-rJrxdictrrr2rf_has_eeg_average_ref_projmake_eeg_average_ref_projrrmatmulr!) r$rrrrkwargsZpicksZ info_fromZinfo_tomappingr'r'r(_reconstruct_projMs<       zProjMixin._reconstruct_proj)FN)N)r[)rr)rNrOrPrQpropertyr\rrirxrrrrrr=rr'r'r'r(rTjs2  * F & *rTTcCs|d|dks| o|d|dko|d|dko|dd|ddko|dd|ddko|dd|ddko|dd|ddkot|dd|ddk}|S) z!Test if two projectors are equal.rrrr!r) row_namesncolnrow)rrr[)abr`equalr'r'r( _proj_equalgs r)ch_names_mappingrc Cs|dkr in|}t}t|tj}t|dkr2|St|dtj}|D]}t||tj}|dk rj|j} n&t||tj }|dk r|j} nt dt||tj }|dk rt |j} nt dt||tj }|dk rt |j} nt dt||tj}|dk r |jd} nt dt||tj}|dk r2|j} nt dt||tj}|dk r^t|j}nd}t||tj}|dk rt|j}nd}| jdt| kr| jd | kr| j} | jd t| krt d t| }t| || dd<t| || t| |d| | d |d }||qFt|dkrtd t||D]R}|drLdnd}td|dd|dddt|ddd|q:|S)Nrz#Projection item description missingzProjection item kind missingz*Number of projection vectors not specified:z$Projection item channel list missingzProjection item data missingFrz>Number of channel names does not match the size of data matrix)rrrr)r!)rrrr!r z( Read a total of %d projection items:rz idlez rz (r!rz x r)z) )rbr r FIFFB_PROJr-FIFFB_PROJ_ITEMrZFIFF_DESCRIPTIONr! FIFF_NAMErcFIFF_PROJ_ITEM_KINDr~FIFF_PROJ_ITEM_NVECFIFF_PROJ_ITEM_CH_NAME_LISTsplitFIFF_PROJ_ITEM_VECTORSFIFF_MNE_PROJ_ITEM_ACTIVEboolFIFF_MNE_ICA_PCA_EXPLAINED_VARfloatshapeTr rrappendrrJ)fidnoderrrUZnodesr1itemtagrrnvecnamesr!rr nchanoner\miscr'r'r( _read_projtst           $ >r)rcCsnt|dkrdS|dkrtn|}t|ttfdt|D]\}}t|td|dq:t|tj |D]}t|tj t |tj t|ddt |dd|}t|tj|t|tj|dt |tj|d |d tjkrt|tjd t |tj|dd t |tj|d t|tj|dd|d dk rPt|tj|d t|tj qht|tj dS)zWrite a projection operator to a file. Parameters ---------- fid : file The file descriptor of the open file. projs : dict The projection operator. rNrUzprojs[]r!r)rrgrrr )r-rrrbtuplerurrrrrr Z FIFF_NCHANr rrr rrrRr ZFIFF_PROJ_ITEM_TIMErrrrrr)rrUrpir\rr'r'r( _write_projs6    rcCs`t|ttfs tdt|ft|D]&\}}t|ts(td|t|fq(|r\t|S|S)z)Check that projs is a list of Projection.z%projs must be a list or tuple, got %szPAll entries in projs list must be Projection instances, but projs[%d] is type %s)r^rbr TypeErrortyperurr)rUr2rrYr'r'r( _check_projss  rr'cCst||||S)aRCreate an SSP operator from SSP projection vectors. Parameters ---------- projs : list List of projection vectors. ch_names : list of str List of channels to include in the projection matrix. bads : list of str Some bad channels to exclude. If bad channels were marked in the raw file when projs were calculated using mne-python, they should not need to be included here as they will have been automatically omitted from the projectors. include_active : bool Also include projectors that are already active. Returns ------- proj : array of shape [n_channels, n_channels] The projection operator to apply to the data. nproj : int How many items in the projector. U : array The orthogonal basis of the projection vectors. )_make_projector)rUrybadsinclude_activer'r'r(make_projectorsrFc s~ddlm}t|}|dkr$tdt||dt|dff}|dkrL|Sd}d} |D](drh|rX| d7} |dd7}qX| dkr|St||f} d}d} t|}t |D]&\} dr|rtdd tt dd krtd | g} g}tdd }t |D]@\}}||kr||kr| || dd  |qdd}| dd|||f}t| dkrdddd|fj || <tddD]}tj|dd|f}|dkrddjdd }|d kr^|s^d tjks*t|dkr^tdtddd|ddt|d|d |dd|f|<| d7} q|r|| j dd<fdd|Ddd <tdd dd<|dd7}q| dks|r|S|j| ddd|fdd\}}}t||ddk} |ddd| f}t||t||j }| |krttd| |f|| |fS)zSubselect projs based on ch_names and bads. Use inplace=True mode to modify ``projs`` inplace so that no warning will be raised next time projectors are constructed with the given inputs. If inplace=True, no meaningful data are returned. r)linalgzNo channel names specifiedNrrr!rr)z@Channel name list in projection item %d contains duplicate items)Zaxisg?rzProjection vector rz has been reduced to r*r+z,% of its original magnitude by subselecting /a of the original channels. If the ignored channels were bad during SSP computation, we recommend recomputing proj (via compute_proj_raw or related functions) with the bad channels properly marked, because computing SSP with bad channels present in the data but unmarked is dangerous (it can bias the PCA used by SSP). On the other hand, if you know that all channels were good during SSP computation, you can safely use info.normalize_proj() to suppress this warning during projection.csg|]}dd|qS)r!r)r')rXrvrYr'r(rzsz#_make_projector..rF)Z full_matricesg{Gz?zFApplication of %d projectors for %d channels will yield no components.)Zscipyrr-rcrreyeemptyZzerosrruuniquerindexrr|ZnormresumrFIFFV_PROJ_ITEM_EEG_AVREFrreprZsvdrs RuntimeError)rUryrrinplacerrZdefault_returnrnprojZvecsZnonzeror5selZvecselZp_setcnamerZ this_vecsr6psizeZorig_nUS_r\r'rr(r8s        .  $ rcCs,t|d|d|d|dddddS)zNormalize proj after subselection to avoid warnings. This is really only useful for tests, and might not be needed eventually if we change or improve our handling of projectors with picks. rUryrrT)rrN)rget)rJr'r'r(_normalize_projs rcCs(t|d|d|d|\}}}||fS)aMake an SSP operator using the measurement info. Calls make_projector on good channels. Parameters ---------- %(info_not_none)s include_active : bool Also include projectors that are already active. Returns ------- proj : array of shape [n_channels, n_channels] The projection operator to apply to the data. nproj : int How many items in the projector. rUryr)r)rJrr\rrr'r'r(make_projector_infos  rcCs4|r t|}|D] }d|d<qtdt||S)a4Set all projections to active. Useful before passing them to make_projector. Parameters ---------- projs : list The projectors. copy : bool Modify projs in place or operate on a copy. %(verbose)s Returns ------- projs : list The projectors. Trz%d projection items activatedrrrJr-rUr2rr\r'r'r( activate_projs  rcCs4|r t|}|D] }d|d<qtdt||S)aBSet all projections to inactive. Useful before saving raw data without projectors applied. Parameters ---------- projs : list The projectors. copy : bool Modify projs in place or operate on a copy. %(verbose)s Returns ------- projs : list The projectors. Frz%d projection items deactivatedrrr'r'r(rds  rdc s|ddrtdtdt|ddddd}|dfd d |D}t|}|d krbtd td |f}|t |}d}t |d|d |d}t ||dt j |d} | S)aCreate an EEG average reference SSP projection vector. Parameters ---------- %(info_not_none)s activate : bool If True projections are activated. %(verbose)s Returns ------- eeg_proj: instance of Projection The SSP/PCA projector. custom_ref_appliedFzA custom reference has been applied to the data earlier. Please use the mne.io.set_eeg_reference function to move from one EEG reference to another.z(Adding average EEG reference projection.TrrrZref_megexcluderycsg|] }|qSr'r')rXr5ryr'r(rz'sz-make_eeg_average_ref_proj..rzACannot create EEG average reference projector (no EEG data found)rN)r)rr!rrAverage EEG reference)rr!rrr )rrrrJrr-rcrrrsqrtrrrr) rJrnreeg_selZ eeg_namesZn_eegZvecr Z eeg_proj_dataeeg_projr'rr(r s2   rcCs:|D]0}|ddks"|dtjkr|r.|drdSqdS)zDetermine if a list of projectors has an average EEG ref. Optionally, set check_active=True to additionally check if the CAR has already been applied. rrrrTF)rr)rUr`r\r'r'r(r8s   rcCs6t|ddddd}t|dko4|d o4t|d S)zDetermine if the EEG needs an averge EEG reference. This returns True if no custom reference has been applied and no average reference projection is present in the list of projections. FTrrrrrU)rr-r)rJrr'r'r(_needs_eeg_average_ref_projFs   rc Cs|r&t|r&t||d}|d|t|\}}|dkrN|rHtdd}ntd||r|t|ddd|d<W5QRX||fS) aSet up projection for Raw and Epochs. Parameters ---------- %(info_not_none)s Warning: will be modified in-place. add_eeg_ref : bool If True, an EEG average reference will be added (unless one already exists). activate : bool If True projections are activated. %(verbose)s Returns ------- projector : array of shape [n_channels, n_channels] The projection operator to apply to the data. info : mne.Info The modified measurement info. )rnrUrz5The projection vectors do not apply to these channelsNz1Created an SSP operator (subspace dimension = %d)Fr_)rrrrrrJrfr)rJrmrnrrZ projectorrr'r'r(rpSs     rpcs\g}|D]&tfdd|Ds|qtt|fdd}|rXt||dS|S)zMake unique projs.c3s|]}t|VqdSr])rrW)r`r\r'r(rZsz"_uniquify_projs..cs8dd|dD}|r$t|d}nt}||dfS)zSort in a nice way.cSsg|]}|r|qSr')isdigit)rXr.r'r'r(rzsz3_uniquify_projs..sorter..r)r~next)xdigitsZsort_idx)my_countr'r(sorters z_uniquify_projs..sorter)key)rerrr-sorted)rUr`raZ final_projsrr')r`rr\r(rhs   rh)T)T)r'T)r'TF)T)TN)TN)TN)F)TTN)TT)5r2r itertoolsrnumpyrr constantsrpickrrrrr treer writer r r rrrrdefaultsrrrutilsrrrrrrrobjectrTrrrrrrrrrrdrrrrprhr'r'r'r(sF    $R~ k.  s     *   ,