'Run ICA artifacts detection workflow.
Note. This is still experimental and will most likely change. Over
the next releases. For maximum control use the workflow exposed in
the examples.
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
may be powerful but misclassification of brain signals as
noise cannot be precluded.
- 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 the defaults)::
ica.detect_artifacts(ecg_channel=\'MEG 1531\', eog_channel=\'EOG 061\')
Parameters
raw : instance of Raw
Raw object to draw sources from.
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)
Returns
self : instance of ICA
The ica object with the detected artifact indices marked for
exclusion'

def detect_artifacts(self, raw, 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):

    logger.info('                Searching    for    artifacts...')
    _detect_artifacts(self, raw=raw, start_find=start_find, stop_find=stop_find, ecg_ch=ecg_ch, ecg_score_func=ecg_score_func, ecg_criterion=ecg_criterion, eog_ch=eog_ch, eog_score_func=eog_score_func, eog_criterion=eog_criterion, skew_criterion=skew_criterion, kurt_criterion=kurt_criterion, var_criterion=var_criterion, add_nodes=add_nodes)
    return self
