Skip to content

Decoding / MVPA

decode module-attribute

Python
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

Python
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

Python
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

Python
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

Python
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

Python
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

Python
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.

DOI: 10.1016/j.tics.2014.01.002

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

Python
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

Python
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

Python
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):

Python
decoding_csp_times = np.linspace(start=0, stop=0.6, num=4)
Create 2 time bins of different durations (0–0.4, 0.4–0.6 sec):
Python
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

Python
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):

Python
decoding_csp_freqs = {
    'custom_range': [4, 8, 14]
}
Create the same two frequency bins, but treat them separately during statistical testing (i.e., temporal clustering only):
Python
decoding_csp_freqs = {
    'theta': [4, 8],
    'alpha': [8, 14]
}
Create 5 equidistant frequency bins from 4 to 14 Hz: ```python decoding_csp_freqs = { 'custom_range': np.linspace( start=4, stop=14, num=5+1 # We need one more to account for the endpoint! ) }

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

Python
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

Python
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

Python
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

Python
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