SSP, ICA, and artifact regression
regress_artifact
module-attribute
¶
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:
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
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
¶
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
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
¶
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
¶
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
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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