mne.preprocessing.run_ica

mne.preprocessing.run_ica(raw, n_components, max_pca_components=100, n_pca_components=64, noise_cov=None, random_state=None, picks=None, start=None, stop=None, start_find=None, stop_find=None, ecg_ch=None, ecg_score_func=’pearsonr’, ecg_criterion=0.1, eog_ch=None, eog_score_func=’pearsonr’, eog_criterion=0.1, skew_criterion=-1, kurt_criterion=-1, var_criterion=0, add_nodes=None, verbose=None)[source]

Run ICA decomposition on raw data and identify artifact sources.

This function implements an automated artifact removal work flow.

Hints and caveats:

  • It is highly recommended to bandpass filter ECG and EOG data and pass them instead of the channel names as ecg_ch and eog_ch arguments.
  • Please check your results. Detection by kurtosis and variance can be powerful but misclassification of brain signals as noise cannot be precluded. If you are not sure set those to None.
  • Consider using shorter times for start_find and stop_find than for start and stop. It can save you much time.

Example invocation (taking advantage of defaults):

ica = run_ica(raw, n_components=.9, start_find=10000, stop_find=12000,
              ecg_ch='MEG 1531', eog_ch='EOG 061')
Parameters:

raw : instance of Raw

The raw data to decompose.

n_components : int | float | None

The number of components used for ICA decomposition. If int, it must be smaller then max_pca_components. If None, all PCA components will be used. If float between 0 and 1 components can will be selected by the cumulative percentage of explained variance.

max_pca_components : int | None

The number of components used for PCA decomposition. If None, no dimension reduction will be applied and max_pca_components will equal the number of channels supplied on decomposing data.

n_pca_components

The number of PCA components used after ICA recomposition. The ensuing attribute allows to balance noise reduction against potential loss of features due to dimensionality reduction. If greater than self.n_components_, the next 'n_pca_components' minus 'n_components_' PCA components will be added before restoring the sensor space data. The attribute gets updated each time the according parameter for in .pick_sources_raw or .pick_sources_epochs is changed.

noise_cov : None | instance of mne.cov.Covariance

Noise covariance used for whitening. If None, channels are just z-scored.

random_state : None | int | instance of np.random.RandomState

np.random.RandomState to initialize the FastICA estimation. As the estimation is non-deterministic it can be useful to fix the seed to have reproducible results.

picks : array-like of int

Channels to be included. This selection remains throughout the initialized ICA solution. If None only good data channels are used.

start : int | float | None

First sample to include for decomposition. 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 for decomposition. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.

start_find : int | float | None

First sample to include for artifact search. If float, data will be interpreted as time in seconds. If None, data will be used from the first sample.

stop_find : int | float | None

Last sample to not include for artifact search. If float, data will be interpreted as time in seconds. If None, data will be used to the last sample.

ecg_ch : str | ndarray | None

The target argument passed to ica.find_sources_raw. Either the name of the ECG channel or the ECG time series. If None, this step will be skipped.

ecg_score_func : str | callable

The score_func argument passed to ica.find_sources_raw. Either the name of function supported by ICA or a custom function.

ecg_criterion : float | int | list-like | slice

The indices of the sorted skewness scores. If float, sources with scores smaller than the criterion will be dropped. Else, the scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest score. If None, this step will be skipped.

eog_ch : list | str | ndarray | None

The target argument or the list of target arguments subsequently passed to ica.find_sources_raw. Either the name of the vertical EOG channel or the corresponding EOG time series. If None, this step will be skipped.

eog_score_func : str | callable

The score_func argument passed to ica.find_sources_raw. Either the name of function supported by ICA or a custom function.

eog_criterion : float | int | list-like | slice

The indices of the sorted skewness scores. If float, sources with scores smaller than the criterion will be dropped. Else, the scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest score. If None, this step will be skipped.

skew_criterion : float | int | list-like | slice

The indices of the sorted skewness scores. If float, sources with scores smaller than the criterion will be dropped. Else, the scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest score. If None, this step will be skipped.

kurt_criterion : float | int | list-like | slice

The indices of the sorted skewness scores. If float, sources with scores smaller than the criterion will be dropped. Else, the scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest score. If None, this step will be skipped.

var_criterion : float | int | list-like | slice

The indices of the sorted skewness scores. If float, sources with scores smaller than the criterion will be dropped. Else, the scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest score. If None, this step will be skipped.

add_nodes : list of ica_nodes

Additional list if tuples carrying the following parameters: (name : str, target : str | array, score_func : callable, criterion : float | int | list-like | slice). This parameter is a generalization of the artifact specific parameters above and has the same structure. Example:

add_nodes=('ECG phase lock', ECG 01', my_phase_lock_function, 0.5)

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns:

ica : instance of ICA

The ica object with detected artifact sources marked for exclusion