This documentation is for development version 0.18.dev0.

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, method='fastica', allow_ref_meg=False, 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 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 : str | list | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values “all” to pick all channels, or “data” to pick data channels. None (default) will pick good data channels(excluding reference MEG channels). This selection remains throughout the initialized ICA solution.

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 tuple

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)
method : {‘fastica’, ‘infomax’, ‘extended-infomax’, ‘picard’}

The ICA method to use in the fit() method. Defaults to ‘fastica’.

allow_ref_meg : bool

Allow ICA on MEG reference channels. Defaults to False.

New in version 0.18.

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.