Before you start

Every recipe on this page starts from the same place and adds blocks. They are written for the case where you have nothing but the recordings — no finished Analysis stage to inherit — so they work identically on every plan.

The starting point

Drop a Select Files block and set:

That block now emits X (the signal table) and Y (labels), plus Channels for a recording-stage source. Everything below hangs off those two ports.

MLFlow, Workflow, or both

Any of these recipes can be built entirely in the Workflow canvas — that is the simplest thing to do, and for a one-off analysis it is the right answer. Build in MLFlow instead when you want the same chain reused across several workflows or studies. The combined section below shows the split.

Channel selection

Keeps the channels that actually separate your classes and drops the rest. On high-density montages this is usually the single biggest win: fewer, better channels means fewer parameters, less overfitting, and a model that trains in seconds.

Wiring it

[Select Files]                    [Channel Selection]
  data_source: Filtered
      X  ──────────────────────────▶ Data
      Y  ──────────────────────────▶ Labels
                                       Selected Data ────▶ (next stage)
                                       Selected Channels ─▶ (optional: Data Graph)
                                       Scores ────────────▶ (optional: Data Graph)

Choosing a method

Twenty methods are available. In practice:

Dimensionality reduction

Projects many correlated channels onto a handful of components. Useful after channel selection, when what remains is still wider than your trial count.

Wiring PCA

PCA is a class block, so it has a selected_method — set it to fit_transform and its ports become X, y and one output.

[Channel Selection]                [PCA]  selected_method: fit_transform
  Selected Data ────────────────────▶ X            n_components: 20
  (labels from Select Files) ───────▶ y
                                       output ─────▶ (next stage)

FastICA, KernelPCA and TruncatedSVD wire identically. Use FastICA when you want statistically independent sources rather than maximum-variance ones, KernelPCA when the structure is non-linear.

Where it belongs

Feature selection

Where dimensionality reduction builds new combined components, feature selection keeps a subset of the original columns — which stays interpretable, because every surviving feature is still a real channel or band.

The same fold-leakage warning applies: selection is fitting, so inside the folds it goes.

Cross-validation

Trains nothing itself. It splits, hands each fold to the estimator you wire in, and reports per-fold and aggregate metrics with a confidence interval.

Wiring it

[Channel Selection]              [Cross-Validation]
  Selected Data ──────────────────▶ Dataset          cv_strategy: stratified_k_fold
[Select Files]                                       n_splits: 5
  Y ──────────────────────────────▶ Labels
[a model block]
  model_obj ──────────────────────▶ Model
                                     Metrics ──────────▶ [Output Block]
                                     Confusion Matrix ─▶ [Data Graph]
                                     Fold Scores ──────▶ [Data Graph]

Picking a strategy

LOSO (cross-subject)

Leave-One-Subject-Out holds out an entire subject per fold. It is the honest way to answer “will this work on someone the model has never seen” — and the number it returns is almost always lower than a within-subject score, which is the point.

The pooling step nobody expects

Set the Input Block's subject_scope to all. That collapses every selected subject into a single run, which is what gives the CV block real subject groups to hold out.

Wiring it

You do not need to wire the Groups port. Leave it empty and the block derives per-sample subject and session ids from the run's own provenance, selected by group_by. Wire it only when you have group ids of your own that the provenance does not know about.

The leakage guard

strict_leakage_check is on by default, and it will stop a run rather than let it report a number you would have to retract.

It fires when:

• you use a non-grouped strategy on data spanning more than one subject or session — trials from the same person land in both train and test, and the score measures memorisation;
• group ids were present but had to be dropped, e.g. a block changed the row count and the groups no longer align with X.

The fix is almost always to switch to group_k_fold or leave_one_group_out, not to turn the check off. Turn it off only when you have a specific reason and know what the resulting number does and does not mean.

Domain adaptation

Cross-subject and cross-session models fail mostly because each recording sits in a slightly different feature space — different impedances, cap placement, day. Domain adaptation pulls those spaces together before the model sees them.

Euclidean Alignment

Start here. It is cheap, needs no target labels, and reliably lifts cross-subject scores — the standard first thing to try for transfer EEG.

[Channel Selection]                [Euclidean Alignment]
  Selected Data ────────────────────▶ Data          reference_mode: mean
                                    ▶ Reference (optional)
                                       Aligned Data ────▶ [Cross-Validation] Dataset

CORAL / MMD / TCA

These take an explicit source and target, so they suit the setup where you train on a group of subjects and adapt to one held-out person. Use Data Splitter or two Select Files blocks to produce the two streams.

Subject Adaptation

Different shape from the rest: it takes a trained model and a small amount of labelled data from the new person, and returns a model tuned to them. This is the calibration-session workflow — a few minutes of data from a new user instead of a full training session.

The combined pipeline

Everything above, in one graph: filtered recordings in, an honest cross-subject number out.

[Select Files]                data_source: Filtered, 8 subjects
   X ──┐
   Y ──┼──────────────────────────────────┐
       │                                  │
       ▼                                  │
[Channel Selection]  t-Value, top 5%      │
   Selected Data                          │
       │                                  │
       ▼                                  │
[Euclidean Alignment]  reference: mean    │
   Aligned Data                           │
       │                                  │
       ▼                                  ▼
[Cross-Validation]  Dataset            Labels
   cv_strategy: leave_one_group_out
   group_by: subject
   strict_leakage_check: on
       │            ▲
       │            └──── Model ──── [a model block]
       ├── Metrics ─────────────▶ [Output Block]
       ├── Confusion Matrix ────▶ [Data Graph]
       └── Fold Scores ─────────▶ [Data Graph]

  + Input Block subject_scope: all      ← the pooling step LOSO needs

Splitting it across MLFlow + Workflow

Once that chain works, the reusable half is everything between the data and the validation. Move it into an MLFlow pipeline:

MLFlow — "EEG Preprocess"          Workflow
┌──────────────────────────┐       ┌────────────────────────────────┐
│ [Input Block] Signal ─┐  │       │ [Select Files]                 │
│ [Input Block] Labels ─┼─▶│       │   X ──▶ Signal ┌─────────────┐ │
│      [Channel Selection] │  ═══▶ │   Y ──▶ Labels │EEG Preprocess│ │
│      [Euclidean Align.]  │       │                │      Clean  ─┼─┼─▶ [Cross-Validation]
│ [Output Block] Clean     │       │                └─────────────┘ │
└──────────────────────────┘       └────────────────────────────────┘

Two Input Blocks and one Output Block become two input ports and one output port on the compiled block, named from each block's port_name. Point a second Select Files at fNIRS instead and the same compiled block runs on that. See the port contract.

Sanity checklist

Before you believe a number, check these:

• Is the split grouped? Multi-subject data with a plain k-fold measures memorisation. The leakage guard catches this — do not switch it off to make the error go away.
• Did anything fit outside the folds? A reduction or feature selection fitted upstream of Cross-Validation has seen the test rows.
• Is the score above chance? The CV report carries theoretical and empirical chance levels. Compare against the empirical one — with imbalanced classes it is higher than 1/n.
• Is the confidence interval narrow enough to mean anything? A 5-fold run on 40 trials produces a wide one. Use repeated_stratified_k_fold.
• Did you pool for LOSO? Without subject_scope: all, a cross-subject strategy has one subject to work with.
• Two models to compare? Use Statistical Comparison — McNemar or a paired test — rather than eyeballing two accuracies.

Block-by-block detail: Custom Blocks and Advanced Blocks. How the canvases fit together: Using the ML Suite.