Decoding / MVPA
decode
module-attribute
¶
decode: bool = True
Whether to perform decoding (MVPA) on the specified
contrasts
. Classifiers will be trained
on entire epochs ("full-epochs decoding"), and separately on each time point
("time-by-time decoding"), trying to learn how to distinguish the contrasting
conditions.
Pipeline steps using this setting
The following steps are directly affected by changes to
decode
:
sensor/_02_decoding_full_epochs
sensor/_03_decoding_time_by_time
sensor/_99_group_average
decoding_which_epochs
module-attribute
¶
decoding_which_epochs: Literal["uncleaned", "after_ica", "after_ssp", "cleaned"] = (
"cleaned"
)
This setting controls which epochs will be fed into the decoding algorithms.
Info
Decoding is a very powerful tool that often can deal with noisy data surprisingly well. Depending on the specific type of data, artifacts, and analysis performed, decoding performance may even improve with less pre-processed data, as processing steps such as ICA or SSP often remove parts of the signal, too, in addition to noise. By default, MNE-BIDS-Pipeline uses cleaned epochs for decoding, but you may choose to use entirely uncleaned epochs, or epochs before the final PTP-based rejection or Autoreject step.
Info
No other sensor- and source-level processing steps will be affected by this setting and use cleaned epochs only.
If "uncleaned"
, use the "raw" epochs before any ICA / SSP, PTP-based, or Autoreject
cleaning (epochs with the filename *_epo.fif
, without a proc-
part).
If "after_ica"
or "after_ssp"
, use the epochs that were cleaned via ICA or SSP, but
before a followup cleaning through PTP-based rejection or Autorejct (epochs with the
filename *proc-ica_epo.fif
or *proc-ssp_epo.fif
).
If "cleaned"
, use the epochs after ICA / SSP and the following cleaning through
PTP-based rejection or Autoreject (epochs with the filename *proc-clean_epo.fif
).
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_which_epochs
:
sensor/_02_decoding_full_epochs
sensor/_03_decoding_time_by_time
sensor/_05_decoding_csp
decoding_epochs_tmin
module-attribute
¶
decoding_epochs_tmin: float | None = 0.0
The first time sample to use for full epochs decoding. By default it starts
at 0. If None
,, it starts at the beginning of the epoch. Does not affect time-by-time
decoding.
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_epochs_tmin
:
sensor/_02_decoding_full_epochs
decoding_epochs_tmax
module-attribute
¶
decoding_epochs_tmax: float | None = None
The last time sample to use for full epochs decoding. By default it is set to None so it ends at the end of the epoch.
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_epochs_tmax
:
sensor/_02_decoding_full_epochs
decoding_metric
module-attribute
¶
decoding_metric: str = 'roc_auc'
The metric to use for estimating classification performance. It can be
'roc_auc'
or 'accuracy'
– or any other metric supported by scikit-learn
.
With ROC AUC, chance level is the same regardless of class balance, that is, you don't need to be worried about exactly balancing class sizes.
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_metric
:
sensor/_02_decoding_full_epochs
sensor/_03_decoding_time_by_time
sensor/_05_decoding_csp
sensor/_99_group_average
decoding_n_splits
module-attribute
¶
decoding_n_splits: Annotated[int, Ge(2)] = 5
The number of folds (also called "splits") to use in the K-fold cross-validation scheme.
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_n_splits
:
sensor/_02_decoding_full_epochs
sensor/_03_decoding_time_by_time
sensor/_05_decoding_csp
sensor/_99_group_average
decoding_time_generalization
module-attribute
¶
decoding_time_generalization: bool = False
Whether to perform time generalization.
Time generalization (also called "temporal generalization" or "generalization across time", GAT) is an extension of the time-by-time decoding approach. Again, a separate classifier is trained on each time point. But instead of just testing the model on the same time point in the test data, it will be tested on all time points.
[T]he manner in which the trained classifiers generalize across time, and from one experimental condition to another, sheds light on the temporal organization of information-processing stages.
Because each classifier is trained and tested on all time points, this procedure may take a significant amount of time.
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_time_generalization
:
sensor/_03_decoding_time_by_time
sensor/_99_group_average
decoding_time_generalization_decim
module-attribute
¶
decoding_time_generalization_decim: int = 1
Says how much to decimate data before time generalization decoding.
This is done in addition to the decimation done at the epochs level via the
epochs_decim
parameter. This can be
used to greatly speed up time generalization at the cost of lower time
resolution in the resulting matrix.
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_time_generalization_decim
:
sensor/_03_decoding_time_by_time
sensor/_99_group_average
decoding_csp
module-attribute
¶
decoding_csp: bool = False
Whether to run decoding via Common Spatial Patterns (CSP) analysis on the data. CSP takes as input data covariances that are estimated on different time and frequency ranges. This allows to obtain decoding scores defined over time and frequency.
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_csp
:
sensor/_05_decoding_csp
sensor/_99_group_average
decoding_csp_times
module-attribute
¶
decoding_csp_times: FloatArrayLike | None = None
The edges of the time bins to use for CSP decoding. Must contain at least two elements. By default, 5 equally-spaced bins are created across the non-negative time range of the epochs. All specified time points must be contained in the epochs interval. If an empty list, do not perform time-frequency analysis, and only run CSP on frequency data.
Example
Create 3 equidistant time bins (0–0.2, 0.2–0.4, 0.4–0.6 sec):
decoding_csp_times = np.linspace(start=0, stop=0.6, num=4)
decoding_csp_times = [0, 0.4, 0.6]
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_csp_times
:
sensor/_05_decoding_csp
sensor/_99_group_average
decoding_csp_freqs
module-attribute
¶
decoding_csp_freqs: dict[str, FloatArrayLike] | None = None
The edges of the frequency bins to use for CSP decoding.
This parameter must be a dictionary with:
- keys specifying the unique identifier or "name" to use for the frequency
range to be treated jointly during statistical testing (such as "alpha" or
"beta"), and
- values must be list-like objects containing at least two scalar values,
specifying the edges of the respective frequency bin(s), e.g., [8, 12]
.
Defaults to two frequency bins, one from
time_frequency_freq_min
to the midpoint between this value and
time_frequency_freq_max
;
and the other from that midpoint to time_frequency_freq_max
.
Example
Create two frequency bins, one for 4–8 Hz, and another for 8–14 Hz, which will be clustered together during statistical testing (in the time-frequency plane):
decoding_csp_freqs = {
'custom_range': [4, 8, 14]
}
decoding_csp_freqs = {
'theta': [4, 8],
'alpha': [8, 14]
}
Pipeline steps using this setting
The following steps are directly affected by changes to
decoding_csp_freqs
:
sensor/_05_decoding_csp
sensor/_99_group_average
n_boot
module-attribute
¶
n_boot: int = 5000
The number of bootstrap resamples when estimating the standard error and confidence interval of the mean decoding scores.
Pipeline steps using this setting
The following steps are directly affected by changes to
n_boot
:
sensor/_05_decoding_csp
sensor/_99_group_average
cluster_forming_t_threshold
module-attribute
¶
cluster_forming_t_threshold: float | None = None
The t-value threshold to use for forming clusters in the cluster-based
permutation test run on the the time-by-time decoding scores.
Data points with absolute t-values greater than this value
will be used to form clusters. If None
, the threshold will be automatically
determined to correspond to a p-value of 0.05 for the given number of
participants in a one-tailed test.
Info
Only points with the same sign will be clustered together.
Pipeline steps using this setting
The following steps are directly affected by changes to
cluster_forming_t_threshold
:
sensor/_99_group_average
cluster_n_permutations
module-attribute
¶
cluster_n_permutations: int = 10000
The maximum number of permutations to perform in a cluster-based permutation test to determine the significance of the decoding scores across participants.
Pipeline steps using this setting
The following steps are directly affected by changes to
cluster_n_permutations
:
sensor/_99_group_average
cluster_permutation_p_threshold
module-attribute
¶
cluster_permutation_p_threshold: Annotated[float, Interval(gt=0, lt=1)] = 0.05
The alpha level (p-value, p threshold) to use for rejecting the null hypothesis that the clusters show no significant difference between conditions. This is used in the permutation test which takes place after forming the clusters.
Info
To control how clusters are formed, see
cluster_forming_t_threshold
.
Pipeline steps using this setting
The following steps are directly affected by changes to
cluster_permutation_p_threshold
:
sensor/_99_group_average