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=0, kurt_criterion=0, var_criterion=-1, 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
- rawinstance 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 ofCovariance
Noise covariance used for whitening. If None, channels are just z-scored.
- random_state
None
|int
| instance ofRandomState
If
random_state
is anint
, it will be used as a seed forRandomState
. IfNone
, the seed will be obtained from the operating system (seeRandomState
for details). Default isNone
. Random state to initialize the FastICA estimation. As the estimation is non-deterministic it can be useful to fix the random state 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 ecg scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute 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 eog scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute 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 absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- kurt_criterion
float
|int
| list-like |slice
The indices of the sorted kurtosis scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- var_criterion
float
|int
| list-like |slice
The indices of the sorted variance scores. If float, sources with absolute scores greater than the criterion will be dropped. Else, the absolute scores sorted in descending order will be indexed accordingly. E.g. range(2) would return the two sources with the highest absolute score. If None, this step will be skipped.
- add_nodes
list
oftuple
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_megbool
Allow ICA on MEG reference channels. Defaults to False.
New in version 0.18.
- verbosebool,
str
,int
, orNone
If not None, override default verbose level (see
mne.verbose()
and Logging documentation for more).
- rawinstance of
- Returns
- icainstance of
ICA
The ICA object with detected artifact sources marked for exclusion.
- icainstance of