Aluode/PerceptionLabPortable
0
1o
2 '�Yiw� � @ s d dl mZ d dlZd dlZd dlZd dlmZ d dlmZ d dl m3Z4 d dl m Z m
Z
d dlmZmZmZ d dlmZ d d lmZ d d5lmZ d dlZd d lmZ d d lm Z d d
l m Z ddl m Z ddl!m"Z"m#Z#m$Z$ ddl%m&Z& ddl'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z.m/Z/ ddl0m1Z1 ddl2m3Z3 ddl4m5Z5 ddl6m7Z7m8Z8m9Z9m:Z:m;Z;m<Z<m=Z=m>Z> ddl?m@Z@ ddlAmBZBmCZC ddlDmEZEmFZFmGZG ddlHmIZI ddlJmKZK dd lLmMZM dd lNmOZO dd lPmQZQ dd lRmSZS dd lTmUZUmVZV dd!lWmXZXmYZYmZZZm[Z[m\Z\m]Z]m^Z^m_Z_m`Z`maZambZbmcZcmdZdmeZemfZfmgZgmhZhmiZimjZjmkZkmlZlmmZmmnZnmoZompZpmqZqmrZr dd"lsmtZtmuZumvZvmwZw dd#lxmyZy dd$lzm{Z{ d%d&l|m}Z} d%d'l~mZ d%d(l�m�Z�m�Z�m�Z�m�Z� d%d)l�m�Z�m�Z� d%d*l�m�Z� d+Z�dhd-d.�Z�d/hZ�d0d1� Z�dhd2d3�Z�d4Z�elG d5d6� d6e"��Z�d7d8� Z�d9d:� Z�eq ; < = > ? did@dA��Z�eq djdDdE��Z�dFdG� Z�dHdI� Z�dhdJdK�Z�dkdMdN�Z�dldQdR�Z�dldSdT�Z�dUdV� Z�eqdmdWdX��Z�edYdZ�Z�eqdmd[d\��Z�d]d^� Z�eq ? _dndLd,d`dadeGeFeEddLdLddb� dcdd��Z�eqd?dde�dfdg��Z�dS )o� )� annotationsN)�6namedtuple)�Sequence��deepcopy)� dataclass� is_dataclass)� Parameter�7isfunction� signature)�Integral)�time)�Literal)�stats)�distance)�expit� )�FIFF)�
ContainsMixin�read_meas_info�write_meas_info)� fiff_open)�_DATA_CH_TYPES_SPLIT�_contains_ch_type�_picks_by_type�
_picks_to_idx�
pick_channels�pick_channels_regexp� pick_info�8pick_types)�make_projector)�read_tag)�
dir_tree_find)� end_block�start_and_end_file� start_block�write_double_matrix�write_id� write_int�write_name_list� write_string)�_find_topomap_coords)�9Covariance�compute_whitener)�_BORDER_DEFAULT�_EXTRAPOLATE_DEFAULT�_INTERPOLATION_DEFAULT)�10BaseEpochs)�Evoked)� filter_data)� _safe_svd)�_get_html_template)�BaseRaw)�_check_load_mat� _get_info)�_PCA�Bunch� _check_all_same_channel_names�_check_ch_locs�_check_compensation_grade� _check_fname�_check_on_missing�
_check_option�_check_preload� _ensure_int�_get_inst_data� _on_missing�_pl�_reject_data_segments�_require_version�_validate_type� check_fname�check_random_state� compute_corr� copy_function_doc_to_method_doc�fill_doc�int_like�logger�pinv� repr_html�verbose�warn)�plot_ica_components�plot_ica_overlay�plot_ica_scores�plot_ica_sources��plot_ica_properties)�
_plot_corrmap� )�_find_outliers)�ctps)�_get_ecg_channel_index� _make_ecg�create_ecg_epochs� qrs_detector)�_find_eog_events�_get_eog_channel_index)�infomax)�ICA�ica_find_ecg_events�ica_find_eog_events�get_score_funcs�read_ica�read_ica_eeglabFc s2 |f� fdd� }d� d� j� jg�|_� j|_|S )�
Aux function.c sT �� fdd�| D �}t |�rt|d �rdd� |D �}|r(t�|�d d �df }|S )Nc s g | ] }� |�� � ��qS � )�ravel��.0�a)�func�yrl �E:\DocsHouse\542 percep lab latest\PerceptionLab\PerceptionLab_Portable\python_embed\Lib\site-packages\mne/preprocessing/ica.py�11<listcomp>v s z1_make_xy_sfunc.<locals>.sfunc.<locals>.<listcomp>r c S s g | ]}|j |jf�qS rl )Z statisticZpvalue)ro �orl rl rs rt x � )�lenr �np�array)�xrr � ndim_output�out�rq )rr rs �sfuncu s z _make_xy_sfunc.<locals>.sfunc�.�12score_func)�join�13__module__�__name__�__doc__)rq r{ r~ rl r} rs �_make_xy_sfuncr s r� Zsomersdc C s� t � } dd� tt��� D �}dd� tt��� D �}| �dd� |D �� |D ]!\}}dd� t|�j�� D �}|ddgkrF| �|t|d d14�i� q%d | v sMJ �| S ) zjGet the score functions.15 16 Returns17 -------18 score_funcs : dict19 The score functions.20 c S �2 g | ]\}}t |�r|�d �s|tvr||f�qS ��_�r21 �22startswith�23_BLOCKLIST�ro �n�frl rl rs rt � � ���z#get_score_funcs.<locals>.<listcomp>c S r� r� r� r� rl rl rs rt � r� c S s, i | ]\}}t |�jd dgkr|t|��qS )�u�v)r �24parametersr� r� rl rl rs �25<dictcomp>� s26 �z#get_score_funcs.<locals>.<dictcomp>c S s& g | ]\}}|j tjtjfv r|�qS rl )�kindr �POSITIONAL_ONLY�POSITIONAL_OR_KEYWORD)ro �name�paramrl rl rs rt � s 27��rz rr T)r{ �pearsonr) r: �varsr �itemsr �updater r� r� )Z score_funcsZxy_arg_dist_funcsZxy_arg_stats_funcsr� r� �paramsrl rl rs rh � s* 28�29��� � � rh c sd t d � � |r dnd7 � |j| ddd�}t� fdd�|D ��}|s0td t|�� d30|� d � � ���d S )
aE Check for channels in picks that are not considered valid channels.31 32 Accepted channels are the data channels33 ('seeg', 'dbs', 'ecog', 'eeg', 'hbo', 'hbr', 'mag', and 'grad'), 'eog'34 and 'ref_meg'.35 This prevents the program from crashing without36 feedback when a bad channel is provided to ICA whitening.37 )�eog)�ref_megrl TF��uniqueZ
only_data_chsc s g | ]}|� v �qS rl rl �ro �ch��typesrl rs rt � � z7_check_for_unsupported_ica_channels.<locals>.<listcomp>zInvalid channel typez passed for ICA: z).Only the following types are supported: N)r �get_channel_types�all�38ValueErrorrE )�picks�info�
allow_ref_meg�chs�checkrl r� rs �#_check_for_unsupported_ica_channels� s ���r� )�fasticard �picardc @ sh e Zd ZdZe d�dddddddd�dd��Zd d39� Zd d � Zed
d� �Z e d�dd��Z40dd� Z dd� Z dd� Z
dd� Zd�d d �Zd d � Zd d!� Zd"d#� Zd$d%� Zd&d'� Zd�d(d)�Zd*d+� Zd,d-� Zd.d/� Zd0d1� Zddd2�d3d4�Zd5d6� Zd�d7d8�Z d9d:� Z d;d<� Z d=d>� Z d?d@� Z e A d�dBdC��Z!d�dDdE�Z" F G Hd�dIdJ�Z#d�dLdM�Z$e N O P H d�dQdR��Z%e F S H d�dTdU��Z&e V W X d�dYdZ��Z'e F [ \ H d�d]d^��Z(e d�d_dd`�dadb��Z)dcdd� Z*dedf� Z+dgdh� Z,didj� Z-dkdl� Z.edddm�dndo��Z/dpdq� Z0e1e2� dvddddddrdsde3e4e5dtd[dudvdddwdddddddddx�dydz��Z6e1e7� d�d{dd|�d}d~��Z8e1e9� d�d�ddddd��d�d���Z:e1e;� � d�d�d���Z<e1e=� d�d_dd`�d�d���Z>ed�d�d���Z?dS )�re a�0 Data decomposition using Independent Component Analysis (ICA).41 42 This object estimates independent components from :class:`mne.io.Raw`,43 :class:`mne.Epochs`, or :class:`mne.Evoked` objects. Components can44 optionally be removed (for artifact repair) prior to signal reconstruction.45 46 .. warning:: ICA is sensitive to low-frequency drifts and therefore47 requires the data to be high-pass filtered prior to fitting.48 Typically, a cutoff frequency of 1 Hz is recommended.49 50 Parameters51 ----------52 n_components : int | float | None53 Number of principal components (from the pre-whitening PCA step) that54 are passed to the ICA algorithm during fitting:55 56 - :class:`int`57 Must be greater than 1 and less than or equal to the number of58 channels.59 - :class:`float` between 0 and 1 (exclusive)60 Will select the smallest number of components required to explain61 the cumulative variance of the data greater than ``n_components``.62 Consider this hypothetical example: we have 3 components, the first63 explaining 70%%, the second 20%%, and the third the remaining 10%%64 of the variance. Passing 0.8 here (corresponding to 80%% of65 explained variance) would yield the first two components,66 explaining 90%% of the variance: only by using both components the67 requested threshold of 80%% explained variance can be exceeded. The68 third component, on the other hand, would be excluded.69 - ``None``70 ``0.999999`` will be used. This is done to avoid numerical71 stability problems when whitening, particularly when working with72 rank-deficient data.73 74 Defaults to ``None``. The actual number used when executing the75 :meth:`ICA.fit` method will be stored in the attribute76 ``n_components_`` (note the trailing underscore).77 78 .. versionchanged:: 0.2279 For a :class:`python:float`, the number of components will account80 for *greater than* the given variance level instead of *less than or81 equal to* it. The default (None) will also take into account the82 rank deficiency of the data.83 noise_cov : None | instance of Covariance84 Noise covariance used for pre-whitening. If None (default), channels85 are scaled to unit variance ("z-standardized") as a group by channel86 type prior to the whitening by PCA.87 %(random_state)s88 method : 'fastica' | 'infomax' | 'picard'89 The ICA method to use in the fit method. Use the ``fit_params`` argument90 to set additional parameters. Specifically, if you want Extended91 Infomax, set ``method='infomax'`` and ``fit_params=dict(extended=True)``92 (this also works for ``method='picard'``). Defaults to ``'fastica'``.93 For reference, see :footcite:`Hyvarinen1999,BellSejnowski1995,LeeEtAl1999,AblinEtAl2018`.94 fit_params : dict | None95 Additional parameters passed to the ICA estimator as specified by96 ``method``. Allowed entries are determined by the various algorithm97 implementations: see :class:`~sklearn.decomposition.FastICA`,98 :func:`~picard.picard`, :func:`~mne.preprocessing.infomax`.99 max_iter : int | 'auto'100 Maximum number of iterations during fit. If ``'auto'``, it101 will set maximum iterations to ``1000`` for ``'fastica'``102 and to ``500`` for ``'infomax'`` or ``'picard'``. The actual number of103 iterations it took :meth:`ICA.fit` to complete will be stored in the104 ``n_iter_`` attribute.105 allow_ref_meg : bool106 Allow ICA on MEG reference channels. Defaults to False.107 108 .. versionadded:: 0.18109 %(verbose)s110 111 Attributes112 ----------113 current_fit : 'unfitted' | 'raw' | 'epochs'114 Which data type was used for the fit.115 ch_names : list-like116 Channel names resulting from initial picking.117 n_components_ : int118 If fit, the actual number of PCA components used for ICA decomposition.119 pre_whitener_ : ndarray, shape (n_channels, 1) or (n_channels, n_channels)120 If fit, array used to pre-whiten the data prior to PCA.121 pca_components_ : ndarray, shape ``(n_channels, n_channels)``122 If fit, the PCA components.123 pca_mean_ : ndarray, shape (n_channels,)124 If fit, the mean vector used to center the data before doing the PCA.125 pca_explained_variance_ : ndarray, shape ``(n_channels,)``126 If fit, the variance explained by each PCA component.127 mixing_matrix_ : ndarray, shape ``(n_components_, n_components_)``128 If fit, the whitened mixing matrix to go back from ICA space to PCA129 space.130 It is, in combination with the ``pca_components_``, used by131 :meth:`ICA.apply` and :meth:`ICA.get_components` to re-mix/project132 a subset of the ICA components into the observed channel space.133 The former method also removes the pre-whitening (z-scaling) and the134 de-meaning.135 unmixing_matrix_ : ndarray, shape ``(n_components_, n_components_)``136 If fit, the whitened matrix to go from PCA space to ICA space.137 Used, in combination with the ``pca_components_``, by the methods138 :meth:`ICA.get_sources` and :meth:`ICA.apply` to unmix the observed139 data.140 exclude : array-like of int141 List or np.array of sources indices to exclude when re-mixing the data142 in the :meth:`ICA.apply` method, i.e. artifactual ICA components.143 The components identified manually and by the various automatic144 artifact detection methods should be (manually) appended145 (e.g. ``ica.exclude.extend(eog_inds)``).146 (There is also an ``exclude`` parameter in the :meth:`ICA.apply`147 method.) To scrap all marked components, set this attribute to an empty148 list.149 %(info)s150 n_samples_ : int151 The number of samples used on fit.152 labels_ : dict153 A dictionary of independent component indices, grouped by types of154 independent components. This attribute is set by some of the artifact155 detection functions.156 n_iter_ : int157 If fit, the number of iterations required to complete ICA.158 159 Notes160 -----161 .. versionchanged:: 0.23162 Version 0.23 introduced the ``max_iter='auto'`` settings for maximum163 iterations. With version 0.24 ``'auto'`` will be the new164 default, replacing the current ``max_iter=200``.165 166 .. versionchanged:: 0.23167 Warn if `~mne.Epochs` were baseline-corrected.168 169 .. note:: If you intend to fit ICA on `~mne.Epochs`, it is recommended to170 high-pass filter, but **not** baseline correct the data for good171 ICA performance. A warning will be emitted otherwise.172 173 A trailing ``_`` in an attribute name signifies that the attribute was174 added to the object during fitting, consistent with standard scikit-learn175 practice.176 177 ICA :meth:`fit` in MNE proceeds in two steps:178 179 1. :term:`Whitening <whitening>` the data by means of a pre-whitening step180 (using ``noise_cov`` if provided, or the standard deviation of each181 channel type) and then principal component analysis (PCA).182 2. Passing the ``n_components`` largest-variance components to the ICA183 algorithm to obtain the unmixing matrix (and by pseudoinversion, the184 mixing matrix).185 186 ICA :meth:`apply` then:187 188 1. Unmixes the data with the ``unmixing_matrix_``.189 2. Includes ICA components based on ``ica.include`` and ``ica.exclude``.190 3. Re-mixes the data with ``mixing_matrix_``.191 4. Restores any data not passed to the ICA algorithm, i.e., the PCA192 components between ``n_components`` and ``n_pca_components``.193 194 ``n_pca_components`` determines how many PCA components will be kept when195 reconstructing the data when calling :meth:`apply`. This parameter can be196 used for dimensionality reduction of the data, or dealing with low-rank197 data (such as those with projections, or MEG data processed by SSS). It is198 important to remove any numerically-zero-variance components in the data,199 otherwise numerical instability causes problems when computing the mixing200 matrix. Alternatively, using ``n_components`` as a float will also avoid201 numerical stability problems.202 203 The ``n_components`` parameter determines how many components out of204 the ``n_channels`` PCA components the ICA algorithm will actually fit.205 This is not typically used for EEG data, but for MEG data, it's common to206 use ``n_components < n_channels``. For example, full-rank207 306-channel MEG data might use ``n_components=40`` to find (and208 later exclude) only large, dominating artifacts in the data, but still209 reconstruct the data using all 306 PCA components. Setting210 ``n_pca_components=40``, on the other hand, would actually reduce the211 rank of the reconstructed data to 40, which is typically undesirable.212 213 If you are migrating from EEGLAB and intend to reduce dimensionality via214 PCA, similarly to EEGLAB's ``runica(..., 'pca', n)`` functionality,215 pass ``n_components=n`` during initialization and then216 ``n_pca_components=n`` during :meth:`apply`. The resulting reconstructed217 data after :meth:`apply` will have rank ``n``.218 219 .. note:: Commonly used for reasons of i) computational efficiency and220 ii) additional noise reduction, it is a matter of current debate221 whether pre-ICA dimensionality reduction could decrease the222 reliability and stability of the ICA, at least for EEG data and223 especially during preprocessing :footcite:`ArtoniEtAl2018`.224 (But see also :footcite:`Montoya-MartinezEtAl2017` for a225 possibly confounding effect of the different whitening/sphering226 methods used in this paper (ZCA vs. PCA).)227 On the other hand, for rank-deficient data such as EEG data after228 average reference or interpolation, it is recommended to reduce229 the dimensionality (by 1 for average reference and 1 for each230 interpolated channel) for optimal ICA performance (see the231 `EEGLAB wiki <eeglab_wiki_>`_).232 233 Caveat! If supplying a noise covariance, keep track of the projections234 available in the cov or in the raw object. For example, if you are235 interested in EOG or ECG artifacts, EOG and ECG projections should be236 temporally removed before fitting ICA, for example::237 238 >> projs, raw.info['projs'] = raw.info['projs'], []239 >> ica.fit(raw)240 >> raw.info['projs'] = projs241 242 Methods currently implemented are FastICA (default), Infomax, and Picard.243 Standard Infomax can be quite sensitive to differences in floating point244 arithmetic. Extended Infomax seems to be more stable in this respect,245 enhancing reproducibility and stability of results; use Extended Infomax246 via ``method='infomax', fit_params=dict(extended=True)``. Allowed entries247 in ``fit_params`` are determined by the various algorithm implementations:248 see :class:`~sklearn.decomposition.FastICA`, :func:`~picard.picard`,249 :func:`~mne.preprocessing.infomax`.250 251 .. note:: Picard can be used to solve the same problems as FastICA,252 Infomax, and extended Infomax, but typically converges faster253 than either of those methods. To make use of Picard's speed while254 still obtaining the same solution as with other algorithms, you255 need to specify ``method='picard'`` and ``fit_params`` as a256 dictionary with the following combination of keys:257 258 - ``dict(ortho=False, extended=False)`` for Infomax259 - ``dict(ortho=False, extended=True)`` for extended Infomax260 - ``dict(ortho=True, extended=True)`` for FastICA261 262 Reducing the tolerance (set in ``fit_params``) speeds up estimation at the263 cost of consistency of the obtained results. It is difficult to directly264 compare tolerance levels between Infomax and Picard, but for Picard and265 FastICA a good rule of thumb is ``tol_fastica == tol_picard ** 2``.266 267 .. _eeglab_wiki: https://eeglab.org/tutorials/06_RejectArtifacts/RunICA.html#how-to-deal-with-corrupted-ica-decompositions268 269 References270 ----------271 .. footbibliography::272 Nr� �autoF)� noise_cov� random_state�method�273fit_params�max_iterr� rR c s� t |td� t |tdd f� |dkrtd|t� || _d|ffD ]2\} }274t|275t�r>d|276 k r3dk s>n td| � d|277� ���t|278t�rR|279dkrRtd | � d|280� d281���q d | _ || _282d | _ d | _ d | _
|| _� d u rki � t� �� |d kr�d
dd d�} � �� fdd�| �� D �� n283|dkr�� �dd� t |tdfd� t|t�r�td|dd� |d kr�d}n|dv r�d}� �d|� || _� | _g | _d | _|| _t� | _|| _d S )Nr� �int-like�imported_eeglab� n_componentsr r[ zaSelecting ICA components by explained variance needs values between 0.0 and 1.0 (exclusive), got �=z Selecting one component with z is not supported�unfittedr� ZparallelZlogcosh)� algorithmZfunZfun_argsc s i | ] \}}|� vr||�qS rl rl �ro �kr� �r� rl rs r� � s z ICA.__init__.<locals>.<dictcomp>rd �extendedFr� �r� �when stri� )rd r� i� )rH �str�floatr@ �_KNOWN_ICA_METHODSr� �284isinstancer� rN � current_fitr� �_max_pca_components�n_pca_components�ch_namesr� r r� r� �285setdefaultr� r� �excluder� r� �dict�labels_r� ) �selfr� r� r� r� r� r� r� rR r� �valr� rl r� rs �__init__� s`
����� 286 287z ICA.__init__c s� t G dd� d��}� jdkrd }n288� jdkrd}nd}� j}� j}t� dd �}t� dd �}t� d d �}t� d289d �}|d urBt� j�}� jd urQ� fd d �tD �} ng } � j ra� fd
d �� j D �}290ng }291||||||||| |292d� } | S )Nc @ sV e Zd ZU ded< ded< ded< ded< ded < ded293< ded < d ed
< d ed< dS )z.ICA._get_infos_for_repr.<locals>._InfosForReprz$Literal['raw data', 'epochs'] | None�fit_onz;Literal['fastica', 'infomax', 'extended-infomax', 'picard']�294fit_methodzdict[str, str | float]r� z295int | None�296fit_n_iter�
fit_n_samples�fit_n_components�fit_n_pca_componentsz list[str]�ch_types�excludesN)r� r� � __qualname__�__annotations__rl rl rl rs �
_InfosForRepr� s 297 r� r� �rawzraw data�epochs�n_iter_�298n_samples_�
n_components_�pca_components_c s g | ]}|� v r|�qS rl rl )ro �c�r� rl rs rt rv z+ICA._get_infos_for_repr.<locals>.<listcomp>c � g | ]}� j | �qS rl )�299_ica_names�ro �ir� rl rs rt � ) r� r� r� r� r� r� r� r� r� )300r r� r� r� �getattrrw r� r� r r� ) r� r� r� r� r� r� r� r� r� r� r� Zinfos_for_reprrl r� rs �_get_infos_for_repr� sB 301 302 303304� zICA._get_infos_for_reprc C s| | � � }|jpd� d|j� �}|jdur8|d|j� d|j� d|j� d|j� dd �|j�� d t |j305�p3d� d306�
7 }d |� d �S )
zICA fit information.�noz decomposition, method: Nz (fit in z iterations on z samples), z ICA components (z+ PCA components available), channel types: �, z sources marked for exclusionz<ICA | �>) r� r� r� r� r� r� r� r� r� rw r� )r� �infos�srl rl rs �__repr__/ s" 307308���309� �� z ICA.__repr__c C sD | � � }tdd�}|j|j|j|j|j|j|j|j |j310|j d� }|S )N�reprzica.html.jinja) r� r� r� �n_iter� n_samplesr� r� r� r� ) r� r5 �renderr� r� r� r� r� r� r� r� r� )r� r� �t�htmlrl rl rs � _repr_html_A s 311� zICA._repr_html_� @Tc C s. t ddd�} | �� D ]\} }
| j| kr t|
dt| �� �� q312t|ttfdd� t� |j313d d�r4t d � t |t�rB|j
d314urBt d � t |t�sad d
� td||||f�D �}|rat dd�|�� �� t|j315|d| jd�}t||j316| jd� t� }| jdkr�| �� t�317dt|�� | jd318ur�| jt|�kr�td| j� dt|�� d���t|j319|�| _320| j321d r�| j322�� �
g | j323d< W d324 � n1 s�w Y | j325d | _ t |t�r�| � ||||||||| |326�327 nt |t�s�J �| � ||||328� t | |�}|� � d329d330d� }t!| |dd � t� }t�331d || d �d �� | S ) a332 Run the ICA decomposition on raw data.333 334 Caveat! If supplying a noise covariance keep track of the projections335 available in the cov, the raw or the epochs object. For example,336 if you are interested in EOG or ECG artifacts, EOG and ECG projections337 should be temporally removed before fitting the ICA.338 339 Parameters340 ----------341 inst : instance of Raw or Epochs342 The data to be decomposed.343 %(picks_good_data_noref)s344 This selection remains throughout the initialized ICA solution.345 start, stop : int | float | None346 First and last sample to include. If float, data will be347 interpreted as time in seconds. If ``None``, data will be used from348 the first sample and to the last sample, respectively.349 350 .. note:: These parameters only have an effect if ``inst`` is351 `~mne.io.Raw` data.352 decim : int | None353 Increment for selecting only each n-th sampling point. If ``None``,354 all samples between ``start`` and ``stop`` (inclusive) are used.355 reject, flat : dict | None356 Rejection parameters based on peak-to-peak amplitude (PTP)357 in the continuous data. Signal periods exceeding the thresholds358 in ``reject`` or less than the thresholds in ``flat`` will be359 removed before fitting the ICA.360 361 .. note:: These parameters only have an effect if ``inst`` is362 `~mne.io.Raw` data. For `~mne.Epochs`, perform PTP363 rejection via :meth:`~mne.Epochs.drop_bad`.364 365 Valid keys are all channel types present in the data. Values must366 be integers or floats.367 368 If ``None``, no PTP-based rejection will be performed. Example::369 370 reject = dict(371 grad=4000e-13, # T / m (gradiometers)372 mag=4e-12, # T (magnetometers)373 eeg=40e-6, # V (EEG channels)374 eog=250e-6 # V (EOG channels)375 )376 flat = None # no rejection based on flatness377 tstep : float378 Length of data chunks for artifact rejection in seconds.379 380 .. note:: This parameter only has an effect if ``inst`` is381 `~mne.io.Raw` data.382 %(reject_by_annotation_raw)s383 384 .. versionadded:: 0.14.0385 %(verbose)s386 387 Returns388 -------389 self : instance of ICA390 Returns the modified instance.391 Zsklearnr� )r� r� z use method=�instz
Raw or EpochsZhighpass� z�The 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.Nz�The 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.c S s g | ]392\}}|d ur|�qS �Nrl )ro �393param_nameZ param_valrl rl rs rt � s394 �zICA.fit.<locals>.<listcomp>)�start�stop�reject�flatzThe following parameters passed to ICA.fit() will be ignored, as they only affect raw data (and it appears you passed epochs): r� F)� allow_emptyZ with_ref_meg)r� r� zPFitting ICA to data using %i channels (please be patient, this may take a while)zica.n_components (z%) cannot be greater than len(picks) (�)�compsr� �������copyzFitting ICA took z.1fzs.)"r� r� r� rG r� rH r6 r1 rx �iscloser� rS r� �baseline�zipr� r r� r� r
r� �_resetrO rw r� r� r �_unlockr� �_fit_raw� _fit_epochs�_ica_explained_variance�argsort�_sort_components)r� r� r� r� r �decimr r �tstep�reject_by_annotationrR Zreq_mapr� �modZignored_paramsZt_start�varZvar_ordZt_stoprl rl rs �fitR s� J395���396 ���� �397�398�399��400 � 401�
402zICA.fitc C s( dD ] }t | |�rt| |� qd| _dS )� Aux method.) �
pre_whitener_�unmixing_matrix_�mixing_matrix_r� r� r� �pca_explained_variance_� pca_mean_r� �403drop_inds_�reject_r� N)�hasattr�delattrr� )r� �keyrl rl rs r � s404 405
406�407z408ICA._resetc C s� t |||�\}}| r dnd} |�|||| �} |dur%| dd�dd|�f } |dus-|dur>|| _t| |||| j|�\} | _nd| _| jd | _| �| d� | S )r �omitNr[ r� ) �_check_start_stop�get_datar rF r� r �shaper� �_fit) r� r� r� r� r r r r r r rR �datarl rl rs r
s � z ICA._fit_rawc C s� |j jdkrtd|j � d���|j|d�}|dur'|dd�dd�dd|�f }|jd |jd | _t�|�}| �|d� t |j409�| _ | S )r r zETried to fit ICA with epochs, but none were found: epochs.events is "z".�r� Nr r� ) �events�size� RuntimeErrorr& r' r� rx �hstackr( r r r )r� r� r� r rR r) rl rl rs r 3 s �� 410 zICA._fit_epochsc C s� | j |dd�}| jdu rX| j}t�t|�dg�}t|dg d�D ]
\}}t�|| �||< q t|d�rBt |dg d�}t�|| �||< t|d �rWt |dg d411�}t�|| �||< nt412| j| j| jj d �\}}|j d |j d ksqJ �|| _
dS )
rk z(pre-whitener computation)��413log_suffixNr[ F)r� r� r� Tr� )r� r� r* r )�_do_projr� r� rx �emptyrw r Zstdr r r- r� r' r )r� r) r� � pre_whitenerr� Zpicks_rl rl rs �_compute_pre_whitenerK s$ 414415416�417�418zICA._compute_pre_whitener� c C s� | j d ur?| j d r?tdd� | j d D �| j d dd�\}}}|r?t� d|� dt|�� |r/d nd419� |� �� | jd u r?|| }|S ) N�projsc S s g | ]}|d r|�qS )Zactiverl )ro �prl rl rs rt f rv z ICA._do_proj.<locals>.<listcomp>r� T)Zinclude_activez& Applying projection operator with z vector� r5 )r� r rO rE r� )r� r) r0 ZprojZnprojr� rl rl rs r1 c s& ��420���421z ICA._do_projc C s4 | j |dd�}| jd u r|| j }|S | j| }|S )Nz(pre-whitener application)r/ )r1 r� r )r� r) rl rl rs � _pre_whitent s 422423424�zICA._pre_whitenc C s� t �|��� s td��t| j�}|j\}}| �|� | �|�}t | j425dd�}|� |j �}|j
}| j}t|t�rAtt||�d �}n|du rIt|�}t|tt jB �sSJ �| jdu rfd} t|t|d�d �| _n)t| jt�r�t|| j�\| _}426| jdkr�td d427|428 � d ���d } nd
} t| j�| _| j|kr�t �|�}429|430|431d }432d433|434| jd |d g } td| j� d| j� d| d d�d| j� d|� d| d d�d�
��t� | � d| j� d�� |j | _ |j | _ |j!| _"~| �#� | jdu�r| jt| j �k�rtd| j� dt| j �� d���t$d| j�} | j%d k�r8dd l&m'}
|
d.d |d �| j(��}|�)|dd�| f � |j | _*|j+| _+nQ| j%d v �r[t,|dd�| f f|dd!�| j(��\}}|| _*|| _+~~n.| j%d"k�r�dd#l-m-} ||dd�| f j fd d|d$�| j(��\}}}}|| _*|d | _+~~| j*j| jfd% k�s�J �| j"}||d d&k}|d| j� }|| jd �s�t �.|�d d d }t/d'| j� d(| j� d)|d d*�d+|d d*�d,|� �435� t �0|�}d-||dk< | j*| _*| �1� || _2dS )/rk z1Input data contains non-finite values (NaN/Inf). T)r� �whitenr Nz$Selecting by non-zero PCA componentsg� !����?r[ z;One PCA component captures most of the explained variance (�d zL%), your threshold results in 1 component. You should select a higher value.z Selecting by explained variancezSelecting by numberr z
n_components=z436 requires z PCA values (EV=z0.1fz%) but n_pca_components (z) results in only z components (EV=�%)z: z components�n_pca_components (z0) is greater than the number of PCA components (r r� )�FastICAF)r: r� )rd zextended-infomax)r� �
return_n_iterr� )r� )r: r? r� r �����ư>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 <= � �?rl )3rx �isfiniter� r� rJ r� r' r4 r9 r9 r� Z
fit_transform�TZexplained_variance_ratio_r� r� r� �int�_exp_var_ncomprw �int_r� �minr� r- rB �cumsumrO r� Zmean_r Z components_r� Zexplained_variance_r �_update_ica_names�slicer� Zsklearn.decompositionr> r� r r r� rd r� �whererS �sqrt�_update_mixing_matrixr� )r� r) Zfit_typer� Z437n_channelsr� ZpcaZuse_evZn_pca�msg�evZevs�selr> �ica�unmixing_matrixr� r� r� �WZnormsZstableZmax_intrl rl rs r( | s� 438439440441 442443 444�� 445446 447�������448�� 449 ��450� ���451452�����453 454zICA._fitc C s t | j�| _d S r� )rP r r r� rl rl rs rM � s zICA._update_mixing_matrixc C s dd� t | j�D �| _dS )z+Update ICA names when n_components_ is set.c S s g | ]}d |d���qS )re Z03drl )ro �iirl rl rs rt � rv z)ICA._update_ica_names.<locals>.<listcomp>N)�ranger� r� r� rl rl rs rI � s zICA._update_ica_namesc C sT | � |�}| jdur|| jdd�df 8 }t�| j| jd| j� �}t�||�}|S )z-Compute sources from data (operates inplace).N)r9 r rx �dotr r� r� )r� r) Zpca_data�sourcesrl rl rs �455_transform� s 456457� zICA._transformc C sR t | d�s td��t|||�\}}| �|�}|rdnd}|�||||�}| �|�S )zTransform raw data.r �!No fit available. Please fit ICA.r$ N)r! r- r% �458_get_picksr& rX )r� r� r� r r r� r r) rl rl rs �_transform_raw459 s 460461 462zICA._transform_rawc C sZ t | d�s td��| �|�}t�|j|d��}| �|�}|s+t�t�|t |j463�d��}|S )r r rY r* r[ ) r! r- rZ rx r. r& rX ry �splitrw r+ )r� r� � concatenater� r) rW rl rl rs �_transform_epochs s 464465466zICA._transform_epochsc C s, t | d�s td��| �|�}| �|j| �S )r r rY )r! r- rZ rX r) )r� �evokedr� rl rl rs �_transform_evoked s 467468zICA._transform_evokedc C s� t |j| jg dd�}t|�t| j�krMt|t�r d\}}nt|t�r'd\}}nt|t�r1d\}}ntd��t |� d|� dt| j�� d t|�� d469|� d �470��|S ) z!Pick logic for _transform method.T�r� r )�Raw�doesn't)�Epochszdon't)r2 rc �0Data input must be of Raw, Epochs or Evoked typer8 z match fitted data: � channels fitted but z$ channels supplied. 471Please provide z compatible with 'ica.ch_names'.)472r r� r� rw r� r6 r1 r2 r� r- )r� r� r� r� �dorl rl rs rZ ' s" 473474475476477478���zICA._get_picksc C s0 t �| jdd�d| j�f j| jd| j� �jS )z�Get ICA topomap for components as numpy arrays.479 480 Returns481 -------482 components : array, shape (n_channels, n_components)483 The ICA components (maps).484 N)rx rV r r� rC r� r� rl rl rs �get_components: s ��zICA.get_components)�485components�ch_typec s@ �j dkr td��t�tttfdd� t� ddttjfddd � t � ttjB �r4� D ] }t|dd486d� q*t|ttjt487dfd d d � t |t488�rJ|g}n|du rV�j d
d
d�}n t |ttjB �s`J �|}t |�dksjJ �d}|D ]}||vr�td|� dd�
|�� ���qn~� du r�t�j�� � ��fdd�|D �}tt||��}|S )a Get the proportion of data variance explained by ICA components.489 490 Parameters491 ----------492 inst : mne.io.BaseRaw | mne.BaseEpochs | mne.Evoked493 The uncleaned data.494 components : array-like of int | int | None495 The component(s) for which to do the calculation. If more than one496 component is specified, explained variance will be calculated497 jointly across all supplied components. If ``None`` (default), uses498 all available components.499 ch_type : 'mag' | 'grad' | 'planar1' | 'planar2' | 'eeg' | array-like of str | None500 The channel type(s) to include in the calculation. If ``None``, all501 available channel types will be used.502 503 Returns504 -------505 dict (str, float)506 The fraction of variance in ``inst`` that can be explained by the507 ICA components, calculated separately for each channel type.508 Dictionary keys are the channel types, and corresponding explained509 variance ratios are the values.510 511 Notes512 -----513 A value similar to EEGLAB's ``pvaf`` (percent variance accounted for)514 will be calculated for the specified component(s).515 516 Since ICA components cannot be assumed to be aligned orthogonally, the517 sum of the proportion of variance explained by all components may not518 be equal to 1. In certain situations, the proportion of variance519 explained by a component may even be negative.520 521 .. versionadded:: 1.2522 r� zICA must be fitted first.r� )�itemr� � item_nameNr� ri z int, array-like of int, or None)rk r� rl � type_namezElements of "components"rj z str, array-like of str, or NoneTr� r[ )�magZgradZplanar1Zplanar2�eegz-You requested operation on the channel type "z7", but only the following channel types are supported: r� c s g | ]523}�j �� |d ��qS ))r� ri rj )�)_get_explained_variance_ratio_one_ch_type)ro rj �ri r� r� rl rs rt � s ���z4ICA.get_explained_variance_ratio.<locals>.<listcomp>)r� r� rH r6 r1 r2 r rx �ndarrayr� r� r� rw r� rU r� r� r ) r� r� ri rj rk r� Zallowed_ch_typesZexplained_var_ratios�resultrl rq rs � get_explained_variance_ratioG s\ 524$ �� �525����526�z ICA.get_explained_variance_ratioc C s� t |�� |gg ddd�}t|ttB �r=|jd ur=t�� � tjddt d� | j527d528i |��}W d � n1 s7w Y n| j529d530i |��}|j |d�}|j |d�}|| }|j dd��
� } |j dd��
� }531d | |532 } | S ) Nr F)r� �includer� r� rR �ignorez The data.*was baseline-corrected)�action�message�categoryr* �Zaxisr[ rl )r� r r� r1 r2 r533 �warnings�catch_warnings�filterwarnings�RuntimeWarning�applyr& r �mean) r� r� ri rj �kwargsZ534inst_reconZ535data_reconZ data_origZ data_diffZ
mean_var_diffZ
mean_var_origZvar_explained_ratiorl rl rs rp � s2 �536� �� z-ICA._get_explained_variance_ratio_one_ch_typec C s� t |t�rt| j|jdd| jd� | �||||�}|S t |t�r5t| j|jdd| jd� | �||d�}|S t |t�rNt| j|jdd| jd� | � ||�}|S t537d��)a� Estimate sources given the unmixing matrix.538 539 This method will return the sources in the container format passed.540 Typical usecases:541 542 1. pass Raw object to use `raw.plot <mne.io.Raw.plot>` for ICA sources543 2. pass Epochs object to compute trial-based statistics in ICA space544 3. pass Evoked object to investigate time-locking in ICA space545 546 Parameters547 ----------548 inst : instance of Raw, Epochs or Evoked549 Object to compute sources from and to represent sources in.550 add_channels : None | list of str551 Additional channels to be added. Useful to e.g. compare sources552 with some reference. Defaults to None.553 start : int | float | None554 First sample to include. If float, data will be interpreted as555 time in seconds. If None, the entire data will be used.556 stop : int | float | None557 Last sample to not include. If float, data will be interpreted as558 time in seconds. If None, the entire data will be used.559 560 Returns561 -------562 sources : instance of Raw, Epochs or Evoked563 The ICA sources time series.564 re rb �r� rd Fr2 re ) r� r6 r= r� r� �_sources_as_rawr1 �_sources_as_epochsr2 �_sources_as_evokedr� )r� r� � add_channelsr� r rW rl rl rs � get_sources� s& 565 �
566��567�� �zICA.get_sourcesc C s" t |||�\}}| j|||d�}|jd || ksJ �|j}|jr)|j}d|_|`z |�� �||jd |d |jd �}W |rGd|_||_n |rPd|_||_w |durlt|�rlt |j568|�} t � ||j
| ||d�g�}||_|j}569|j} |570g|_| g|_dg|_d|_d|_| �|j||� |S )r �r� r r[ F�sfreqTN)r% r[ r' �preload�_datar �cropr� rw r r� rx r] r& �571first_sampZ last_sampZ _first_sampsZ _last_samps� filenames�572_projector� _export_info) r� r� r� r� r Zdata_Z preloadedr) r| r� Zout_first_sampZ
out_last_samprl rl rs r� � s@ ��� zICA._sources_as_rawc s� � � � }| �� |�}|dur� fdd�|D �}ng }t|�dkr1tj|� �� dd�|f gdd�n||_| �|j� |� d|_ d|_573d|_ |S )r Nc � g | ]}� j �|��qS rl �r� �index�ro r� �r� rl rs rt % rv z*ICA._sources_as_epochs.<locals>.<listcomp>r r[ rz T) r r^ rw rx r] r& r� r� r� r� �_rawr� )r� r� r� r] r| rW r� rl r� rs r� s "��zICA._sources_as_epochsc sr |dur� fdd�|D �}ng }| � � �}t|�dkr&tj|� j| f }n|}� �� }||_| �|j� |� |S )r Nc r� rl r� r� �r_ rl rs rt 8 rv z*ICA._sources_as_evoked.<locals>.<listcomp>r[ )r` rw rx Zr_r) r r� r� )r� r_ r� r� rW r) r| rl r� rs r� 5 s 574 zICA._sources_as_evokedc s� g �g }t | j�D ](\}}��|� |�t|d|d tjtjtjtjt j575ddd�d|d dd� � q � durH�� 7 �|� fd d576�|j d D �7 }|j d d d
�� ||d < g |d< W d � n1 sbw Y �fdd577�| j
D �|d< dS )r r[ � Zf4�ZdtyperA r ) �ch_name�calZlognoZ coil_typer� Z coord_frame�unit�locrU ZscannoZunit_mulNc s g | ]578}|d � v r|�qS )r� rl r� )r� rl rs rt b � z$ICA._export_info.<locals>.<listcomp>r� T)Zupdate_redundantZ check_afterr6 c s g | ]}� | �qS rl rl r� r� rl rs rt h r� �bads)� enumerater� �appendr� r ZFIFFV_COIL_NONEZ
FIFFV_MISC_CHZFIFFV_COORD_UNKNOWNZFIFF_UNIT_NONErx �zerosr� r
r� )r� r� � containerr� Zch_inforT r� rl )r� r� rs r� G s: 579 �� �580 � zICA._export_infor� c581 C s t |t�rt| j|jdd| jd� | �||||�}582n4t |t�r3t| j|jdd| jd� | j|dd�}583nt |t�rJt| j|jdd| jd� | � |�}584nt585d��|d urx| � |||||�}|586j d587 |j d588 krit589d ��t |t�rxt
||590|||�\}591}t|592||�} | S ) a@ Assign score to components based on statistic or metric.593 594 Parameters595 ----------596 inst : instance of Raw, Epochs or Evoked597 The object to reconstruct the sources from.598 target : array-like | str | None599 Signal to which the sources shall be compared. It has to be of600 the same shape as the sources. If str, a routine will try to find601 a matching channel name. If None, a score602 function expecting only one input-array argument must be used,603 for instance, scipy.stats.skew (default).604 score_func : callable | str605 Callable taking as arguments either two input arrays606 (e.g. Pearson correlation) or one input607 array (e. g. skewness) and returns a float. For convenience the608 most common score_funcs are available via string labels:609 Currently, all distance metrics from scipy.spatial and All610 functions from scipy.stats taking compatible input arguments are611 supported. These function have been modified to support iteration612 over the rows of a 2D array.613 start : int | float | None614 First sample to include. If float, data will be interpreted as615 time in seconds. If None, data will be used from the first sample.616 stop : int | float | None617 Last sample to not include. If float, data will be interpreted as618 time in seconds. If None, data will be used to the last sample.619 l_freq : float620 Low pass frequency.621 h_freq : float622 High pass frequency.623 %(reject_by_annotation_all)s624 625 .. versionadded:: 0.14.0626 %(verbose)s627 628 Returns629 -------630 scores : ndarray631 Scores for each source as returned from score_func.632 re rb r� rd T)r] r2 re Nr z>Sources and target do not have the same number of time slices.)r� r6 r= r� r� r[ r1 r^ r2 r` r� �
_check_targetr' �_band_pass_filter�
_find_sources) r� r� �targetr� r� r �l_freq�h_freqr rR rW �scoresrl rl rs �
score_sourcesj s8 6336�634�635� �636637� zICA.score_sourcesc C s� t |t�r:|r dnd}t|||�\}}t|d�r&|jdk r&|�d|jd �}t |t�r8t||�}|� ||||�}|S t |t638�rft |t�rOt||�}|j |d�}t|d�rd|jdkrdt |j�dkrd|� � }|S t |t
�rzt |t�rzt||�}|j| }|S ) z Aux Method.r$ N�ndimr r[ r r* � )r� r6 r% r! r� �reshaper' r� �_get_target_chr& r1 rG rm r2 r) )r� r� r� r� r r �pickrl rl rs r� � s. 639 640641642643644�645646 647648�649650651zICA._check_target� @r� �zscorec s� g g �} � ����fdd�|D �} g }
|D ] }t |t�s-| dkr'|
�d� q|
�| � q|
�|� qtt|
| ��D ]P\}\}}��j� |d��||�d�g7 �|652dkr]t�d |d �}n|653d654krot�t �d �|k�d }nt655d |656� ���| |g7 } t |��j | � d
|� d
|� �< q:t�
�fdd�t| �D ��}t�
| �t� |��� ddd� }t t�|��}g } |D ]}||v r�| �|� |�|� q�t��dkrЈd �t | �}|�fS )znCompute ExG/ref components.657 658 See find_bads_ecg, find_bads_eog, and find_bads_ref for details.659 c s g | ] }�� |� �����qS rl )r� r� )r� r r� r� r rl rs rt � s ��z%ICA._find_bads_ch.<locals>.<listcomp>�ecg�ECG-MAGr� )r� r� r� r r� r� r r� r �� threshold� correlationr zUnknown measure �/c s g | ]660\}}� | | �qS rl rl )ro rT �inds)r� rl rs rt s Nr[ )r� r� r� r� r r� r\ rx rK �absr� �listr� r] r r� �removerw )r� r� r� r� r� r r� r� r �prefix�measure�idx�targetsZ target_namesr� rT r� Zthis_idxZscores_Zidx_Z661idx_uniquer� �labelsrl )r� r r� r� r� r rs �
_find_bads_ch� sX 662�663 ��
664 "665666� zICA._find_bads_ch� c C s� | j d }t�dd�d }t�|�d dt�|� }dd|| d d t�d|| d � }|t�t�|d | �� S )667aH Automatically decide the threshold of Kuiper index for CTPS method.668 669 This function finds the threshold of Kuiper index based on the670 threshold of pk. Kuiper statistic that minimizes the difference between671 pk and the pk threshold (defaults to 20 :footcite:`DammersEtAl2008`)672 is returned. It is assumed that the data are appropriately filtered and673 bad data are rejected at least based on peak-to-peak amplitude674 when/before running the ICA decomposition on data.675 676 References677 ----------678 .. footbibliography::679 r� r[ r; gףp=680��?g� ��Q��?r � ������681 )r� rx �arange�mathrL �expZargminr� )r� Z pk_threshold�NZVs�CZPksrl rl rs �_get_ctps_threshold, s682 683 . zICA._get_ctps_threshold� � r] c C s t |tdfd� t|t�rtd|ddd� t |td� td|d� t |684td� td|685d � t||�} | d686u rAt|||| d �\}
}n|j| }
|d kr�|d
kr\| �� }t� d|d�d�� t|t687�r~| � t ||||d| d��j
dd�}|jd dkr}td� nt|t�r�| � |�j
dd�}ntd��t|�\}}}|�d�}t�||k�d }|t�|| ��� d688d689d� }t|�| jd< |d690u r�d}t|�| jd|� �< n.|dkr�|d
kr�|691d kr�d }n692|d
kr�|693dkr�d }| j||
g|||||d| |694d �695\| jd< }| jd |fS ) a� Detect ECG related components.696 697 Cross-trial phase statistics :footcite:`DammersEtAl2008` or Pearson698 correlation can be used for detection.699 700 .. note:: If no ECG channel is available, an artificial ECG channel will be701 created based on cross-channel averaging of ``"mag"`` or ``"grad"``702 channels. If neither of these channel types are available in703 ``inst``, artificial ECG channel creation is impossible.704 705 Parameters706 ----------707 inst : instance of Raw, Epochs or Evoked708 Object to compute sources from.709 %(ch_name_ecg)s710 threshold : float | 'auto'711 Value above which a feature is classified as outlier. See Notes.712 713 .. versionchanged:: 0.21714 start : int | float | None715 First sample to include. If float, data will be interpreted as716 time in seconds. If None, data will be used from the first sample.717 When working with Epochs or Evoked objects, must be float or None.718 stop : int | float | None719 Last sample to not include. If float, data will be interpreted as720 time in seconds. If None, data will be used to the last sample.721 When working with Epochs or Evoked objects, must be float or None.722 l_freq : float723 Low pass frequency.724 h_freq : float725 High pass frequency.726 method : 'ctps' | 'correlation'727 The method used for detection. If ``'ctps'``, cross-trial phase728 statistics :footcite:`DammersEtAl2008` are used to detect729 ECG-related components. See Notes.730 %(reject_by_annotation_all)s731 732 .. versionadded:: 0.14.0733 %(measure)s734 %(verbose)s735 736 Returns737 -------738 ecg_idx : list of int739 The indices of ECG-related components.740 scores : np.ndarray of float, shape (``n_components_``)741 If method is 'ctps', the normalized Kuiper index scores. If method742 is 'correlation', the correlation scores.743 744 See Also745 --------746 find_bads_eog, find_bads_ref, find_bads_muscle747 748 Notes749 -----750 The ``threshold``, ``method``, and ``measure`` parameters interact in751 the following ways:752 753 - If ``method='ctps'``, ``threshold`` refers to the significance value754 of a Kuiper statistic, and ``threshold='auto'`` will compute the755 threshold automatically based on the sampling frequency.756 - If ``method='correlation'`` and ``measure='correlation'``,757 ``threshold`` refers to the Pearson correlation value, and758 ``threshold='auto'`` sets the threshold to 0.9.759 - If ``method='correlation'`` and ``measure='zscore'``, ``threshold``760 refers to the z-score value (i.e., standard deviations) used in the761 iterative z-scoring method, and ``threshold='auto'`` sets the762 threshold to 3.0.763 764 References765 ----------766 .. footbibliography::767 �numericr� r� r� ��extrar� )r] r� r� �r� r� N)r r] r� zUsing threshold: z.2fz for CTPS ECG detectionF)r� r� Zkeep_ecgr r r zANo ECG activity detected. Consider changing the input parameters.z2With `ctps` only Raw and Epochs input is supportedr r� r� zecg/r� r� r� ��������?�r� r� r r� r� r� r r� )rH r� r� r@ r^ r_ r� r� rO r� r6 r� r` r& r' rS r1 r� r] �maxrx rK r� r r� r� r� )r� r� r� r� r� r r� r� r� r r� rR Zidx_ecgr� r� rW Zp_valsr� Zecg_idxrl rl rs �
find_bads_ecgD s� X768 769 �770771�� � ��772773 �
zICA.find_bads_ecg�togetherc s� t |tdfd� t|t�rtd|ddd� t | td� td| d� t |774td� td|775d � | d776kr}|d kr<|777d kr<d
}n778|d krF|779dkrFd}|sOt� jd�} nt� j|�} t| �} | s_td��� fdd�| D �}
| j � |
|||||d||780d�781\| j782d< }n\| dkr�|d kr�d
}|783d kr�t � d|784� d�� t
| j ddd�}t
| j ddd�}t|�r�t|�s�td ��| �� }tjj|| d d �tjj|| d d � }t�|�}tt||d d ��| j785d< | j786d |fS )!a( Detect MEG reference related components using correlation.787 788 Parameters789 ----------790 inst : instance of Raw, Epochs or Evoked791 Object to compute sources from. Should contain at least one channel792 i.e. component derived from MEG reference channels.793 ch_name : list of str794 Which MEG reference components to use. If None, then all channels795 that begin with REF_ICA.796 threshold : float | str797 Value above which a feature is classified as outlier.798 799 - If ``measure`` is ``'zscore'``, defines the threshold on the800 z-score used in the iterative z-scoring method.801 - If ``measure`` is ``'correlation'``, defines the absolute802 threshold on the correlation between 0 and 1.803 - If ``'auto'``, defaults to 3.0 if ``measure`` is ``'zscore'`` and804 0.9 if ``measure`` is ``'correlation'``.805 806 .. warning::807 If ``method`` is ``'together'``, the iterative z-score method808 is always used.809 start : int | float | None810 First sample to include. If float, data will be interpreted as811 time in seconds. If None, data will be used from the first sample.812 stop : int | float | None813 Last sample to not include. If float, data will be interpreted as814 time in seconds. If None, data will be used to the last sample.815 l_freq : float816 Low pass frequency.817 h_freq : float818 High pass frequency.819 %(reject_by_annotation_all)s820 method : 'together' | 'separate'821 Method to use to identify reference channel related components.822 Defaults to ``'together'``. See notes.823 824 .. versionadded:: 0.21825 %(measure)s826 %(verbose)s827 828 Returns829 -------830 ref_idx : list of int831 The indices of MEG reference related components, sorted by score.832 scores : np.ndarray of float, shape (``n_components_``) | list of array833 The correlation scores.834 835 See Also836 --------837 find_bads_ecg, find_bads_eog, find_bads_muscle838 839 Notes840 -----841 ICA decomposition on MEG reference channels is used to assess external842 magnetic noise and remove it from the MEG. Two methods are supported:843 844 With the ``'together'`` method, only one ICA fit is used, which845 encompasses both MEG and reference channels together. Components which846 have particularly strong weights on the reference channels may be847 thresholded and marked for removal.848 849 With ``'separate'`` selected components from a separate ICA850 decomposition on the reference channels are used as a ground truth for851 identifying bad components in an ICA fit done on MEG channels only. The852 logic here is similar to an EOG/ECG, with reference components853 replacing the EOG/ECG channels. Recommended procedure is to perform ICA854 separately on reference channels, extract them using855 :meth:`~mne.preprocessing.ICA.get_sources`, and then append them to the856 inst using :meth:`~mne.io.Raw.add_channels`, preferably with the prefix857 ``REF_ICA`` so that they can be automatically detected.858 859 With ``'together'``, thresholding is based on adaptative z-scoring.860 861 With ``'separate'``:862 863 - If ``measure`` is ``'zscore'``, thresholding is based on adaptative864 z-scoring.865 - If ``measure`` is ``'correlation'``, threshold defines the absolute866 threshold on the correlation between 0 and 1.867 868 Validation and further documentation for this technique can be found869 in :footcite:`HannaEtAl2020`.870 871 .. versionadded:: 0.18872 873 References874 ----------875 .. footbibliography::876 r� r� r� r� r� r� )r� �separater� r� r� r� r� r� r� r� zREF_ICA*z No valid channels available.c r� rl r� r� �r� rl rs rt d r� z%ICA.find_bads_ref.<locals>.<listcomp>r� r� r� zVWith method 'together', only 'zscore' measure issupported. Using 'zscore' instead of 'z'.TF)�megr� z:ICA solution must contain both reference and MEG channels.r rz r[ )r� �tail)rH r� r� r@ r r� r r� r� r� r� rO r� r �anyrh rx �linalg�norm�logr\ )r� r� r� r� r� r r� r� r r� r� rR r� Zref_chsr� Z meg_picks� ref_picks�weightsZnormratsrl r� rs �
find_bads_ref� sn j877 � ����878 879�zICA.find_bads_ref� �?� �- c sp t �dd� d\} }880} | j|||d�} | �� }
| j||dd�}|jdd�\}}|jd kr2|jd881d �}t�t� |�t� |�j882d �d883 }t |d
d �} t |j
| jdddd�}t|j
|d�swtd� | }�fdd�t|�D �| jd< | jd |fS t|
�tjt|
�d884d � }t|j
| j|dd�}|jd885 |
jd886 ks�J �||jd887d �8 }tjj|d d �}||�� }t�||�}t |d d �}888t�|
jd f�}t� t� |��}d ||�� }t|
j889�D ]#\}}t� t� |dd�tj f ��}||�� }t� ||�� � ||< q�d t |d d � } d d� | |890| fD �}t!|�� tj"t�#|�d891d �}� �fd d�t|�D �| jd< | jd |fS ) as Detect muscle-related components.892 893 Detection is based on :footcite:`DharmapraniEtAl2016` which uses894 data from a subject who has been temporarily paralyzed895 :footcite:`WhithamEtAl2007`. The criteria are threefold:896 897 #. Positive log-log spectral slope from 7 to 45 Hz898 #. Peripheral component power (farthest away from the vertex)899 #. A single focal point measured by low spatial smoothness900 901 The threshold is relative to the slope, focal point and smoothness902 of a typical muscle-related ICA component. Note the high frequency903 of the power spectral density slope was 75 Hz in the reference but904 has been modified to 45 Hz as a default based on the criteria being905 more accurate in practice.906 907 If ``inst`` is supplied without sensor positions, only the first criterion908 (slope) is applied.909 910 Parameters911 ----------912 inst : instance of Raw, Epochs or Evoked913 Object to compute sources from.914 threshold : float | str915 Value above which a component should be marked as muscle-related,916 relative to a typical muscle component.917 start : int | float | None918 First sample to include. If float, data will be interpreted as919 time in seconds. If None, data will be used from the first sample.920 stop : int | float | None921 Last sample to not include. If float, data will be interpreted as922 time in seconds. If None, data will be used to the last sample.923 l_freq : float924 Low frequency for muscle-related power.925 h_freq : float926 High frequency for muscle-related power.927 %(sphere_topomap_auto)s928 %(verbose)s929 930 Returns931 -------932 muscle_idx : list of int933 The indices of muscle-related components, sorted by score.934 scores : np.ndarray of float, shape (``n_components_``) | list of array935 The correlation scores.936 937 See Also938 --------939 find_bads_ecg, find_bads_eog, find_bads_ref940 941 Notes942 -----943 .. versionadded:: 1.1944 r� r� �NNNr� �misc)ZfminZfmaxr� T)Z return_freqsr r rz r[ r� g �?r� rl Fra r* zdNo sensor positions found. Scores for bad muscle components are only based on the 'slope' criterion.c s g | ]945\}}|� kr|�qS rl rl �ro r� �scorer� rl rs rt � r� z(ICA.find_bads_muscle.<locals>.<listcomp>�muscle)r� �sphereZignore_overlapg�������?g�������?Ni, r; c S s g | ]}|d ur|�qS r� rl )ro r� rl rl rs rt s946 �c s g | ] \}}|�� kr|�qS rl rl r� �Z947n_criteriar� rl rs rt s )$rH r� rh Z compute_psdr& r� r� rx Zpolyfit�log10rC r r r� r� r< rS r� r� r� r� r+ r' r� r� rV r� r Z948squareformZpdist�newaxis�multiply�sumrw �prodry ) r� r� r� r� r r� r� r� rR Z slope_scoreZ focus_scoreZsmoothness_scorerW ri ZspectrumZpsdsZfreqsZslopesr� r� Zcomponents_norm�pos�distsZ focus_distsZ smoothnessesr� �compZ949comp_distsrl r� rs �find_bads_muscle� sb B950951 ��952 � � � �zICA.find_bads_muscler[ r� c s� t |tdfd� t|t�rtd|ddd� t | td� td| d� t|� �} � fdd �| D �} |d953kr:| d kr:d }n954|d955krD| d
krDd}| j� | |||||d|| d�956\| jd< }
| jd |
fS )aI Detect EOG related components using correlation.957 958 Detection is based on Pearson correlation between the959 filtered data and the filtered EOG channel.960 Thresholding is based on adaptive z-scoring. The above threshold961 components will be masked and the z-score will be recomputed962 until no supra-threshold component remains.963 964 Parameters965 ----------966 inst : instance of Raw, Epochs or Evoked967 Object to compute sources from.968 ch_name : str969 The name of the channel to use for EOG peak detection.970 The argument is mandatory if the dataset contains no EOG971 channels.972 threshold : float | str973 Value above which a feature is classified as outlier.974 975 - If ``measure`` is ``'zscore'``, defines the threshold on the976 z-score used in the iterative z-scoring method.977 - If ``measure`` is ``'correlation'``, defines the absolute978 threshold on the correlation between 0 and 1.979 - If ``'auto'``, defaults to 3.0 if ``measure`` is ``'zscore'`` and980 0.9 if ``measure`` is ``'correlation'``.981 start : int | float | None982 First sample to include. If float, data will be interpreted as983 time in seconds. If None, data will be used from the first sample.984 stop : int | float | None985 Last sample to not include. If float, data will be interpreted as986 time in seconds. If None, data will be used to the last sample.987 l_freq : float988 Low pass frequency.989 h_freq : float990 High pass frequency.991 %(reject_by_annotation_all)s992 993 .. versionadded:: 0.14.0994 %(measure)s995 %(verbose)s996 997 Returns998 -------999 eog_idx : list of int1000 The indices of EOG related components, sorted by score.1001 scores : np.ndarray of float, shape (``n_components_``) | list of array1002 The correlation scores.1003 1004 See Also1005 --------1006 find_bads_ecg, find_bads_ref, find_bads_muscle1007 r� r� r� r� r� r� r� c r� rl r� r� r� rl rs rt k r� z%ICA.find_bads_eog.<locals>.<listcomp>r� r� r� r� r� r� r� )rH r� r� r@ rc r� r� )r� r� r� r� r� r r� r� r r� rR Zeog_indsZeog_chsr� rl r� rs �
find_bads_eog" s0 B1008 1009� zICA.find_bads_eogrS )� on_baselinerR c C s t |tttfdd� t|||d�} t|t�r%d| j}1010} | j|||d� n t|t�r7d| j}1011} | j|d� n d| j }1012} | j|d � t1013| j |j d1014|1015| j d � t
|d d
d� d} t|ttB �rvt|dd�durv|dkrnd} nd}
t||
d � t� d|1016� d�� | di | ��}| r�|�|j� |S )a% Remove selected components from the signal.1017 1018 Given the unmixing matrix, transform the data,1019 zero out all excluded components, and inverse-transform the data.1020 This procedure will reconstruct M/EEG signals from which1021 the dynamics described by the excluded components is subtracted.1022 1023 Parameters1024 ----------1025 inst : instance of Raw, Epochs or Evoked1026 The data to be processed (i.e., cleaned). It will be modified1027 in-place.1028 include : array_like of int1029 The indices referring to columns in the ummixing matrix. The1030 components to be kept. If ``None`` (default), all components1031 will be included (minus those defined in ``ica.exclude``1032 and the ``exclude`` parameter, see below).1033 exclude : array_like of int1034 The indices referring to columns in the ummixing matrix. The1035 components to be zeroed out. If ``None`` (default) or an1036 empty list, only components from ``ica.exclude`` will be1037 excluded. Else, the union of ``exclude`` and ``ica.exclude``1038 will be excluded.1039 %(n_pca_components_apply)s1040 start : int | float | None1041 First sample to include. If float, data will be interpreted as1042 time in seconds. If None, data will be used from the first sample.1043 stop : int | float | None1044 Last sample to not include. If float, data will be interpreted as1045 time in seconds. If None, data will be used to the last sample.1046 %(on_baseline_ica)s1047 %(verbose)s1048 1049 Returns1050 -------1051 out : instance of Raw, Epochs or Evoked1052 The processed data.1053 1054 Notes1055 -----1056 .. note:: Applying ICA may introduce a DC shift. If you pass1057 baseline-corrected `~mne.Epochs` or `~mne.Evoked` data,1058 the baseline period of the cleaned data may not be of1059 zero mean anymore. If you require baseline-corrected1060 data, apply baseline correction again after cleaning1061 via ICA. A warning will be emitted to remind you of this1062 fact if you pass baseline-corrected data.1063 1064 .. versionchanged:: 0.231065 Warn if instance was baseline-corrected.1066 r� zRaw, Epochs, or Evoked)ru r� r� rb )r� r� r rd r� r2 r� re r� r� )�reapply)�extrasFr1067 Nr� Tz�The data you passed to ICA.apply() was baseline-corrected. Please note that ICA can introduce DC shifts, therefore you may wish to consider baseline-correcting the cleaned data again.zApplying ICA to z instancerl )rH r6 r1 r2 r� r� �1068_apply_rawr� �
_apply_epochs�
_apply_evokedr= r� r� r? r� rD rO Zapply_baseliner1069 )r� r� ru r� r� r� r r� rR r� r� �methZreapply_baselinerN r| rl rl rs r � s> @��1070 1071 �� z ICA.applyc C s. |d u r t t| j��S t t| j��t|���S r� )r� �setr� �union)r� r� rl rl rs �_check_exclude� s zICA._check_excludec C sh t |d� t|||�\}}t|jd| jg dd�}||||�f d }| �||||�}|||||�f< |S )r � ica.applyF)r� ru r� r� r )rA r% r r� r� �
_pick_sources) r� r� ru r� r� r� r r� r) rl rl rs r� � s 1072�zICA._apply_rawc C s� t |d� t|jdd| jg d�}t|�t| j�kr)tdt| j�� dt|�� d���t�|�|��}| � ||||�}t�1073t� |t|j �d��|j
dd�|f< d |_|S )1074r r F�r� r� ru r� z Epochs don't match fitted data: rf zJ channels supplied. 1075Please provide Epochs compatible with 'ica.ch_names'.r[ NT)rA r r� r� rw r- rx r. r& r ry r\ r+ r� r� )r� r� ru r� r� r� r) rl rl rs r� � s 1076���(zICA._apply_epochsc C sp t |jdd| jg d�}t|�t| j�kr$tdt| j�� dt|�� d���|j| }| �||||�}||j|< |S )r Fr z#Evoked does not match fitted data: rf zY channels supplied. 1077Please provide an Evoked object that's compatible with ica.ch_names.)r r� r� rw r- r) r )r� r_ ru r� r� r� r) rl rl rs r� s ���10781079zICA._apply_evokedc C s� |du r| j }| �|�}| �|�}| �|�}|j\}}| jjd }| j| kr,|ks<n td|� d| j� d|� d���t� d| j� dt1080| j�� d �� | j dur\|| j dd�df 8 }t �
| j�} |dg fvrnt �|�} n|dg fvr~t �t �
| j�|�} | jt| � }1081t� d1082|1083� d t1084|1085�� �� | jd|� } | j||fks�J �| jj| jj kr�| jfd ks�J � J �t �|�} | j| d| j�d| j�f< t �| | �} t� d
|� dt1086|�� �� t �|�}
| j|
d| j�d| j�f< | j|
}
|
j| jddd� k�r1087||fk�s
J � J �t �| t �
| j|�f�} t �|
dd�| f | | dd�f �}t �||�}|j|fd k�s<J �| j du�rM|| j dd�df 7 }| jdu �rZ|| j9 }|S t jj| jdd�| }|S )rk Nr r= z ) must be >= n_components_ (z-) and <= the total number of PCA components (z).z Transforming to ICA space (z1088 componentr z Zeroing out z ICA componentr z Projecting back using z PCA componentr g�+����=)Zrcond)r� r9 r �_check_n_pca_componentsr' r� r� r� rO r� rE r rx r� r� Z setdiff1drw r r �eyerV rC r] r� r r� rP )r� r) ru r� r� � _n_pca_comp�n_chr� �max_pca_componentsZsel_keepZn_zero�pca_componentsZunmixingZmixingZproj_matrl rl rs r . sv 1089109010911092 ���1093��1094 �1095�1096 �109710982�$ 1099�zICA._pick_sources)� overwriterR c C st | j dkr td��t|dd� t||d�}t�d|� d�� t|��}t|| � W d � | S 1 s3w Y | S ) a� Store ICA solution into a fiff file.1100 1101 Parameters1102 ----------1103 fname : path-like1104 The absolute path of the file name to save the ICA solution into.1105 The file name should end with ``-ica.fif`` or ``-ica.fif.gz``.1106 %(overwrite)s1107 1108 .. versionadded:: 1.01109 %(verbose)s1110 1111 Returns1112 -------1113 ica : instance of ICA1114 The object.1115 1116 See Also1117 --------1118 read_ica1119 r� z&No fit available. Please first fit ICAre �z-ica.fifz -ica.fif.gzz_ica.fifz _ica.fif.gz)r1120 zWriting ICA solution to z...N)r� r- rI r> rO r� r$ �1121_write_ica)r� �fnamer1122 rR �fidrl rl rs �save{ s 1123� 1124 1125��zICA.savec C s t | �S )z{Copy the ICA object.1126 1127 Returns1128 -------1129 ica : instance of ICA1130 The copied object.1131 r r� rl rl rs r � s zICA.copy� �head�@ ZRdBu_r�NNz%3.2f)r� �plot_stdr �sensors�1132show_names�contours�outlinesr� � image_interp� extrapolate�border�resr, �cmap�vlim�cnorm�colorbar�cbar_fmt�axes�title�nrows�ncols�show�1133image_args�psd_argsrR c C s� t | fi d|�d|�d|�d|�d|�d|�d|�d|�d | �d1134|1135�d | �d | �d
|
�d|�d|�d|�d|�d|�d|�d|�d|�d|�d|�d|�d|�d|�d|�d | ��S ) Nr� rj r� r r r r r r r� r r r r r, r r r r r! r" r# r$ r% r& r' r( rR )rT ) r� r� rj r� r r r r r r r� r r r r r, r r r r r! r" r# r$ r% r& r' r( rR rl rl rs �plot_components� sv !�������� �1136� � �
��������������� � �zICA.plot_components�power)�estimaterR c C s( t | ||||||||| |1137| | |
||d�S )N)r� r" �dBr � log_scale� topomap_argsr' r( �figsizer& r r r+ rR rX )r� r� r� r" r, r r- r. r' r( r/ r& r r r+ rR rl rl rs �plot_properties� s$ �zICA.plot_propertiesr� z.*)�annotation_regexr( �theme�
overview_mode�splashc
C sr t | fi d|�d|�d|�d|�d|�d|�d|�d|
�d |�d1138|�d | �d |1139�d
| �d| �d|�d|�d|��S )Nr� r� r� r r# r& �blockr1 r( �show_first_samp�show_scrollbars� time_format�1140precompute�1141use_openglr2 r3 r4 )rW )r� r� r� r� r r# r& r5 r6 r7 r8 r9 r: r1 r( r2 r3 r4 rl rl rs � plot_sources1142 sJ �������� �1143� � �
������zICA.plot_sources�ICA component scoresc C s t | ||||||||d� S )N) rQ r� r� r� �axhliner# r/ �n_colsr& )rV ) r� r� r� r� r= r# r/ r> r& rl rl rs � plot_scores<1144 s �zICA.plot_scoresc
C s t | ||||||||| |1145d� S )N)1146r� r� r� r� r r# r& r� r� rR )rU ) r� r� r� r� r� r r# r& r� r� rR rl rl rs � plot_overlayT1147 s �zICA.plot_overlayc C s� t |t�r$t| j|�\}}t�d|� dd| � dd| � d�� |}|S |du r7| j}|du r5| jjd }|S || j k r?| j }|S )rk z
Selected z' PCA components by explained variance (r; u ≥r< Nr )1148r� r� rE r rO r� r� r� r' r� )r� r rR r� rO rl rl rs r q1149 s& 1150���� 1151�zICA._check_n_pca_componentsr� ) NNNNNNr� TN)r5 �Fr� )Nr� NNNNTN)r� NNNNTr� r� )r� )1152Nr� NNr� r� r] Tr� N)1153Nr� NNNNTr� r� N)r� NNr� r� NN) Nr� NNr[ r� Tr� N)NNNNN) NNTTFNNNNTr� T) NNNNTFFTr� NN)NNNr< NNT)NNNNNTN)@r� r� r� r� rR r� r� r� rQ r� r r r r r4 r1 r9 r( rM rI rX r[ r^ r` rZ rh rt rp r� r� r� r� r� r� r� r� r� r� r� r� r� r r r� r� r� r r r rL rT r0 r/ r. r) rY r0 rW r; rV r? rU r@ r rl rl rl rs re � s� k��E41154 � (&1155y11561157
Z1158'0(# �1159Z 1160�1161K � � + � �]� �gM#1162��@��&��* �� � re c C sN t j| t jd�}|�� }||d }t||k�� d t|��}|||d fS )Nr� r r[ )rx Zasarray�float64rH rG r� rw )r r� Zcvarrl rl rs rE �1163 s1164 rE c C sr t � }|df|| jffD ]*\}}|du r|�|� q z |�t|�� W q ty6 |�| �|�d � Y q w |S )rk r N)r� Zn_timesr� rB � TypeErrorZ
time_as_index)r� r� r r| �stZnone_rl rl rs r% �1165 s �r% �� r� � �# r� c 1166 C sZ t �d� t| jd |�� ||||d�}t|�} tj|| j t�| �|t� | � f }|S )a� Find ECG peaks from one selected ICA source.1167 1168 Parameters1169 ----------1170 raw : instance of Raw1171 Raw object to draw sources from.1172 ecg_source : ndarray1173 ICA source resembling ECG to find peaks from.1174 event_id : int1175 The index to assign to found events.1176 tstart : float1177 Start detection after tstart seconds. Useful when beginning1178 of run is noisy.1179 l_freq : float1180 Low pass frequency.1181 h_freq : float1182 High pass frequency.1183 qrs_threshold : float | str1184 Between 0 and 1. qrs detection threshold. Can also be "auto" to1185 automatically choose the threshold that generates a reasonable1186 number of heartbeats (40-160 beats / min).1187 %(verbose)s1188 1189 Returns1190 -------1191 ecg_events : array1192 Events.1193 ch_ECG : string1194 Name of channel used.1195 average_pulse : float.1196 Estimated average pulse.1197 z(Using ICA source to identify heart beatsr� )�tstartZ thresh_valuer� r� )1198rO r� ra rm rw rx Zc_r� r� �ones)1199r� Z1200ecg_source�event_idrH r� r� Z
qrs_thresholdrR Z