U f{jH @sdZddlZddlmZddlmZmZddlm Z m Z m Z m Z m Z mZmZddlmZddlmZmZmZdd lmZdd lmZmZd d lmZmZmZmZmZm Z e dddZ!ddZ"ddZ#e dddZ$e d ddZ%e d!ddZ&dS)"z+Dynamic Imaging of Coherent Sources (DICS).N)equalize_channels) pick_info pick_channels)loggerverbose_check_one_ch_type_check_channels_spatial_filter _check_rank _check_option_validate_type)_subject_from_forward) combine_xyz_check_reference _check_depth) compute_rank) _make_stc _get_src_type)_prepare_beamformer_input_compute_beamformer_check_src_type Beamformer_compute_power_proj_whiten_data皙?F?Tmatrixc*Cst|}td|dddgtd| ddgt|tdfdd d |jD}t|}td ||||\}}}t|t|d g|d }t |||g\}}}t ||| \}}t | d} | dkrd| d<t ||||f||dd| \}}}}}}}}g}|st |||d}tt|D]|}t |j|dd||d}|sz|D]@}||ksX||||kr8td|||||dfq8|t|q~t|d }tdg}g} t|D]\}}!|dkrtd|!|d|f|j|d}"| r|"j}"|rdnd}#t||"||#||| ||| |||d \}$}%||$| |%qt|}|dkrht| } nd} t|d|}&t|}'|dkr|nd}tdd |D}(td||||||(|'|| ||&||| d })|)S)!aCompute a Dynamic Imaging of Coherent Sources (DICS) spatial filter. This is a beamformer filter that can be used to estimate the source power at a specific frequency range :footcite:`GrossEtAl2001`. It does this by constructing a spatial filter for each source point. The computation of these filters is very similar to those of the LCMV beamformer (:func:`make_lcmv`), but instead of operating on a covariance matrix, the CSD matrix is used. When applying these filters to a CSD matrix (see :func:`apply_dics_csd`), the source power can be estimated for each source point. Parameters ---------- %(info_not_none)s forward : instance of Forward Forward operator. csd : instance of CrossSpectralDensity The data cross-spectral density (CSD) matrices. A source estimate is performed for each frequency or frequency-bin defined in the CSD object. reg : float The regularization to apply to the cross-spectral density before computing the inverse. noise_csd : instance of CrossSpectralDensity | None Noise cross-spectral density (CSD) matrices. If provided, whitening will be done. The noise CSDs need to have been computed for the same frequencies as the data CSDs. Providing noise CSDs is mandatory if you mix sensor types, e.g. gradiometers with magnetometers or EEG with MEG. .. versionadded:: 0.20 label : Label | None Restricts the solution to a given label. %(pick_ori_bf)s %(rank_none)s .. versionadded:: 0.17 %(weight_norm)s Defaults to ``None``, in which case no normalization is performed. %(reduce_rank)s %(depth)s real_filter : bool If ``True``, take only the real part of the cross-spectral-density matrices to compute real filters. .. versionchanged:: 0.23 Version 0.23 an earlier used ``real_filter=False`` as the default, as of version 0.24 ``True`` is the default. %(inversion_bf)s .. versionchanged:: 0.21 Default changed to ``'matrix'``. %(verbose)s Returns ------- filters : instance of Beamformer Dictionary containing filter weights from DICS beamformer. Contains the following keys: 'kind' : str The type of beamformer, in this case 'DICS'. 'weights' : ndarray, shape (n_frequencies, n_weights) For each frequency, the filter weights of the beamformer. 'csd' : instance of CrossSpectralDensity The data cross-spectral density matrices used to compute the beamformer. 'ch_names' : list of str Channels used to compute the beamformer. 'proj' : ndarray, shape (n_channels, n_channels) Projections used to compute the beamformer. 'vertices' : list of ndarray Vertices for which the filter weights were computed. 'n_sources' : int Number of source location for which the filter weight were computed. 'subject' : str The subject ID. 'pick-ori' : None | 'max-power' | 'normal' | 'vector' The orientation in which the beamformer filters were computed. 'inversion' : 'single' | 'matrix' Whether the spatial filters were computed for each dipole separately or jointly for all dipoles at each vertex using a matrix inversion. 'weight_norm' : None | 'unit-noise-gain' The normalization of the weights. 'src_type' : str Type of source space. 'is_free_ori' : bool Whether the filter was computed in a fixed direction (pick_ori='max-power', pick_ori='normal') or not. 'whitener' : None | ndarray, shape (n_channels, n_channels) Whitening matrix, provided if whitening was applied to the covariance matrix and leadfield during computation of the beamformer weights. 'max-power-ori' : ndarray, shape (n_sources, 3) | None When pick_ori='max-power', this fields contains the estimated direction of maximum power at each source location. See Also -------- apply_dics_csd Notes ----- The original reference is :footcite:`GrossEtAl2001`. See :footcite:`vanVlietEtAl2018` for a tutorial style paper on the topic. The DICS beamformer is very similar to the LCMV (:func:`make_lcmv`) beamformer and many of the parameters are shared. However, :func:`make_dics` and :func:`make_lcmv` currently have different defaults for these parameters, which were settled on separately through extensive practical use case testing (but not necessarily exhaustive parameter space searching), and it remains to be seen how functionally interchangeable they could be. The default setting reproduce the DICS beamformer as described in :footcite:`vanVlietEtAl2018`:: inversion='single', weight_norm=None, depth=1. To use the :func:`make_lcmv` defaults, use:: inversion='matrix', weight_norm='unit-noise-gain-invariant', depth=None For more information about ``real_filter``, see the supplemental information from :footcite:`HippEtAl2011`. References ---------- .. footbibliography:: pick_oriNnormalz max-power inversionZsingler weight_normcSsg|]}t|qSnpmean).0Zfreq_binr"r"S/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/beamformer/_dics.py szmake_dics..Zdicsch_namesZbadsZ depth_sparseFr)Z noise_covrankZpca)infor*T)indexas_covz3%s data rank (%s) did not match the noise rank (%s)z!Computing DICS spatial filters...rz1 computing DICS spatial filter at %sHz (%d/%d)r,)r*r nn orient_stdwhitenersrc)NZvectorcSsg|] }t|qSr")len)r&vr"r"r'r(sZDICS)kindweightscsdr)projvertices n_sourcessubjectrr r!src_type is_free_orir2 max_power_ori) r r r str frequenciesr4rrrr_prepare_noise_csdrrrrangeget_data ValueErrorgetappendsumvalueslistrr+ enumeraterealrr$arrayrr r)*r+forwardr8reg noise_csdlabelrr*r!Z reduce_rankdepth real_filterr rrAn_freqs_Zallow_mismatchr>r9r:Gr2r0r1Z csd_int_rankZ noise_rankiZcsd_rankkeyr)WsZmax_orisfreqCmn_orientWr?r=r<r;filtersr"r"r' make_dicss                r_cCsT|dk rLt||g\}}t|jdkr.|}|jdd}|rL|dj|d<||fS)NrT)r-data)rr4rAr%rDrL)r8rPrSr"r"r'rBs rBc cst|tjr"|jdkr"|g}d}nd}|d}t|dk}|d}t|\}}t|D]\} } |sttd| dt | |d|} g} |D]Z} t | | } |d rtd t | } d |d }| t | |d |d||||dq|r| dVqV| VqVtddS)zz#combining the current components...rZsfreqr:r=r:r=tmintstepr< warn_textr[done]N) isinstancer$Zndarrayndimr4rrKrr+rdotrrGr)r`r^r+rbZ one_epochrYZone_freqr<rdrWMstcsr]Zsolrcr"r"r' _apply_dics s<       rkcCsJt||j}|j}|jd}t|j|}||}t||||d}t|S)aIApply Dynamic Imaging of Coherent Sources (DICS) beamformer weights. Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights on evoked data. .. warning:: The result of this function is meant as an intermediate step for further processing (such as computing connectivity). If you are interested in estimating source time courses, use an LCMV beamformer (:func:`make_lcmv`, :func:`apply_lcmv`) instead. If you are interested in estimating spectral power at the source level, use :func:`apply_dics_csd`. .. warning:: This implementation has not been heavily tested so please report any issues or suggestions. Parameters ---------- evoked : Evoked Evoked data to apply the DICS beamformer weights to. filters : instance of Beamformer DICS spatial filter (beamformer weights) Filter weights returned from :func:`make_dics`. %(verbose)s Returns ------- stc : SourceEstimate | VolSourceEstimate | list Source time courses. If the DICS beamformer has been computed for more than one frequency, a list is returned containing for each frequency the corresponding time courses. See Also -------- apply_dics_epochs apply_dics_csd rr`r^r+rb)rr+r`timesr r)rknext)Zevokedr^rr+r`rbselZstcr"r"r' apply_dics6s%  rpc Csvt|t|ddkr td|j}|jd}t|j|}|dd|ddf}t||||d}|srt |}|S)aApply Dynamic Imaging of Coherent Sources (DICS) beamformer weights. Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights on single trial data. .. warning:: The result of this function is meant as an intermediate step for further processing (such as computing connectivity). If you are interested in estimating source time courses, use an LCMV beamformer (:func:`make_lcmv`, :func:`apply_lcmv`) instead. If you are interested in estimating spectral power at the source level, use :func:`apply_dics_csd`. .. warning:: This implementation has not been heavily tested so please report any issue or suggestions. Parameters ---------- epochs : Epochs Single trial epochs. filters : instance of Beamformer DICS spatial filter (beamformer weights) Filter weights returned from :func:`make_dics`. The DICS filters must have been computed for a single frequency only. return_generator : bool Return a generator object instead of a list. This allows iterating over the stcs without having to keep them all in memory. %(verbose)s Returns ------- stc: list | generator of (SourceEstimate | VolSourceEstimate) The source estimates for all epochs. See Also -------- apply_dics apply_dics_csd r7rzThis function only works on DICS beamformer weights that have been computed for a single frequency. When calling make_dics(), make sure to use a CSD object with only a single frequency (or frequency-bin) defined.rNrl) rr4rEr+rmr r)rDrkrJ) Zepochsr^Zreturn_generatorrr+rbror`rjr"r"r'apply_dics_epochsis'  rqc sL|d}|d}|drdnd}|d}|d}|d}d d jD} t| } t|tjf} fd d |D} td t| D]\} }| dkrtd || d| fj| d}|| ddfdd| f}|d| }t|t|| j }t |||| dd| f<qtdt |\}}t | ||ddd||d| fS)a%Apply Dynamic Imaging of Coherent Sources (DICS) beamformer weights. Apply a previously computed DICS beamformer to a cross-spectral density (CSD) object to estimate source power in time and frequency windows specified in the CSD object :footcite:`GrossEtAl2001`. Parameters ---------- csd : instance of CrossSpectralDensity The data cross-spectral density (CSD) matrices. A source estimate is performed for each frequency or frequency-bin defined in the CSD object. filters : instance of Beamformer DICS spatial filter (beamformer weights) Filter weights returned from `make_dics`. %(verbose)s Returns ------- stc : SourceEstimate Source power with frequency instead of time. frequencies : list of float The frequencies for which the source power has been computed. If the data CSD object defines frequency-bins instead of exact frequencies, the mean of each bin is returned. References ---------- .. footbibliography:: r)r:r>r/rr<r2r;cSsg|]}t|qSr"r#)r&Zdfreqr"r"r'r(sz"apply_dics_csd..csg|]}j|qSr")r)r,)r&chr8r"r'r(szComputing DICS source power...z0 applying DICS spatial filter at %sHz (%d/%d)r.Nr7rer=grra)rAr4r$Zzerosrr+rKrDrhZconjTrrr)r8r^rr)r:r\r<r2r;rArTZ source_powerZ csd_picksrWrZr[r]rdr"rsr'apply_dics_csds@       ru) rNNNNNFrTrN)N)FN)N)'__doc__numpyr$ZchannelsrZio.pickrrutilsrrrr r r r rNr Zminimum_norm.inverserrrr*rZsource_estimaterrrrrrrrr_rBrkrprqrur"r"r"r's: $    c - 2 >