U f{j7/@s~ddlZddlmZddlmZddlmZmZddl m Z ddl m Z m Z mZmZdd lmZmZe Gd d d eeZdS) N) filter_data)_regularized_covariance)TransformerMixin BaseEstimator)psd_array_welch) _time_maskfill_doc_validate_type _check_option)_get_channel_types _picks_to_idxc@sLeZdZdZdddZddZdd d Zd d Zd dZddZ ddZ dS)SSDu, M/EEG signal decomposition using the Spatio-Spectral Decomposition (SSD). SSD seeks to maximize the power at a frequency band of interest while simultaneously minimizing it at the flanking (surrounding) frequency bins (considered noise). It extremizes the covariance matrices associated with signal and noise :footcite:`NikulinEtAl2011`. SSD can either be used as a dimensionality reduction method or a ‘denoised’ low rank factorization method :footcite:`HaufeEtAl2014b`. Parameters ---------- %(info_not_none)s Must match the input data. filt_params_signal : dict Filtering for the frequencies of interest. filt_params_noise : dict Filtering for the frequencies of non-interest. reg : float | str | None (default) Which covariance estimator to use. If not None (same as 'empirical'), allow regularization for covariance estimation. If float, shrinkage is used (0 <= shrinkage <= 1). For str options, reg will be passed to method to :func:`mne.compute_covariance`. n_components : int | None (default None) The number of components to extract from the signal. If n_components is None, no dimensionality reduction is applied. picks : array of int | None (default None) The indices of good channels. sort_by_spectral_ratio : bool (default False) If set to True, the components are sorted accordingly to the spectral ratio. See Eq. (24) in :footcite:`NikulinEtAl2011`. return_filtered : bool (default True) If return_filtered is True, data is bandpassed and projected onto the SSD components. n_fft : int (default None) If sort_by_spectral_ratio is set to True, then the SSD sources will be sorted accordingly to their spectral ratio which is calculated based on :func:`mne.time_frequency.psd_array_welch` function. The n_fft parameter set the length of FFT used. See :func:`mne.time_frequency.psd_array_welch` for more information. cov_method_params : dict | None (default None) As in :class:`mne.decoding.SPoC` The default is None. rank : None | dict | ‘info’ | ‘full’ As in :class:`mne.decoding.SPoC` This controls the rank computation that can be read from the measurement info or estimated from the data. See Notes of :func:`mne.compute_rank` for details. We recommend to use 'full' when working with epoched data. Attributes ---------- filters_ : array, shape (n_channels, n_components) The spatial filters to be multiplied with the signal. patterns_ : array, shape (n_components, n_channels) The patterns for reconstructing the signal from the filtered data. References ---------- .. footbibliography:: NTFc Cs||d} dD]j\} }d|}| d| |krBtd| d|f| || d}t|ttfst|d|d| dq|d|dks|d|dkrtd t||d d d |_~t||jd d}t|dkrtdt|||_ |d|df|_ |d|df|_ ||_ ||_ t|ts,td||_| dkrNt|j d|_n t| |_t|tsltd||_||_||_| |_| |_dS)zInitialize instance.)signalnoise))lr)hr)rr)rrZ_freqz.%s must be defined in filter parameters for %s)numeric Zl_freqZh_freqz[Wrongly specified frequency bands! The signal band-pass must be within the noise band-pass!dataZbads)noneexcludeT)picksuniquerzTAt this point SSD only supports fitting single channel types. Your info has %i typesz&sort_by_spectral_ratio must be booleanNsfreqzreturn_filtered must be boolean) ValueError isinstanceintfloatr rpicks_r leninfo freqs_signal freqs_noisefilt_params_signalfilt_params_noiseboolsort_by_spectral_ration_fftreturn_filteredreg n_componentsrankcov_method_params)selfr"r%r&r+r,rr(r*r)r.r-ZdictsparamddkeyvalZch_typesr4O/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/decoding/ssd.py__init__QsZ        z SSD.__init__cCsNt|tjdtd|jd|jd}||jdkrJtd||jdfdS)zCheck input data.XzX.ndim)rZnchanzAInfo must match the input data.Found %i channels but expected %i.N)r npZndarrayr ndimshaper"r)r/r7Zn_chanr4r4r5_check_Xs  z SSD._check_XcCs@ddlm}|||d|jddf}t||jdf|j}t||jdf|j}||8}|jdkr|t |}t |}t ||j |j |j|jd}t ||j |j |j|jd}|||\} } t | ddd} | | |_| dd| f|_t j|j|_|jj|d|jddf} t} |jr6|j| d \}} | |_|S) aEstimate the SSD decomposition on raw or epoched data. Parameters ---------- X : array, shape ([n_epochs, ]n_channels, n_times) The input data from which to estimate the SSD. Either 2D array obtained from continuous data or 3D array obtained from epoched data. y : None | array, shape (n_samples,) Used for scikit-learn compatibility. Returns ------- self : instance of SSD Returns the modified instance. r)eigh.Nrr8)r+Z method_paramsr-r") ssd_sources)Z scipy.linalgr>r=r rr"r%r&r;r:Zhstackrr+r.r-argsorteigvals_filters_ZlinalgZpinv patterns_TEllipsisr(get_spectral_ratio sorter_spec)r/r7yr>X_auxZX_signalZX_noiseZ cov_signalZ cov_noiserBZ eigvects_ZixX_ssdrH_r4r4r5fitsX      zSSD.fitcCs|||jdkrtd|jrL|d|jddf}t||jdf|j}|jj|d|jddf}|j dkr||j d|j }n0|dd|j ddfddd|j ddf}|S)aEstimate epochs sources given the SSD filters. Parameters ---------- X : array, shape ([n_epochs, ]n_channels, n_times) The input data from which to estimate the SSD. Either 2D array obtained from continuous data or 3D array obtained from epoched data. Returns ------- X_ssd : array, shape ([n_epochs, ]n_components, n_times) The processed data. Nz+No filters available. Please first call fit.rr) r=rC RuntimeErrorr*r rr"r%rEr;rHr,)r/r7rJrKr4r4r5 transforms   0z SSD.transformc Cst||jd|jd\}}t|f|j}t|f|j}|jdkr|dddd|fjddjdd}|dddd|fjddjdd}||}n8|dd|fjdd}|dd|fjdd}||}|ddd } || fS) adGet the spectal signal-to-noise ratio for each spatial filter. Spectral ratio measure for best n_components selection See :footcite:`NikulinEtAl2011`, Eq. (24). Parameters ---------- ssd_sources : array Data projected to SSD space. Returns ------- spec_ratio : array, shape (n_channels) Array with the sprectal ratio value for each component. sorter_spec : array, shape (n_channels) Array of indices for sorting spec_ratio. References ---------- .. footbibliography:: r)rr)r8Nr)Zaxisrrr?) rr"r)r r#r$r;ZmeanrA) r/r@ZpsdZfreqsZsig_idxZ noise_idxZmean_sigZ mean_noiseZ spec_ratiorHr4r4r5rGs   && zSSD.get_spectral_ratiocCs tddS)zNot implemented yet.z'inverse_transform is not yet available.N)NotImplementedError)r/r4r4r5inverse_transformszSSD.inverse_transformcCs.||}|j|jd|jj}||}|S)a<Remove selected components from the signal. This procedure will reconstruct M/EEG signals from which the dynamics described by the excluded components is subtracted (denoised by low-rank factorization). See :footcite:`HaufeEtAl2014b` for more information. .. note:: Unlike in other classes with an apply method, only NumPy arrays are supported (not instances of MNE objects). Parameters ---------- X : array, shape ([n_epochs, ]n_channels, n_times) The input data from which to estimate the SSD. Either 2D array obtained from continuous data or 3D array obtained from epoched data. Returns ------- X : array, shape ([n_epochs, ]n_channels, n_times) The processed data. N)rOrDrHr,rE)r/r7rKZ pick_patternsr4r4r5apply s z SSD.apply)NNNTFNNN)N) __name__ __module__ __qualname____doc__r6r=rMrOrGrQrRr4r4r4r5rs A 4 5%r)numpyr:filterrZcovrrrZtime_frequencyrutilsr r r r Zio.pickr rrr4r4r4r5s