Skip to content

SSP, ICA, and artifact regression

regress_artifact module-attribute

Python
regress_artifact: dict[str, Any] | None = None

Keyword arguments to pass to the mne.preprocessing.EOGRegression model used in mne.preprocessing.regress_artifact. If None, no time-domain regression will be applied. Note that any channels picked in regress_artifact["picks_artifact"] will have the same time-domain filters applied to them as the experimental data.

Artifact regression is applied before SSP or ICA.

Example

For example, if you have MEG reference channel data recorded in three miscellaneous channels, you could do:

Python
regress_artifact = {"picks": "meg", "picks_artifact": ["MISC 001", "MISC 002", "MISC 003"]}
Pipeline steps using this setting

The following steps are directly affected by changes to regress_artifact:

  • preprocessing/_04_frequency_filter
  • preprocessing/_05_regress_artifact

spatial_filter module-attribute

Python
spatial_filter: Literal['ssp', 'ica'] | None = 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.

ICA requires manual intervention!

After the automatic ICA component detection step, review each subject's *_report.html report file check if the set of ICA components to be removed is correct. Adjustments should be made to the *_proc-ica_components.tsv file, which will then be used in the step that is applied during ICA.

ICA component order can be considered arbitrary, so any time the ICA is re-fit – i.e., if you change any parameters that affect steps prior to ICA fitting – this file will need to be updated!

Pipeline steps using this setting

The following steps are directly affected by changes to spatial_filter:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_06b_run_ssp
  • preprocessing/_08a_apply_ica
  • preprocessing/_08b_apply_ssp
  • preprocessing/_09_ptp_reject
  • sensor/_04_time_frequency
  • sensor/_06_make_cov

min_ecg_epochs module-attribute

Python
min_ecg_epochs: Annotated[int, Ge(1)] = 5

Minimal number of ECG epochs needed to compute SSP projectors.

Pipeline steps using this setting

The following steps are directly affected by changes to min_ecg_epochs:

  • preprocessing/_06b_run_ssp

min_eog_epochs module-attribute

Python
min_eog_epochs: Annotated[int, Ge(1)] = 5

Minimal number of EOG epochs needed to compute SSP projectors.

Pipeline steps using this setting

The following steps are directly affected by changes to min_eog_epochs:

  • preprocessing/_06b_run_ssp

n_proj_eog module-attribute

Python
n_proj_eog: dict[str, float] = dict(n_mag=1, n_grad=1, n_eeg=1)

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

Pipeline steps using this setting

The following steps are directly affected by changes to n_proj_eog:

  • preprocessing/_06b_run_ssp

n_proj_ecg module-attribute

Python
n_proj_ecg: dict[str, float] = dict(n_mag=1, n_grad=1, n_eeg=1)

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

Pipeline steps using this setting

The following steps are directly affected by changes to n_proj_ecg:

  • preprocessing/_06b_run_ssp

ecg_proj_from_average module-attribute

Python
ecg_proj_from_average: bool = True

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

Pipeline steps using this setting

The following steps are directly affected by changes to ecg_proj_from_average:

  • preprocessing/_06b_run_ssp

eog_proj_from_average module-attribute

Python
eog_proj_from_average: bool = True

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

Pipeline steps using this setting

The following steps are directly affected by changes to eog_proj_from_average:

  • preprocessing/_06b_run_ssp

ssp_meg module-attribute

Python
ssp_meg: Literal['separate', 'combined', 'auto'] = '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.

Pipeline steps using this setting

The following steps are directly affected by changes to ssp_meg:

  • preprocessing/_06b_run_ssp

ssp_reject_ecg module-attribute

Python
ssp_reject_ecg: dict[str, float] | Literal['autoreject_global'] | None = 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
Pipeline steps using this setting

The following steps are directly affected by changes to ssp_reject_ecg:

  • preprocessing/_06b_run_ssp

ssp_reject_eog module-attribute

Python
ssp_reject_eog: dict[str, float] | Literal['autoreject_global'] | None = 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
Pipeline steps using this setting

The following steps are directly affected by changes to ssp_reject_eog:

  • preprocessing/_06b_run_ssp

ssp_ecg_channel module-attribute

Python
ssp_ecg_channel: str | None = None

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

Pipeline steps using this setting

The following steps are directly affected by changes to ssp_ecg_channel:

  • preprocessing/_06b_run_ssp

ica_reject module-attribute

Python
ica_reject: dict[str, float] | Literal['autoreject_local'] | None = 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
Pipeline steps using this setting

The following steps are directly affected by changes to ica_reject:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_08a_apply_ica
  • preprocessing/_09_ptp_reject

ica_algorithm module-attribute

Python
ica_algorithm: Literal[
    "picard", "fastica", "extended_infomax", "picard-extended_infomax"
] = "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).

Pipeline steps using this setting

The following steps are directly affected by changes to ica_algorithm:

  • preprocessing/_06a1_fit_ica

ica_l_freq module-attribute

Python
ica_l_freq: float | None = 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.

Pipeline steps using this setting

The following steps are directly affected by changes to ica_l_freq:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts

ica_max_iterations module-attribute

Python
ica_max_iterations: int = 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.

Pipeline steps using this setting

The following steps are directly affected by changes to ica_max_iterations:

  • preprocessing/_06a1_fit_ica

ica_n_components module-attribute

Python
ica_n_components: float | int | None = None

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 (default), 0.999999 will be used to avoid issues when working with rank-deficient data.

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

Pipeline steps using this setting

The following steps are directly affected by changes to ica_n_components:

  • preprocessing/_06a1_fit_ica

ica_decim module-attribute

Python
ica_decim: int | None = 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.

Pipeline steps using this setting

The following steps are directly affected by changes to ica_decim:

  • preprocessing/_06a1_fit_ica

ica_ecg_threshold module-attribute

Python
ica_ecg_threshold: float = 0.1

The cross-trial phase statistics (CTPS) threshold parameter used for detecting ECG-related ICs.

Pipeline steps using this setting

The following steps are directly affected by changes to ica_ecg_threshold:

  • preprocessing/_06a2_find_ica_artifacts

ica_eog_threshold module-attribute

Python
ica_eog_threshold: float = 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.

Pipeline steps using this setting

The following steps are directly affected by changes to ica_eog_threshold:

  • preprocessing/_06a2_find_ica_artifacts