U f{jJ @sddlmZddlmZddlmZddlmZddlmZddl m Z ddl m Z m Z ddlZddlZddlZd d lmZmZmZmZd d lmZmZd d lmZd dlmZd dlmZm Z d dl!m"Z"d dl#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)d dl*m+Z+d dl,m-Z-m.Z.m/Z/m0Z0m1Z1m2Z2d dl3m4Z4d dl5m6Z6d dl7m8Z8d dl9m:Z:m;Z;mZ>d dl?m@Z@d dlAmBZBmCZCd dlDmEZEd dlFmGZGmHZHmIZImJZJd dlKmLZLd dlMmNZNd dlOmPZPd d lQmRZRd d!lSmTZTmUZUd d"l,mVZVmWZWd d#lXmYZYmZZZm[Z[m\Z\m]Z]m^Z^m_Z_m`Z`maZambZbmcZcmdZdmeZemfZfmgZgmhZhmiZimjZjmkZkmlZlmmZmmnZnd d$lompZpmqZqd d%lrmsZsd d<muZud d'lvmwZwd d(l#mxZxmyZyd)Zzded+d,Z{d-hZ|d.d/Z}dfd0d1Z~d2ZeiGd3d4d4e<Zd5d6Zd7d8Ze\dgd>d?Ze\dhdBdCZdDdEZdFdGZdidHdIZdjdKdLZdkdOdPZdldQdRZdSdTZe\dmdUdVZedWdXZe\dndYdZZd[d\Ze\dod`daZe\ddbdcddZdS)p) isfunction) namedtupledeepcopy)Integral)time) dataclass)OptionalListN) qrs_detector_get_ecg_channel_index _make_ecgcreate_ecg_epochs)_find_eog_events_get_eog_channel_index)infomax)compute_whitener) CovarianceEvoked)_INTERPOLATION_DEFAULT) pick_types pick_channels pick_info _picks_to_idx_get_channel_types_DATA_CH_TYPES_SPLIT)make_projector)write_double_matrix write_stringwrite_name_list write_int start_block end_block) dir_tree_find) fiff_open)read_tag)write_meas_inforead_meas_info ContainsMixin)FIFF)BaseRaw) _get_info_check_load_mat) BaseEpochs)plot_ica_componentsplot_ica_scoresplot_ica_sourcesplot_ica_overlayplot_ica_properties) _plot_corrmap)_contains_ch_type)_find_topomap_coords) psd_welchpsd_multitaper)start_and_end_filewrite_id)logger check_fname _check_fnameverbose_reject_data_segmentscheck_random_state_validate_type compute_corr_get_inst_data _ensure_intcopy_function_doc_to_method_doc_plwarnBunch_check_preload_check_compensation_gradefill_doc _check_option_PCAint_like_require_version_check_all_same_channel_names) _get_args _safe_svd) filter_data)_find_outliers)ctps)pick_channels_regexp_picks_by_type)ICAica_find_ecg_eventsica_find_eog_eventsget_score_funcsread_icaread_ica_eeglabFcs@|rfdd}n fdd}ddjjg|_j|_|S) Aux function.cs&tfdd|DdddfS)Ncsg|]}|qSravel.0afuncyraT/var/www/html/bwave/python/venv/lib/python3.8/site-packages/mne/preprocessing/ica.py Ms1_make_xy_sfunc..sfunc..rnparrayxrirhrirjsfuncLsz_make_xy_sfunc..sfunccstfdd|DS)Ncsg|]}|qSrarbrdrgrarjrkPsrlrmrprrrsrjrtOs. score_func)join __module____name____doc__)rh ndim_outputrtrarrrj_make_xy_sfuncIs  r|Zsomersdcsddlm}ddlm}t}ddt|D}ddt|D}|dd|Dd |fd d|Dd |kst|S) zjGet the score functions. Returns ------- score_funcs : dict The score functions. r)stats)distancecSs2g|]*\}}t|r|ds|tkr||fqS_r startswith _BLOCKLISTrenfrararjrkhs  z#get_score_funcs..cSs2g|]*\}}t|r|ds|tkr||fqSrrrrararjrkks  cSs*i|]"\}}t|ddgkr|t|qS)uvrSr|rrararj nsz#get_score_funcs..)Zvar_positionalZ var_keyword keyword_onlycs2i|]*\}}t|dddgkr|t|ddqS)excluderqriT)r{rrrrarjrtspearsonr) scipyr}Z scipy.spatialr~rJvarsitemsupdateAssertionError)r}r~Z score_funcsZxy_arg_dist_funcsZxy_arg_stats_funcsrarrjr]]s    r]cs\td|rdnd7t||ddd}tfdd|D}|sXtd t||fd S) aECheck for channels in picks that are not considered valid channels. Accepted channels are the data channels ('seeg', 'dbs', 'ecog', 'eeg', 'hbo', 'hbr', 'mag', and 'grad'), 'eog' and 'ref_meg'. This prevents the program from crashing without feedback when a bad channel is provided to ICA whitening. )eog)ref_megraTF)uniqueZ only_data_chscsg|] }|kqSrararechtypesrarjrksz7_check_for_unsupported_ica_channels..zTInvalid channel type%s passed for ICA: %s.Only the following types are supported: %sN)rrall ValueErrorrH)picksinfo allow_ref_megchscheckrarrj#_check_for_unsupported_ica_channels{s  r)fasticarpicardc@sReZdZdZedddddddddddZd d Zd d Zd dZedddZ ddZ ddZ ddZ ddZ dddZddZd d!Zd"d#Zd$d%Zd&d'Zdd(d)Zd*d+Zd,d-Zd.d/Zd0d1Zdd2d3Zd4d5Zd6d7Zd8d9Zd:d;Zedd=d>Zdd?d@ZddDdEZ ddGdHZ!eddLdMZ"eddOdPZ#eddTdUZ$eddXdYZ%eddZd[Z&d\d]Z'd^d_Z(d`daZ)dbdcZ*dddeZ+edddfdgdhZ,didjZ-e.e/dddkdddldddddmdne0ddddddddfdodpZ1e.e2dddqdrdsZ3e.e4ddddudvdwZ5e.e6ddydzZ7e.e8dd{d|Z9edd}d~Z:dS)rZa0Data decomposition using Independent Component Analysis (ICA). This object estimates independent components from :class:`mne.io.Raw`, :class:`mne.Epochs`, or :class:`mne.Evoked` objects. Components can optionally be removed (for artifact repair) prior to signal reconstruction. .. warning:: ICA is sensitive to low-frequency drifts and therefore requires the data to be high-pass filtered prior to fitting. Typically, a cutoff frequency of 1 Hz is recommended. Parameters ---------- n_components : int | float | None Number of principal components (from the pre-whitening PCA step) that are passed to the ICA algorithm during fitting: - :class:`int` Must be greater than 1 and less than or equal to the number of channels. - :class:`float` between 0 and 1 (exclusive) Will select the smallest number of components required to explain the cumulative variance of the data greater than ``n_components``. Consider this hypothetical example: we have 3 components, the first explaining 70%%, the second 20%%, and the third the remaining 10%% of the variance. Passing 0.8 here (corresponding to 80%% of explained variance) would yield the first two components, explaining 90%% of the variance: only by using both components the requested threshold of 80%% explained variance can be exceeded. The third component, on the other hand, would be excluded. - ``None`` ``0.999999`` will be used. This is done to avoid numerical stability problems when whitening, particularly when working with rank-deficient data. Defaults to ``None``. The actual number used when executing the :meth:`ICA.fit` method will be stored in the attribute ``n_components_`` (note the trailing underscore). .. versionchanged:: 0.22 For a :class:`python:float`, the number of components will account for *greater than* the given variance level instead of *less than or equal to* it. The default (None) will also take into account the rank deficiency of the data. noise_cov : None | instance of Covariance Noise covariance used for pre-whitening. If None (default), channels are scaled to unit variance ("z-standardized") as a group by channel type prior to the whitening by PCA. %(random_state)s method : 'fastica' | 'infomax' | 'picard' The ICA method to use in the fit method. Use the ``fit_params`` argument to set additional parameters. Specifically, if you want Extended Infomax, set ``method='infomax'`` and ``fit_params=dict(extended=True)`` (this also works for ``method='picard'``). Defaults to ``'fastica'``. For reference, see :footcite:`Hyvarinen1999,BellSejnowski1995,LeeEtAl1999,AblinEtAl2018`. fit_params : dict | None Additional parameters passed to the ICA estimator as specified by ``method``. Allowed entries are determined by the various algorithm implementations: see :class:`~sklearn.decomposition.FastICA`, :func:`~picard.picard`, :func:`~mne.preprocessing.infomax`. max_iter : int | 'auto' Maximum number of iterations during fit. If ``'auto'``, it will set maximum iterations to ``1000`` for ``'fastica'`` and to ``500`` for ``'infomax'`` or ``'picard'``. The actual number of iterations it took :meth:`ICA.fit` to complete will be stored in the ``n_iter_`` attribute. allow_ref_meg : bool Allow ICA on MEG reference channels. Defaults to False. .. versionadded:: 0.18 %(verbose)s Attributes ---------- current_fit : str Flag informing about which data type (raw or epochs) was used for the fit. ch_names : list-like Channel names resulting from initial picking. n_components_ : int If fit, the actual number of PCA components used for ICA decomposition. pre_whitener_ : ndarray, shape (n_channels, 1) or (n_channels, n_channels) If fit, array used to pre-whiten the data prior to PCA. pca_components_ : ndarray, shape ``(n_channels, n_channels)`` If fit, the PCA components. pca_mean_ : ndarray, shape (n_channels,) If fit, the mean vector used to center the data before doing the PCA. pca_explained_variance_ : ndarray, shape ``(n_channels,)`` If fit, the variance explained by each PCA component. mixing_matrix_ : ndarray, shape ``(n_components_, n_components_)`` If fit, the whitened mixing matrix to go back from ICA space to PCA space. It is, in combination with the ``pca_components_``, used by :meth:`ICA.apply` and :meth:`ICA.get_components` to re-mix/project a subset of the ICA components into the observed channel space. The former method also removes the pre-whitening (z-scaling) and the de-meaning. unmixing_matrix_ : ndarray, shape ``(n_components_, n_components_)`` If fit, the whitened matrix to go from PCA space to ICA space. Used, in combination with the ``pca_components_``, by the methods :meth:`ICA.get_sources` and :meth:`ICA.apply` to unmix the observed data. exclude : array-like of int List or np.array of sources indices to exclude when re-mixing the data in the :meth:`ICA.apply` method, i.e. artifactual ICA components. The components identified manually and by the various automatic artifact detection methods should be (manually) appended (e.g. ``ica.exclude.extend(eog_inds)``). (There is also an ``exclude`` parameter in the :meth:`ICA.apply` method.) To scrap all marked components, set this attribute to an empty list. %(info)s n_samples_ : int The number of samples used on fit. labels_ : dict A dictionary of independent component indices, grouped by types of independent components. This attribute is set by some of the artifact detection functions. n_iter_ : int If fit, the number of iterations required to complete ICA. Notes ----- .. versionchanged:: 0.23 Version 0.23 introduced the ``max_iter='auto'`` settings for maximum iterations. With version 0.24 ``'auto'`` will be the new default, replacing the current ``max_iter=200``. .. versionchanged:: 0.23 Warn if `~mne.Epochs` were baseline-corrected. .. note:: If you intend to fit ICA on `~mne.Epochs`, it is recommended to high-pass filter, but **not** baseline correct the data for good ICA performance. A warning will be emitted otherwise. A trailing ``_`` in an attribute name signifies that the attribute was added to the object during fitting, consistent with standard scikit-learn practice. ICA :meth:`fit` in MNE proceeds in two steps: 1. :term:`Whitening ` the data by means of a pre-whitening step (using ``noise_cov`` if provided, or the standard deviation of each channel type) and then principal component analysis (PCA). 2. Passing the ``n_components`` largest-variance components to the ICA algorithm to obtain the unmixing matrix (and by pseudoinversion, the mixing matrix). ICA :meth:`apply` then: 1. Unmixes the data with the ``unmixing_matrix_``. 2. Includes ICA components based on ``ica.include`` and ``ica.exclude``. 3. Re-mixes the data with ``mixing_matrix_``. 4. Restores any data not passed to the ICA algorithm, i.e., the PCA components between ``n_components`` and ``n_pca_components``. ``n_pca_components`` determines how many PCA components will be kept when reconstructing the data when calling :meth:`apply`. This parameter can be used for dimensionality reduction of the data, or dealing with low-rank data (such as those with projections, or MEG data processed by SSS). It is important to remove any numerically-zero-variance components in the data, otherwise numerical instability causes problems when computing the mixing matrix. Alternatively, using ``n_components`` as a float will also avoid numerical stability problems. The ``n_components`` parameter determines how many components out of the ``n_channels`` PCA components the ICA algorithm will actually fit. This is not typically used for EEG data, but for MEG data, it's common to use ``n_components < n_channels``. For example, full-rank 306-channel MEG data might use ``n_components=40`` to find (and later exclude) only large, dominating artifacts in the data, but still reconstruct the data using all 306 PCA components. Setting ``n_pca_components=40``, on the other hand, would actually reduce the rank of the reconstructed data to 40, which is typically undesirable. If you are migrating from EEGLAB and intend to reduce dimensionality via PCA, similarly to EEGLAB's ``runica(..., 'pca', n)`` functionality, pass ``n_components=n`` during initialization and then ``n_pca_components=n`` during :meth:`apply`. The resulting reconstructed data after :meth:`apply` will have rank ``n``. .. note:: Commonly used for reasons of i) computational efficiency and ii) additional noise reduction, it is a matter of current debate whether pre-ICA dimensionality reduction could decrease the reliability and stability of the ICA, at least for EEG data and especially during preprocessing :footcite:`ArtoniEtAl2018`. (But see also :footcite:`Montoya-MartinezEtAl2017` for a possibly confounding effect of the different whitening/sphering methods used in this paper (ZCA vs. PCA).) On the other hand, for rank-deficient data such as EEG data after average reference or interpolation, it is recommended to reduce the dimensionality (by 1 for average reference and 1 for each interpolated channel) for optimal ICA performance (see the `EEGLAB wiki `_). Caveat! If supplying a noise covariance, keep track of the projections available in the cov or in the raw object. For example, if you are interested in EOG or ECG artifacts, EOG and ECG projections should be temporally removed before fitting ICA, for example:: >> projs, raw.info['projs'] = raw.info['projs'], [] >> ica.fit(raw) >> raw.info['projs'] = projs Methods currently implemented are FastICA (default), Infomax, and Picard. Standard Infomax can be quite sensitive to differences in floating point arithmetic. Extended Infomax seems to be more stable in this respect, enhancing reproducibility and stability of results; use Extended Infomax via ``method='infomax', fit_params=dict(extended=True)``. Allowed entries in ``fit_params`` are determined by the various algorithm implementations: see :class:`~sklearn.decomposition.FastICA`, :func:`~picard.picard`, :func:`~mne.preprocessing.infomax`. .. note:: Picard can be used to solve the same problems as FastICA, Infomax, and extended Infomax, but typically converges faster than either of those methods. To make use of Picard's speed while still obtaining the same solution as with other algorithms, you need to specify ``method='picard'`` and ``fit_params`` as a dictionary with the following combination of keys: - ``dict(ortho=False, extended=False)`` for Infomax - ``dict(ortho=False, extended=True)`` for extended Infomax - ``dict(ortho=True, extended=True)`` for FastICA Reducing the tolerance (set in ``fit_params``) speeds up estimation at the cost of consistency of the obtained results. It is difficult to directly compare tolerance levels between Infomax and Picard, but for Picard and FastICA a good rule of thumb is ``tol_fastica == tol_picard ** 2``. .. _eeglab_wiki: https://eeglab.org/tutorials/06_RejectArtifacts/RunICA.html#how-to-deal-with-corrupted-ica-decompositions References ---------- .. footbibliography:: NrautoF) noise_cov random_statemethod fit_paramsmax_iterrr@c st|tdt|tddf|dkr0td|t||_d|ffD]d\} } t| tr|d| krfdks|ntd| d| t| tr@| dkr@td | d| d q@d |_ ||_ d|_ d|_ d|_ ||_dkrit|d krd ddd} fdd| Dn|dkr(ddt|tdfdt|trptd|dd|d krbd}n|dkrpd}d|||_|_g|_d|_||_t|_||_dS)Nrzint-likeimported_eeglab n_componentsrr zaSelecting ICA components by explained variance needs values between 0.0 and 1.0 (exclusive), got =zSelecting one component with z is not supportedunfittedrparallelZlogcosh) algorithmZfunZfun_argscsi|]\}}|kr||qSrararekrrrarjrs z ICA.__init__..rextendedFrrwhen stri)rri)rCstrfloatrN_KNOWN_ICA_METHODSr isinstancerrP current_fitr_max_pca_componentsn_pca_componentsch_namesrrrr setdefaultrrrrrdictlabels_r) selfrrrrrrrr@kindvalrrarrj__init__~sV          z ICA.__init__c stGddd}jdkr"d}njdkr2d}nd}j}tdd}tdd}td d}td d}|dk r~tj}td d}|dk rj} | | } | d|}jdk r҇fd d t D} ng} j rfdd j D} ng} ||||||||| | d } | S)Nc@sveZdZUeeed<eed<eeed<eeed<eeed<eeed<eeed<eeed<eeed <d S) z.ICA._get_infos_for_repr.._InfosForReprfit_on fit_method fit_n_iter fit_n_samplesfit_n_componentsfit_n_pca_componentsfit_explained_variancech_typesexcludesN) ryrx __qualname__r r__annotations__intrr rarararj _InfosForReprs        rrrawzraw dataepochsn_iter_ n_samples_ n_components_pca_components_pca_explained_variance_csg|]}|kr|qSrara)recrrarjrksz+ICA._get_infos_for_repr..csg|]}j|qSra) _ica_namesreirrarjrks) rrrrrrrrr) rrrgetattrlenrrsumrrr)rrrrrrrrrZabs_varsZrel_varsrrZinfos_for_reprrarrj_get_infos_for_reprsJ           zICA._get_infos_for_reprcCs|}|jpdd|j}|jdk r|d|jd|jd|jdt|jdd d |jd d |j d t |j pxdd 7}d|dS)zICA fit information.noz decomposition, method: Nz (fit in z iterations on z samples), z ICA components explaining dr z % of variance (z+ PCA components available), channel types: , z sources marked for exclusionz) rrrrrrroundrrrwrrr)rinfossrararj__repr__s T z ICA.__repr__c CsPddlm}|}|d}|j|j|j|j|j|j |j |j |j |j d }|S)Nr)repr_templates_envzica.html.jinja) rrn_iter n_samplesrrZexplained_variancerr)Zhtml_templatesrrZ get_templaterenderrrrrrrrrr)rrrthtmlrararj _repr_html_ s   zICA._repr_html_@Tc  Cs$tddd} | D]&\} } |j| krt| dt| qt|ttfddt |j ddrht d t |tr|j d k rt d t |tsd d td||||fD}|rt dd|t|j |d|jd}t||j |jdt}|jdkr|t dt||jd k rL|jt|krLtd|jdt|dt|j ||_ |j dr|j g|j d<W5QRX|j d|_t |tr|||||||||| | n t |tst||||| t ||}|!d d d}t"||ddt}t d#|||S)a Run the ICA decomposition on raw data. Caveat! If supplying a noise covariance keep track of the projections available in the cov, the raw or the epochs object. For example, if you are interested in EOG or ECG artifacts, EOG and ECG projections should be temporally removed before fitting the ICA. Parameters ---------- inst : instance of Raw or Epochs The data to be decomposed. %(picks_good_data_noref)s This selection remains throughout the initialized ICA solution. start, stop : int | float | None First and last sample to include. If float, data will be interpreted as time in seconds. If ``None``, data will be used from the first sample and to the last sample, respectively. .. note:: These parameters only have an effect if ``inst`` is `~mne.io.Raw` data. decim : int | None Increment for selecting only each n-th sampling point. If ``None``, all samples between ``start`` and ``stop`` (inclusive) are used. reject, flat : dict | None Rejection parameters based on peak-to-peak amplitude (PTP) in the continuous data. Signal periods exceeding the thresholds in ``reject`` or less than the thresholds in ``flat`` will be removed before fitting the ICA. .. note:: These parameters only have an effect if ``inst`` is `~mne.io.Raw` data. For `~mne.Epochs`, perform PTP rejection via :meth:`~mne.Epochs.drop_bad`. Valid keys are all channel types present in the data. Values must be integers or floats. If ``None``, no PTP-based rejection will be performed. Example:: reject = dict( grad=4000e-13, # T / m (gradiometers) mag=4e-12, # T (magnetometers) eeg=40e-6, # V (EEG channels) eog=250e-6 # V (EOG channels) ) flat = None # no rejection based on flatness tstep : float Length of data chunks for artifact rejection in seconds. .. note:: This parameter only has an effect if ``inst`` is `~mne.io.Raw` data. %(reject_by_annotation_raw)s .. versionadded:: 0.14.0 %(verbose)s Returns ------- self : instance of ICA Returns the modified instance. Zsklearnr)rrz use method=instz Raw or EpochsZhighpasszThe data has not been high-pass filtered. For good ICA performance, it should be high-pass filtered (e.g., with a 1.0 Hz lower bound) before fitting ICA.NzThe epochs you passed to ICA.fit() were baseline-corrected. However, we suggest to fit ICA only on data that has been high-pass filtered, but NOT baseline-corrected.cSsg|]\}}|dk r|qSNra)re param_nameZ param_valrararjrkpszICA.fit..)startstoprejectflatzThe following parameters passed to ICA.fit() will be ignored, as they only affect raw data (and it appears you passed epochs): rF) allow_emptyZ with_ref_meg)rrzPFitting ICA to data using %i channels (please be patient, this may take a while)zica.n_components (z%) cannot be greater than len(picks) ()compsrcopyzFitting ICA took {:.1f}s.)$rrrrQreprrCr,r/rniscloserrIrbaselineziprwrrrrr_resetr=rrrr_unlockr_fit_rawr _fit_epochs_ica_explained_varianceargsort_sort_componentsformat)rrrrrdecimrrtstepreject_by_annotationr@Zreq_maprmodZignored_paramsZt_startvarZvar_ordZt_stoprararjfitsn@           zICA.fitcCs"dD]}t||rt||qdS) Aux method.) pre_whitener_unmixing_matrix_mixing_matrix_rrrr pca_mean_r drop_inds_reject_N)hasattrdelattr)rkeyrararjrs z ICA._resetc Cst|||\}}| rdnd} ||||| } |dk rJ| dddd|f} |dk sZ|dk rz||_t| ||||j|\} |_| jd|_|| d|S)romitNr r) _check_start_stopget_datarrArrshaper_fit) rrrrrr rrrrr@datarararjrs    z ICA._fit_rawcCs|jjdkrtd|j|dd|f}|dk rT|dddddd|f}|jd|jd|_t|}| |d|S)rrzITried to fit ICA with epochs, but none were found: epochs.events is "{}".Nrr) eventssize RuntimeErrorr rr rrnhstackr!)rrrr r@r"rararjrs   zICA._fit_epochscCs|j|dd}|jdkr|j}tt|dg}t|dgdD]\}}t||||<q>t|drt |dgd}t||||<t|d rt |dgd }t||||<n2t |j|j|jj d \}}|j d |j dkst ||_dS) r`z(pre-whitener computation) log_suffixNr F)rrrTr)rr)rr)_do_projrrrnemptyrrYstdr7rrrr rr)rr"r pre_whitenerrZpicks_rararj_compute_pre_whiteners&    zICA._compute_pre_whitenercCs|jdk r~|jdr~tdd|jdD|jddd\}}}|r~td|dt||r^d nd ||jdkr~||}|S) NprojscSsg|]}|dr|qS)Zactivera)reprararjrksz ICA._do_proj..rT)Zinclude_activez& Applying projection operator with z vector r.)rrr=rHr)rr"r(ZprojZnprojrrararjr)s " z ICA._do_projcCs2|j|dd}|jdkr$||j}n |j|}|S)Nz(pre-whitener application)r')r)rr)rr"rararj _pre_whitens    zICA._pre_whitencCst|j}|j\}}||||}t|jdd}||j}|j }|j }t |t rlt t||d}n|dkr|t|}t |t tjfst|jdkrd} t|t|dd|_nRt |jt rt||j\|_} |jdkrtdd | d d } nd } t|j|_|j|krt|} | | d } d | |jd|dg} td|jd|jd| ddd|j d|d| ddd td| |jf|j|_|j|_|j|_ ~|!|j dk r|j t|jkrt"d|j dt|jdt#d|j} |j$dkrXddl%m&} | fd|d|j'}|(|dd| f|j|_)|j*|_*n|j$dkrt+|dd| ff|dd|j'\}}||_)||_*~~n\|j$d krdd!l,m,}||dd| fjfdd|d"|j'\}}}}||_)|d|_*~~|j)j|jfd#kst|j }||dd$k}|d|j}||jdst-|dd d}t.d%|jd&|jd'|dd(d)|d d(d*| t/|}d+||dk<|j)|_)|0||_1dS),r`T)rwhitenrNz$Selecting by non-zero PCA componentsg !?r z;One PCA component captures most of the explained variance (rzL%), your threshold results in 1 component. You should select a higher value.zSelecting by explained variancezSelecting by numberrz n_components=z requires z PCA values (EV=z0.1fz%) but n_pca_components (z) results in only z components (EV=%)z%s: %s componentsn_pca_components (z0) is greater than the number of PCA components (rr)FastICAF)r3r)rzextended-infomax)r return_n_iterr)r)r3r7rrư>zUsing n_components=z (resulting in n_components_=zZ) may lead to an unstable mixing matrix estimation because the ratio between the largest (z0.2gz) and smallest (zZ) variances is too large (> 1e6); consider setting n_components=0.999999 or an integer <= ?)2rBrr r-r2rOrZ fit_transformTZexplained_variance_ratio_rrrr_exp_var_ncomprrnint_rrminrr%rFcumsumr=rZmean_rZ components_rZexplained_variance_r_update_ica_namesrslicerZsklearn.decompositionr6rrrrrrwhererIsqrt_update_mixing_matrixr)rr"Zfit_typerZ n_channelsrZpcaZuse_evZn_pcamsgevZevsselr6icaunmixing_matrixrrrWZnormsZstableZmax_intrararjr! s              :          6  zICA._fitcCsddlm}||j|_dS)Nrlinalg)rrKpinvrr)rrKrararjrCts zICA._update_mixing_matrixcCsddt|jD|_dS)z+Update ICA names when n_components_ is set.cSsg|] }d|qS)zICA%03dra)reiirararjrkzsz)ICA._update_ica_names..N)rangerrrrararjr?xszICA._update_ica_namescCsT||}|jdk r*||jdddf8}t|j|jd|j}t||}|S)z-Compute sources from data (operates inplace).N)r2rrndotrrr)rr"Zpca_datasourcesrararj _transform|s   zICA._transformcCsRt|dstdt|||\}}||}|r4dnd}|||||}||S)zTransform raw data.r!No fit available. Please fit ICA.rN)rr%r _get_picksrrQ)rrrrrrrr"rararj_transform_raws   zICA._transform_rawcCsbt|dstd||}t|dd|f}||}|s^tt|t |j d}|S)rrrRNr ) rr%rSrnr&rrQrosplitrr#)rr concatenaterr"rPrararj_transform_epochss   zICA._transform_epochscCs,t|dstd||}||j|S)rrrR)rr%rSrQr")revokedrrararj_transform_evokeds  zICA._transform_evokedcCst|j|jgdd}t|t|jkrt|tr:d\}}n0t|trNd\}}nt|trbd\}}ntdt d||t|jt||f|S)z!Pick logic for _transform method.T)rr)Rawdoesn't)Epochszdon't)rr[0Data input must be of Raw, Epochs or Evoked typezu%s %s match fitted data: %i channels fitted but %i channels supplied. Please provide %s compatible with ica.ch_names) rrrrrr,r/rrr%)rrrrdorararjrSs(      zICA._get_pickscCs0t|jddd|jfj|jd|jjS)zGet ICA topomap for components as numpy arrays. Returns ------- components : array, shape (n_channels, n_components) The ICA components (maps). N)rnrOrrr:rrrararjget_componentsszICA.get_componentscCst|tr4t|j|jdd|jd|||||}njt|trft|j|jdd|jd|||d}n8t|trt|j|jdd|jd| ||}nt d|S)aEstimate sources given the unmixing matrix. This method will return the sources in the container format passed. Typical usecases: 1. pass Raw object to use `raw.plot ` for ICA sources 2. pass Epochs object to compute trial-based statistics in ICA space 3. pass Evoked object to investigate time-locking in ICA space Parameters ---------- inst : instance of Raw, Epochs or Evoked Object to compute sources from and to represent sources in. add_channels : None | list of str Additional channels to be added. Useful to e.g. compare sources with some reference. Defaults to None. start : int | float | None First sample to include. If float, data will be interpreted as time in seconds. If None, the entire data will be used. stop : int | float | None Last sample to not include. If float, data will be interpreted as time in seconds. If None, the entire data will be used. Returns ------- sources : instance of Raw, Epochs or Evoked The ICA sources time series. rZrZrr\Frr]) rr,rLrr_sources_as_rawr/_sources_as_epochsr_sources_as_evokedr)rr add_channelsrrrPrararj get_sourcess"   zICA.get_sourcesc Cs t|||\}}|j|||d}|jd||ks6t|j}|jrR|j}d|_|`z,|||jd|d|jd}W5|rd|_||_X|dk rt |rt |j |} t ||j| ||dg}||_|jg|_|jg|_dg|_d|_d|_||j|||S)rrrr FTsfreqN)rrTr rpreload_datarcroprrrrrnrVr first_sampZ _first_sampsZ last_sampZ _last_sampsZ _filenames _projector _export_info) rrrdrrZdata_Z preloadedr"outrrararjras<    zICA._sources_as_rawcs}||}|dk r0fdd|D}ng}t|dkrbtj|dd|fgddn||_||j|d|_ d|_ d|_ |S)rNcsg|]}j|qSrarindexrerrrarjrk sz*ICA._sources_as_epochs..rr ZaxisT) rrWrrnrVrrirmrrh_rawrl)rrrdrVrnrPrrarrrjrbs   zICA._sources_as_epochscsr|dk rfdd|D}ng}|}t|dkrLtj|j|f}n|}}||_||j||S)rNcsg|]}j|qSrarorqrXrarjrk0sz*ICA._sources_as_evoked..r )rYrrnZr_r"rrmr)rrXrdrrPr"rnrarurjrc-s  zICA._sources_as_evokedcsgg}t|jD]P\}}||t|d|dtjtjtjtjt j dddd|ddd qdk r7|fd d |j d D7}|j d d d .||d <fdd |j D|d<g|d<W5QRXdS)rr Zf4Zdtyper9r) ch_namecalZlognoZ coil_typerZ coord_frameunitlocrNZscannoZunit_mulNcsg|]}|dkr|qS)rxrarq)rdrarjrkSs z$ICA._export_info..rT)Zupdate_redundantZ check_aftercsg|] }|qSrararqr`rarjrkWsbadsr/) enumeraterappendrr+ZFIFFV_COIL_NONEZ FIFFV_MISC_CHZFIFFV_COORD_UNKNOWNZFIFF_UNIT_NONErnzerosrrr)rr containerrdZch_inforMnamera)rdrrjrm?s0   zICA._export_inforc Cst|tr4t|j|jdd|jd|||||} nht|trft|j|jdd|jd|j|dd} n6t|trt|j|jdd|jd| |} nt d|d k r| |||||}| j d |j d krt d t|trt || |||\} }t| ||} | S) a@Assign score to components based on statistic or metric. Parameters ---------- inst : instance of Raw, Epochs or Evoked The object to reconstruct the sources from. target : array-like | str | None Signal to which the sources shall be compared. It has to be of the same shape as the sources. If str, a routine will try to find a matching channel name. If None, a score function expecting only one input-array argument must be used, for instance, scipy.stats.skew (default). score_func : callable | str Callable taking as arguments either two input arrays (e.g. Pearson correlation) or one input array (e. g. skewness) and returns a float. For convenience the most common score_funcs are available via string labels: Currently, all distance metrics from scipy.spatial and All functions from scipy.stats taking compatible input arguments are supported. These function have been modified to support iteration over the rows of a 2D array. start : int | float | None First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample. stop : int | float | None Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample. l_freq : float Low pass frequency. h_freq : float High pass frequency. %(reject_by_annotation_all)s .. versionadded:: 0.14.0 %(verbose)s Returns ------- scores : ndarray Scores for each source as returned from score_func. rZrZr`r\T)rVrr]Nrz>Sources and target do not have the same number of time slices.)rr,rLrrrTr/rWrrYr _check_targetr _band_pass_filter _find_sources) rrtargetrvrrl_freqh_freqrr@rPscoresrararj score_sourcesZs>-        zICA.score_sourcescCst|trr|rdnd}t|||\}}t|drL|jdkrL|d|jd}t|trt||}| ||||}nt|t rt|trt||}| dd|f}t|dr|jdkrt |jdkr| }n(t|t rt|trt||}|j|}|S)z Aux Method.rNndimrr r)rr,rrrreshaper r_get_target_chrr/r=rcrr")rrrrrrpickrararjrs*               zICA._check_target@rzscorec  sgg} fdd|D} g} |D]8}t|tsZ| dkrN| dqd| | q,| |q,tt| | D]\}\}}j|d||dg7| dkrtd|d }n2| d krtt d|kd }nt d | | |g7} t |j d | |f|<qttfddt| D}t| t |ddd}t t|}g} |D]$}||krf| |||qftdkrd t | }|fS)znCompute ExG/ref components. See find_bads_ecg, find_bads_eog, and find_bads_ref for details. c sg|]}|qSra)rr)rrrrrrarjrksz%ICA._find_bads_ch..ecgECG-MAGr)rrvrrrrrrr threshold correlationrzUnknown measure {}z%s/%i/csg|]\}}||qSrara)rerMinds)rrarjrksNr )rrr~r}rrrVrnrAabsrr listrrVr rremover)rrrrrrrrrprefixmeasureidxtargetsZ target_namesrrMrZthis_idxZscores_Zidx_Z idx_uniquerlabelsra)rrrrrrrj _find_bads_chsV       "  zICA._find_bads_chcCs|jd}tddd}t|ddt|}dd||ddtd||d}|tt|d | S) aHAutomatically decide the threshold of Kuiper index for CTPS method. This function finds the threshold of Kuiper index based on the threshold of pk. Kuiper statistic that minimizes the difference between pk and the pk threshold (defaults to 20 :footcite:`DammersEtAl2008`) is returned. It is assumed that the data are appropriately filtered and bad data are rejected at least based on peak-to-peak amplitude when/before running the ICA decomposition on data. References ---------- .. footbibliography:: rgr rgףp= ?gQ?r )rrnarangemathrBexpZargminr)rZ pk_thresholdNZVsCZPksrararj_get_ctps_thresholds  .zICA._get_ctps_thresholdrWc  Cst|tdfdt|tr*td|dddt|tdtd|dt| tdtd| d t||} | d krt|||| d \} }n |j| } |d kr|d kr|}t d|t|t r| t ||||d| d }|jddkrtdn$t|tr| | }ntdt|\}}}|d}t||kd}|t||d d d}t||jd<|d kr~d}t||jd|<nf|dkr|d kr| dkrd}n|d kr| dkrd}|j|| g|||||d| | d \|jd<}|jd|fS)a Detect ECG related components. Cross-trial phase statistics :footcite:`DammersEtAl2008` or Pearson correlation can be used for detection. .. note:: If no ECG channel is available, routine attempts to create an artificial ECG based on cross-channel averaging. Parameters ---------- inst : instance of Raw, Epochs or Evoked Object to compute sources from. ch_name : str The name of the channel to use for ECG peak detection. The argument is mandatory if the dataset contains no ECG channels. threshold : float | 'auto' Value above which a feature is classified as outlier. See Notes. .. versionchanged:: 0.21 start : int | float | None First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample. When working with Epochs or Evoked objects, must be float or None. stop : int | float | None Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample. When working with Epochs or Evoked objects, must be float or None. l_freq : float Low pass frequency. h_freq : float High pass frequency. method : 'ctps' | 'correlation' The method used for detection. If ``'ctps'``, cross-trial phase statistics :footcite:`DammersEtAl2008` are used to detect ECG-related components. See Notes. %(reject_by_annotation_all)s .. versionadded:: 0.14.0 %(measure)s %(verbose)s Returns ------- ecg_idx : list of int The indices of ECG-related components. scores : np.ndarray of float, shape (``n_components_``) If method is 'ctps', the normalized Kuiper index scores. If method is 'correlation', the correlation scores. See Also -------- find_bads_eog, find_bads_ref, find_bads_muscle Notes ----- The ``threshold``, ``method``, and ``measure`` parameters interact in the following ways: - If ``method='ctps'``, ``threshold`` refers to the significance value of a Kuiper statistic, and ``threshold='auto'`` will compute the threshold automatically based on the sampling frequency. - If ``method='correlation'`` and ``measure='correlation'``, ``threshold`` refers to the Pearson correlation value, and ``threshold='auto'`` sets the threshold to 0.9. - If ``method='correlation'`` and ``measure='zscore'``, ``threshold`` refers to the z-score value (i.e., standard deviations) used in the iterative z-scoring method, and ``threshold='auto'`` sets the threshold to 3.0. References ---------- .. footbibliography:: numericrrrextrar)rWrrrrN)rrWrz,Using threshold: %.2f for CTPS ECG detectionF)rrZkeep_ecgrrzANo ECG activity detected. Consider changing the input parameters.z2With `ctps` only Raw and Epochs input is supportedrrrzecg/%srrr?rrrrrrrr)rCrrrNr rrrr=rr,rerrr rIr/rrWmaxrnrArr rrr)rrrxrrrrrrrrr@Zidx_ecgrtimesrPrZp_valsrZecg_idxrararj find_bads_ecgsvO                 zICA.find_bads_ecgtogetherc  st|tdfdt|tr*td|dddt| tdtd| dt| tdtd| d | d kr|d krx| d krxd }n|d kr| dkrd}|stjd} n tj|} t| } | stdfdd| D} |j | |||||d|| d \|j d<}n| dkr|d krd }| d kr.t d| dt |j ddd}t |j ddd}t|rbt|sjtd|}tjj||ddtjj||dd}t|}tt||dd |j d<|j d|fS)!a(Detect MEG reference related components using correlation. Parameters ---------- inst : instance of Raw, Epochs or Evoked Object to compute sources from. Should contain at least one channel i.e. component derived from MEG reference channels. ch_name : list of str Which MEG reference components to use. If None, then all channels that begin with REF_ICA. threshold : float | str Value above which a feature is classified as outlier. - If ``measure`` is ``'zscore'``, defines the threshold on the z-score used in the iterative z-scoring method. - If ``measure`` is ``'correlation'``, defines the absolute threshold on the correlation between 0 and 1. - If ``'auto'``, defaults to 3.0 if ``measure`` is ``'zscore'`` and 0.9 if ``measure`` is ``'correlation'``. .. warning:: If ``method`` is ``'together'``, the iterative z-score method is always used. start : int | float | None First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample. stop : int | float | None Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample. l_freq : float Low pass frequency. h_freq : float High pass frequency. %(reject_by_annotation_all)s method : 'together' | 'separate' Method to use to identify reference channel related components. Defaults to ``'together'``. See notes. .. versionadded:: 0.21 %(measure)s %(verbose)s Returns ------- ref_idx : list of int The indices of MEG reference related components, sorted by score. scores : np.ndarray of float, shape (``n_components_``) | list of array The correlation scores. See Also -------- find_bads_ecg, find_bads_eog, find_bads_muscle Notes ----- ICA decomposition on MEG reference channels is used to assess external magnetic noise and remove it from the MEG. Two methods are supported: With the ``'together'`` method, only one ICA fit is used, which encompasses both MEG and reference channels together. Components which have particularly strong weights on the reference channels may be thresholded and marked for removal. With ``'separate'`` selected components from a separate ICA decomposition on the reference channels are used as a ground truth for identifying bad components in an ICA fit done on MEG channels only. The logic here is similar to an EOG/ECG, with reference components replacing the EOG/ECG channels. Recommended procedure is to perform ICA separately on reference channels, extract them using :meth:`~mne.preprocessing.ICA.get_sources`, and then append them to the inst using :meth:`~mne.io.Raw.add_channels`, preferably with the prefix ``REF_ICA`` so that they can be automatically detected. With ``'together'``, thresholding is based on adaptative z-scoring. With ``'separate'``: - If ``measure`` is ``'zscore'``, thresholding is based on adaptative z-scoring. - If ``measure`` is ``'correlation'``, threshold defines the absolute threshold on the correlation between 0 and 1. Validation and further documentation for this technique can be found in :footcite:`HannaEtAl2020`. .. versionadded:: 0.18 References ---------- .. footbibliography:: rrrrrr)rseparaterrrrrrrrzREF_ICA*zNo valid channels available.csg|]}j|qSrar`rqrrarjrksz%ICA.find_bads_ref..rrrzVWith method 'together', only 'zscore' measure issupported. Using 'zscore' instead of 'z'.TF)megrz:ICA solution must contain both reference and MEG channels.rrsr )rtail)rCrrrNrXrrrrrrr=rranyr_rnrKnormlogrV)rrrxrrrrrrrrr@rZref_chsrZ meg_picks ref_picksweightsZnormratsrarrj find_bads_refsj`           zICA.find_bads_ref?-c sddlm} m} tdd|j|||d} |} t|trBtnt } | | ||dd\}}t t |t |j dd}t| t jt| dd }t|jd |d }|jd| jdkst||jdd 8}t jj|dd }||}t ||}t | jdf}| | |}d||}t| j D]D\}}| | |d d t jf}||}t ||||<q,ddt |d  dddt |d ddddt |d d}fddt|D|jd<|jd|fS)aDetect muscle related components. Detection is based on :footcite:`DharmapraniEtAl2016` which uses data from a subject who has been temporarily paralyzed :footcite:`WhithamEtAl2007`. The criteria are threefold: 1) Positive log-log spectral slope from 7 to 45 Hz 2) Peripheral component power (farthest away from the vertex) 3) A single focal point measured by low spatial smoothness The threshold is relative to the slope, focal point and smoothness of a typical muscle-related ICA component. Note the high frequency of the power spectral density slope was 75 Hz in the reference but has been modified to 45 Hz as a default based on the criteria being more accurate in practice. Parameters ---------- inst : instance of Raw, Epochs or Evoked Object to compute sources from. threshold : float | str Value above which a component should be marked as muscle-related, relative to a typical muscle component. start : int | float | None First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample. stop : int | float | None Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample. l_freq : float Low frequency for muscle-related power. h_freq : float High frequency for msucle related power. %(sphere_topomap_auto)s %(verbose)s Returns ------- muscle_idx : list of int The indices of EOG related components, sorted by score. scores : np.ndarray of float, shape (``n_components_``) | list of array The correlation scores. See Also -------- find_bads_ecg, find_bads_eog, find_bads_ref Notes ----- .. versionadded:: 1.1 r)pdist squareformrrrfmisc)ZfminZfmaxrr rsr")rsphereNrg?g?g?i,rcs g|]\}}|dkr|qS)rra)rerZscorerrarjrks z(ICA.find_bads_muscle..muscle)Zscipy.spatial.distancerrrCrer_rr,r9r:rnZpolyfitlog10r:rrr8rr rZmeanrKrrOrr}newaxismultiplyrrr)rrrrrrrrr@rrrP componentsZpsd_funcZpsdsZfreqsZslopesZcomponents_normposdistsZ focus_distsZ smoothnessesrcompZ comp_distsrrarrjfind_bads_muscle6s86       zICA.find_bads_muscler rc  st|tdfdt|tr*td|dddt| tdtd| dt|} fdd | D} |d krt| d krtd }n|d kr| d krd}|j| |||||d|| d \|jd<} |jd| fS)a7Detect EOG related components using correlation. Detection is based on Pearson correlation between the filtered data and the filtered EOG channel. Thresholding is based on adaptive z-scoring. The above threshold components will be masked and the z-score will be recomputed until no supra-threshold component remains. Parameters ---------- inst : instance of Raw, Epochs or Evoked Object to compute sources from. ch_name : str The name of the channel to use for EOG peak detection. The argument is mandatory if the dataset contains no EOG channels. threshold : float | str Value above which a feature is classified as outlier. - If ``measure`` is ``'zscore'``, defines the threshold on the z-score used in the iterative z-scoring method. - If ``measure`` is ``'correlation'``, defines the absolute threshold on the correlation between 0 and 1. - If ``'auto'``, defaults to 3.0 if ``measure`` is ``'zscore'`` and 0.9 if ``measure`` is ``'correlation'``. start : int | float | None First sample to include. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample. stop : int | float | None Last sample to not include. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample. l_freq : float Low pass frequency. h_freq : float High pass frequency. %(reject_by_annotation_all)s .. versionadded:: 0.14.0 %(measure)s %(verbose)s Returns ------- eog_idx : list of int The indices of EOG related components, sorted by score. scores : np.ndarray of float, shape (``n_components_``) | list of array The correlation scores. See Also -------- find_bads_ecg, find_bads_ref rrrrrrrcsg|]}j|qSrar`rqrrarjrksz%ICA.find_bads_eog..rrrrrrr)rCrrrNrrr)rrrxrrrrrrrr@Zeog_indsZeog_chsrrarrj find_bads_eogs09    zICA.find_bads_eogc Cst|tttfddt|||d}t|trJd|j} } |j|||dn= n_components_ (z-) and <= the total number of PCA components (z).z Transforming to ICA space (z componentrz Zeroing out z ICA componentrz Projecting back using z PCA componentrg+=)Zrcond)rr2r_check_n_pca_componentsr rrrr=rrHrrnrrZ setdiff1drrrreyerOr:rVrrrKrL)rr"rrr _n_pca_compn_chrmax_pca_componentsZsel_keepZn_zeropca_componentsZunmixingZmixingZproj_matrararjrzsd                 0$    zICA._pick_sources) overwriter@c CsZ|jdkrtdt|ddt||d}td|t|}t||W5QRX|S)aStore ICA solution into a fiff file. Parameters ---------- fname : str The absolute path of the file name to save the ICA solution into. The file name should end with -ica.fif or -ica.fif.gz. %(overwrite)s .. versionadded:: 1.0 %(verbose)s Returns ------- ica : instance of ICA The object. See Also -------- read_ica rz&No fit available. Please first fit ICArZz-ica.fifz -ica.fif.gzz_ica.fifz _ica.fif.gz)rzWriting ICA solution to %s...)rr%r>r?r=rr; _write_ica)rfnamerr@fidrararjsaves    zICA.savecCst|S)z{Copy the ICA object. Returns ------- ica : instance of ICA The copied object. rrrararjrszICA.copy@ZRdBu_rheadcCs4t|||||||||| | | | | ||||||||dS)N)rch_typeresvminvmaxcmapsensorscolorbartitleshowoutlinescontours image_interprplot_std topomap_args image_argspsd_argsrrr@)r0)rrrrrrrrrrrrrrrrrrrrrr@rararjplot_componentss*zICA.plot_componentsr@cCs&t|||||||||| | | | | |dS)N) raxesdBr log_scalerrrfigsizerrrr@r4)rrrrrrrrrrrrrrr@rararjplot_propertiess zICA.plot_propertiesr)theme overview_modec Cs&t|||||||||| | | | | |dS)N)rrrrrrblockshow_first_sampshow_scrollbars time_format precompute use_openglrr)r2)rrrrrrrrrrr r r rrrararj plot_sourcesszICA.plot_sourcesICA component scoresc Cst|||||||||d S)N) rGrrraxhlinerrn_colsr)r1) rrrrrrrrrrararj plot_scores szICA.plot_scoresc Cst|||||||||d S)N)rrrrrrrr)r3) rrrrrrrrrrararj plot_overlay)s zICA.plot_overlayc Cs~t|trFt|j|\}}td|dd|dd|d|}n4|dkrj|j}|dkrz|jjd}n||j krz|j }|S)r`z Selected z' PCA components by explained variance (ru≥r4Nr) rrr;rr=rrrr r)rrr@rrErararjr0s & zICA._check_n_pca_components)N) NNNNNNrTN)r.)F)NNN)NrNNNNTN)F)rNNNNTrr)r) NrNNrrrWTrN) NrNNNNTrrN)rNNrrNN) NrNNr rTrN)NNNNNN) NNTTFNNNNTrT) NNNNTFFTrNN)NNNr NNT)NNNNNTN)N);ryrxrrzr@rrrrrrrrr-r)r2r!rCr?rQrTrWrYrSr_rerarbrcrmrrrrrrrrrrrrrrrrrGr0rrr5rr2r r1rr3rrrarararjrZsll=<   i   .' P  9    a L NH"     rZcCsNtj|tjd}|}||d}t||kdt|}|||dfS)Nrwrr )rnasarrayfloat64r>r=rr)rrZcvarrararjr;Cs  r;c Csvt}|df||jffD]X\}}|dkr4||qz|t|Wqtk rn|||dYqXq|S)r`rN)rZn_timesr~rF TypeErrorZ time_as_index)rrrrnstZnone_rararjrLs rr#rc CsZtdt|jd|||||d}t|} tj||jt| |t | f}|S)aFind ECG peaks from one selected ICA source. Parameters ---------- raw : instance of Raw Raw object to draw sources from. ecg_source : ndarray ICA source resembling ECG to find peaks from. event_id : int The index to assign to found events. tstart : float Start detection after tstart seconds. Useful when beginning of run is noisy. l_freq : float Low pass frequency. h_freq : float High pass frequency. qrs_threshold : float | str Between 0 and 1. qrs detection threshold. Can also be "auto" to automatically choose the threshold that generates a reasonable number of heartbeats (40-160 beats / min). %(verbose)s Returns ------- ecg_events : array Events. ch_ECG : string Name of channel used. average_pulse : float. Estimated average pulse. z(Using ICA source to identify heart beatsrg)tstartZ thresh_valuerr) r=rr rcrrnZc_rkrones) rZ ecg_sourceevent_idrrrZ qrs_thresholdr@Z ecg_eventsZn_eventsrararjr[Zs$  r[rcCs&t|tj||||jd|jd}|S)aLocate EOG artifacts from one selected ICA source. Parameters ---------- raw : instance of Raw The raw data. eog_source : ndarray ICA source resembling EOG to find peaks from. event_id : int The index to assign to found events. l_freq : float Low cut-off frequency in Hz. h_freq : float High cut-off frequency in Hz. %(verbose)s Returns ------- eog_events : array Events. rg)rrrZ sampling_raterk)rrnrrrk)rZ eog_sourcerrrr@Z eog_eventsrararjr\s r\cCsdt|j|gd}t|jdddd}t|dkrBtt|t|}t|dkr`td||jf|S)r`)rFT)reegrrz%s not in channel list (%s))rrrrrrrr)rrrrrararjrs  rcCsLt|trt||}t|s,td||dk r>|||n||d}|S)r`z%s is not a valid score_func.Nr )rrr]getcallabler)rPrrvrrararjrs  rcCst|tstdt|tttfs*tdt||}t|trj|j\}}}| ddd |||f}|j\}}t j |j dddt j |ddd||d}|r|| }|S)aCheck variance accounted for by each component in supplied data. Parameters ---------- ica : ICA Instance of `mne.preprocessing.ICA`. inst : Raw | Epochs | Evoked Data to explain with ICA. Instance of Raw, Epochs or Evoked. normalize : bool Whether to normalize the variance. Returns ------- var : array Variance explained by each component. z*first argument must be an instance of ICA.zAsecond argument must an instance of either Raw, Epochs or Evoked.r rrrs)rrZrr,r/rrErer Z transposerrnrr)rGr normalizeZ source_dataZn_epochsZn_chanZn_samprrararjr s(       r Tcs|jtkst|r|}|jddf|_|jddf|_ttjrZt |j rvfdd|j D|_ |j D]"}fdd|j |D|j |<q|S)z/Change the order of components in ica solution.Ncsg|]}|qSrarpreZicorderrarjrksz$_sort_components..csg|]}|qSrar!r"r#rarjrk s) rrrrrrrrnndarrayrrrkeys)rGr$rrrar#rjr s  r ;:c Csg}|D]\}}t|r$|j}nlt|tr8t|}nXt|tr|D]D\}}t|trJt|dkrJt|dtt j frJdd|D||<qJt j j t fD]}t||r|j}q|||t|q ||S)r`rcSsg|] }t|qSra)rrrararjrk sz_serialize..)rrryrrrrrrrnintegerrandomZ RandomStaterr~jsondumpsrw) Zdict_ outer_sep inner_seprrvaluesubkeyZsubvalueclsrararj _serialize s"      r2cCs6i}||D]"}||d\}}t|||<q|S)z Aux Function.r )rUr+loads)Zstr_r-r.rnmappingrrrararj _deserialize s r5cCst|j|j|j|j|j|jd}|jdk r|t|t j t |t j |jddk rdt |t j |jdt||jt|t j t|t jt|t jt||jdk rt|t j|jt|dd}|dkrdnt|t|ddt|ddt|ddt|ddd }t|t jt|t|t j|jt|t j|jt|t j|j t|t j!|j"t|t j#|j$t%|t j&t'|j(t|t jdS) zWrite an ICA object. Parameters ---------- fid: file The file descriptor ica: The instance of ICA to write )rrrrrrNZmeas_idrrrrr)rrrrr))rrrrrrrrr#r+Z FIFFB_MEASr<Z FIFF_BLOCK_IDZFIFF_PARENT_BLOCK_IDr(r$ FIFFB_MNE_ICAr FIFF_MNE_ICA_INTERFACE_PARAMSr2rr!FIFF_MNE_ROW_NAMESrrFIFF_MNE_ICA_MISC_PARAMSrFIFF_MNE_ICA_WHITENERrFIFF_MNE_ICA_PCA_COMPONENTSrFIFF_MNE_ICA_PCA_MEANrFIFF_MNE_ICA_PCA_EXPLAINED_VARrFIFF_MNE_ICA_MATRIXrr"FIFF_MNE_ICA_BADSrr)rrGica_initrica_miscrararjr' sR             rcCst|ddtd|t|\}}}zt||dd\}}Wn"tk r`tdd}YnXt|tj}t |dkrt|d }t |dkr| td |d}|d D]}|j } |j } | tj krt|| } | j} q| tjkrt|| } | j} q| tjkrt|| } | j}q| tjkr6t|| } | j}q| tjkrTt|| } | j}q| tjkrrt|| } | j}q| tjkrt|| } | j}q| tjkrt|| } | j}q| tjkrt|| } | j}q| d d | |fD\} }| d}| d}| d}|dd}|tkr$|| d<| dtjkr>tdtddd}dd| D} tf| }||_| d|_!|dk rt"|t#st$%|}||_&|||_'|||_(|||_)|j*d|_+||_,|-|||_.|||_/|0|dkrgnt1||_2||_d|kr*|d|_3d|krL|d}|dk rL||_4d|kr`|d|_5d|krt|d|_6d|kr|d|_7td|S) a/Restore ICA solution from fif file. Parameters ---------- fname : str Absolute path to fif file containing ICA matrices. The file name should end with -ica.fif or -ica.fif.gz. %(verbose)s Returns ------- ica : instance of ICA The ICA estimator. rZrzReading %s ...T)Z clean_badszZCould not find the measurement info. Functionality requiring the info won't be available.Nr{zCould not find ICA data directorycSsg|] }t|qSra)r5rqrararjrk szread_ica..rrrrrrz0Reading whitener drawn from noise covariance ...zNow restoring ICA solution ...cSs |tjSr)astypernr)rqrararjr szread_ica..fcSs$i|]\}}|ttjkr||qSra)rSrZrrrararjr szread_ica..r(rrrrzReady.)8r>r=rr&r)rr%r+r6rcloserrr7r'r"r8r:r;r=r<r>r?r9poprrrryrrZrrUrrrPrnrrrrrr rrr?rrrCrrrrrrr)rr@rtreerrZica_dataZ my_ica_datadrrtagr@rr,rZpca_explained_varianceZpca_meanrHrrArrrrrrGrrararjr^p s                                                     r^Nodez name target score_func criterioncCs|dk rj|dk rjtdtddddddd}t||jd ||f|}td t||jd ||f|}n|dk sz|dk rtd ||fS) z%Optionally band-pass filter the data.Nz... filtering ICA sourcesz zero-doubleZ10sZhannrZfirwin2)ZphaseZ filter_lengthZ fir_windowZl_trans_bandwidthZh_trans_bandwidthZ fir_designrgz... filtering targetzMust specify both pass bands)r=rrrUr)rrPrrrr@kwrararjr s  rcsZfdd|D}dd|D}dd|D}dkrJfdd|D}nfdd|D}ddt||D}t|d krt|nd }d dt||D} d dt||D} t| d krgd d gfSt| d j} tt| } tt| } t| | D]\}}| || | |7} q| t| } | | 9} tt | d }| |||fS) z.cSsg|]}t|qSra)rnrrdrararjrk scSsg|]}t|qSra)rnsignrdrararjrk sr cs"g|]}tt|kdqS)r)rrnZnonzeroreZs_corrrrarjrk scsg|]}tt|dqS)r)rrVrMrrarjrk scSs"g|]\}}|D] }||qqSrarareZl_Zi_srrararjrk srcSs"g|]\}}|D] }||qqSrararNrararjrk scSs"g|]\}}|D] }||qqSrararNrararjrk s)r r) rrrnZmedianrr$r+rrZcorrcoef)all_mapsrrZ all_corrsZ abs_corrsZcorr_polarities max_corrsamZmedian_corr_with_targetZ polaritiesZmaxmapsZ newtargetZ std_of_mapsZ mean_of_mapsZmaxmapZpolarityZsim_i_ora)rrrj_find_max_corrs s2     rRrrrc st|tstdt|} | dkr*tdd}|dkrPtjddtjdd }d }d d |Dt|d kr|d|dd}n2|jdkrt|dj dkr|d}ntdd\}}|dkrR|rd t |d}||dj |d|||| | |t | dd}n.t|gdgdg||dd|| | |d| d }|jdd|jtt|t}d||f}tdkrt|fdd |D}|tdd |D\}}}tdkstdkrt|fdd |D}|tdd |D\}}}}dd td D\}}}}td!|~|dkrVtd"tt||D]\}\}}t|dkrt|dtjr|d}|d#k rtt t||j!"|t|j!|<|dkr:|#|$d#d#|fj%|#|gt||#|n,|d#k r0||j!kr0t|j!|<|&|qdt|dkrXtd$ntd%t'||f|dkrt|||||||| | || d& }||fSd#Sd#S)'aFind similar Independent Components across subjects by map similarity. Corrmap (Viola et al. 2009 Clin Neurophysiol) identifies the best group match to a supplied template. Typically, feed it a list of fitted ICAs and a template IC, for example, the blink for the first subject, to identify specific ICs across subjects. The specific procedure consists of two iterations. In a first step, the maps best correlating with the template are identified. In the next step, the analysis is repeated with the mean of the maps identified in the first stage. Run with ``plot`` and ``show`` set to ``True`` and ``label=False`` to find good parameters. Then, run with labelling enabled to apply the labelling in the IC objects. (Running with both ``plot`` and ``labels`` off does nothing.) Outputs a list of fitted ICAs with the indices of the marked ICs in a specified field. The original Corrmap website: www.debener.de/corrmap/corrmapplugin1.html Parameters ---------- icas : list of mne.preprocessing.ICA A list of fitted ICA objects. template : tuple | np.ndarray, shape (n_components,) Either a tuple with two elements (int, int) representing the list indices of the set from which the template should be chosen, and the template. E.g., if template=(1, 0), the first IC of the 2nd ICA object is used. Or a numpy array whose size corresponds to each IC map from the supplied maps, in which case this map is chosen as the template. threshold : "auto" | list of float | float Correlation threshold for identifying ICs If "auto", search for the best map by trying all correlations between 0.6 and 0.95. In the original proposal, lower values are considered, but this is not yet implemented. If list of floats, search for the best map in the specified range of correlation strengths. As correlation values, must be between 0 and 1 If float > 0, select ICs correlating better than this. If float > 1, use z-scoring to identify ICs within subjects (not in original Corrmap) Defaults to "auto". label : None | str If not None, categorised ICs are stored in a dictionary ``labels_`` under the given name. Preexisting entries will be appended to (excluding repeats), not overwritten. If None, a dry run is performed and the supplied ICs are not changed. ch_type : 'mag' | 'grad' | 'planar1' | 'planar2' | 'eeg' The channel type to plot. Defaults to 'eeg'. plot : bool Should constructed template and selected maps be plotted? Defaults to True. show : bool Show figures if True. %(outlines_topomap)s sensors : bool | str Add markers for sensor locations to the plot. Accepts matplotlib plot format string (e.g., 'r+' for red plusses). If True, a circle will be used (via .add_artist). Defaults to True. contours : int | array of float The number of contour lines to draw. If 0, no contours will be drawn. When an integer, matplotlib ticker locator is used to find suitable values for the contour thresholds (may sometimes be inaccurate, use array for accuracy). If an array, the values represent the levels for the contours. Defaults to 6. cmap : None | matplotlib colormap Colormap for the plot. If ``None``, defaults to 'Reds_r' for norm data, otherwise to 'RdBu_r'. %(sphere_topomap_auto)s %(verbose)s Returns ------- template_fig : Figure Figure showing the template. labelled_ics : Figure Figure showing the labelled ICs in all ICA decompositions. z`plot` must be of type `bool`FzNot all ICA instances have the same channel names. Corrmap requires all instances to have the same montage. Consider interpolating bad channels before running ICA.r.r<_rwgY@z ("auto")cSsg|]}|jqSra)r_r:)rerGrararjrk szcorrmap..rrr TzI`template` must be a length-2 tuple or an array the size of the ICA maps.)NNzTemplate from subj. {})r)rrrrrrrrTemplate)rrrrtemplaterg?)topzbNo component detected using when z-scoring threshold%s %s, consider using a more lenient thresholdcsg|]}t|qSrarRrer)rOrrarjrk scSsg|] }|dqS)rrarepathrararjrk scsg|]}t|qSrarXrY)rO new_targetrarjrk scSsg|] }|dqS)r rarZrararjrk scSsg|] }tqSra)r)rerrararjrk srz.Median correlation with constructed map: %0.3fz$Displaying selected ICs per subject.Nz(At least 1 IC detected for each subject.zENo maps selected for subject%s %s, consider a more liberal threshold.)rrrrr)(rboolrrRrnrrrrr r rrrr6rZsubplots_adjustZcanvasZdrawZ atleast_1drorrcr%ZargmaxrNr=rr}rr%rrrrextendr_r:r~rH)ZicasrVrlabelrZplotrrrrrrr@Z same_chansZthreshold_extraZ is_subjectZ template_figZ labelled_icsttlZ threshold_errpathsrZ median_corrrPZallmapsindicesZsubjsZnonesrMrGZmax_corrra)rOr\rrjcorrmap- sT                     rcrcCslddlm}t|d}t|\}}}||t|t|dt ddd|j j d}|j j d}t d|d } d | _|d | _d| _|| _t| j} t|j| kstt| df| _t| | _|j j d| kst|j j ||fkst|j |j } ||j} tj| | d d s&td| } t| dd\} }}| || _|| _||| _ || _!| "| #| S)a>Load ICA information saved in an EEGLAB .set file. Parameters ---------- fname : str Complete path to a .set EEGLAB file that contains an ICA object. %(verbose)s Returns ------- ica : instance of ICA An ICA object based on the information contained in the input file. rrJN icachansindr Frr)rrZeeglabrr8)ZrtolzMismatch between icawinv and icaweights @ icasphere from EEGLAB possibly due to ICA component removal, assuming icawinv is correct)Z full_matrices)$rrKr.r-Z set_montagerrnrrDrZ icaspherer Z icaweightsrZrrrrrrdrrrrrrLZicawinvZallcloserIrTrrrrrCr?)rr@rKrrZ eeg_montagerZrankrrGrZuseZ use_checkrrrrararjr_ s>   "          r_)F)F)rrrrrN)Nrr rN)F)T)r'r()r'r()N)N) rNrTTrTrNNN)inspectr collectionsrrrnumbersrr dataclassesrtypingr r rr+numpyrnrr r rrrrrZinfomax_rZcovrr.rrdefaultsrZio.pickrrrrrrZio.projrZio.writerr r!r"r#r$Zio.treer%Zio.openr&Zio.tagr'Z io.meas_infor(r)r*Z io.constantsr+Zio.baser,Zio.eeglab.eeglabr-r.rr/Zvizr0r1r2r3Zviz.icar5Z viz.topomapr6Zchannels.channelsr7Zchannels.layoutr8Ztime_frequencyr9r:r;r<utilsr=r>r?r@rArBrCrDrErFrGrHrIrJrKrLrMrNrOrPrQrRfixesrSrTfilterrUr|rVZctps_rWrXrY__all__r|rr]rrrZr;rr[r\rrr r r2r5rr^Z _ica_noderrRrcr_rarararj s                      `     @  2  (   I }  ' =