Skip to content

SSP & ICA

spatial_filter module-attribute

Python
spatial_filter = None

Whether to use a spatial filter to detect and remove artifacts. The BIDS Pipeline offers the use of signal-space projection (SSP) and independent component analysis (ICA).

Use 'ssp' for SSP, 'ica' for ICA, and None if you do not wish to apply a spatial filter for artifact removal.

The Pipeline will try to automatically discover EOG and ECG artifacts. For SSP, it will then produce projection vectors that remove ("project out") these artifacts from the data. For ICA, the independent components related to EOG and ECG activity will be omitted during the signal reconstruction step in order to remove the artifacts. The ICA procedure can be configured in various ways using the configuration options you can find below.

min_ecg_epochs module-attribute

Python
min_ecg_epochs = 5

Minimal number of ECG epochs needed to compute SSP or ICA rejection.

min_eog_epochs module-attribute

Python
min_eog_epochs = 5

Minimal number of EOG epochs needed to compute SSP or ICA rejection.

n_proj_eog module-attribute

Python
n_proj_eog = dict(n_mag=1, n_grad=1, n_eeg=1)

Number of SSP vectors to create for EOG artifacts for each channel type.

n_proj_ecg module-attribute

Python
n_proj_ecg = dict(n_mag=1, n_grad=1, n_eeg=1)

Number of SSP vectors to create for ECG artifacts for each channel type.

ssp_meg module-attribute

Python
ssp_meg = 'auto'

Whether to compute SSP vectors for MEG channels separately ('separate') or jointly ('combined') for magnetometers and gradiomenters. When using Maxwell filtering, magnetometer and gradiometer signals are synthesized from multipole moments jointly and are no longer independent, so it can be useful to estimate projectors from all MEG sensors simultaneously. The default is 'auto', which will use 'combined' when Maxwell filtering is used and 'separate' otherwise.

ecg_proj_from_average module-attribute

Python
ecg_proj_from_average = True

Whether to calculate the ECG projection vectors based on the the averaged or on individual ECG epochs.

eog_proj_from_average module-attribute

Python
eog_proj_from_average = True

Whether to calculate the EOG projection vectors based on the the averaged or on individual EOG epochs.

ssp_reject_eog module-attribute

Python
ssp_reject_eog = None

Peak-to-peak amplitude limits of the EOG epochs to exclude from SSP fitting. This allows you to remove strong transient artifacts, which could negatively affect SSP performance.

The pipeline will automatically try to detect EOG artifacts in your data, and remove them via SSP. For this to work properly, it is recommended to not specify rejection thresholds for EOG channels here – otherwise, SSP won't be able to "see" these artifacts.

Example
Python
ssp_reject_eog = {'grad': 10e-10, 'mag': 20e-12, 'eeg': 400e-6}
ssp_reject_eog = {'grad': 15e-10}
ssp_reject_eog = None

ssp_reject_ecg module-attribute

Python
ssp_reject_ecg = None

Peak-to-peak amplitude limits of the ECG epochs to exclude from SSP fitting. This allows you to remove strong transient artifacts, which could negatively affect SSP performance.

The pipeline will automatically try to detect ECG artifacts in your data, and remove them via SSP. For this to work properly, it is recommended to not specify rejection thresholds for ECG channels here – otherwise, SSP won't be able to "see" these artifacts.

Example
Python
ssp_reject_ecg = {'grad': 10e-10, 'mag': 20e-12, 'eeg': 400e-6}
ssp_reject_ecg = {'grad': 15e-10}
ssp_reject_ecg = None

ssp_ecg_channel module-attribute

Python
ssp_ecg_channel = None

Channel to use for ECG SSP. Can be useful when the autodetected ECG channel is not reliable.

ica_reject module-attribute

Python
ica_reject = None

Peak-to-peak amplitude limits to exclude epochs from ICA fitting. This allows you to remove strong transient artifacts from the epochs used for fitting ICA, which could negatively affect ICA performance.

The parameter values are the same as for reject, but "autoreject_global" is not supported. "autoreject_local" here behaves differently, too: it is only used to exclude bad epochs from ICA fitting; we do not perform any interpolation.

Info

We don't support "autoreject_global" here (as opposed to reject) because in the past, we found that rejection thresholds were too strict before running ICA, i.e., too many epochs got rejected. "autoreject_local", however, usually performed nicely. The autoreject documentation [recommends][https://autoreject.github.io/stable/auto_examples/plot_autoreject_workflow.html] running local autoreject before and after ICA, which can be achieved by setting both, ica_reject and reject, to "autoreject_local".

If passing a dictionary, the rejection limits will also be applied to the ECG and EOG epochs created to find heart beats and ocular artifacts.

Info

MNE-BIDS-Pipeline will automatically try to detect EOG and ECG artifacts in your data, and remove them. For this to work properly, it is recommended to not specify rejection thresholds for EOG and ECG channels here – otherwise, ICA won't be able to "see" these artifacts.

Info

This setting is applied only to the epochs that are used for fitting ICA. The goal is to make it easier for ICA to produce a good decomposition. After fitting, ICA is applied to the epochs to be analyzed, usually with one or more components removed (as to remove artifacts). But even after ICA cleaning, some epochs may still contain large-amplitude artifacts. Those epochs can then be rejected by using the reject parameter.

Example
Python
ica_reject = {'grad': 10e-10, 'mag': 20e-12, 'eeg': 400e-6}
ica_reject = {'grad': 15e-10}
ica_reject = None  # no rejection before fitting ICA
ica_reject = "autoreject_global"  # find global (per channel type) PTP thresholds before fitting ICA
ica_reject = "autoreject_local"  # find local (per channel) thresholds and repair epochs before fitting ICA

ica_algorithm module-attribute

Python
ica_algorithm = 'picard'

The ICA algorithm to use. "picard-extended_infomax" operates picard such that the generated ICA decomposition is identical to the one generated by the extended Infomax algorithm (but may converge in less time).

ica_l_freq module-attribute

Python
ica_l_freq = 1.0

The cutoff frequency of the high-pass filter to apply before running ICA. Using a relatively high cutoff like 1 Hz will remove slow drifts from the data, yielding improved ICA results. Must be set to 1 Hz or above.

Set to None to not apply an additional high-pass filter.

Info

The filter will be applied to raw data which was already filtered according to the l_freq and h_freq settings. After filtering, the data will be epoched, and the epochs will be submitted to ICA.

Info

The Pipeline will only allow you to perform ICA on data that has been high-pass filtered with a 1 Hz cutoff or higher. This is a conscious, opinionated (but partially data-driven) decision made by the developers. If you have reason to challenge this behavior, please get in touch with us so we can discuss.

ica_max_iterations module-attribute

Python
ica_max_iterations = 500

Maximum number of iterations to decompose the data into independent components. A low number means to finish earlier, but the consequence is that the algorithm may not have finished converging. To ensure convergence, pick a high number here (e.g. 3000); yet the algorithm will terminate as soon as it determines that is has successfully converged, and not necessarily exhaust the maximum number of iterations. Note that the default of 200 seems to be sufficient for Picard in many datasets, because it converges quicker than the other algorithms; but e.g. for FastICA, this limit may be too low to achieve convergence.

ica_n_components module-attribute

Python
ica_n_components = 0.8

MNE conducts ICA as a sort of a two-step procedure: First, a PCA is run on the data (trying to exclude zero-valued components in rank-deficient data); and in the second step, the principal components are passed to the actual ICA. You can select how many of the total principal components to pass to ICA – it can be all or just a subset. This determines how many independent components to fit, and can be controlled via this setting.

If int, specifies the number of principal components that are passed to the ICA algorithm, which will be the number of independent components to fit. It must not be greater than the rank of your data (which is typically the number of channels, but may be less in some cases).

If float between 0 and 1, all principal components with cumulative explained variance less than the value specified here will be passed to ICA.

If None, all principal components will be used.

This setting may drastically alter the time required to compute ICA.

ica_decim module-attribute

Python
ica_decim = None

The decimation parameter to compute ICA. If 5 it means that 1 every 5 sample is used by ICA solver. The higher the faster it is to run but the less data you have to compute a good ICA. Set to 1 or None to not perform any decimation.

ica_ctps_ecg_threshold module-attribute

Python
ica_ctps_ecg_threshold = 0.1

The threshold parameter passed to find_bads_ecg method.

ica_eog_threshold module-attribute

Python
ica_eog_threshold = 3.0

The threshold to use during automated EOG classification. Lower values mean that more ICs will be identified as EOG-related. If too low, the false-alarm rate increases dramatically.