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

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.

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

There is one way to do it: wire a Validation Scheme into the trainer's Val/Eval input. The trainer then trains once per fold and reports per-fold and aggregate metrics with a confidence interval, instead of holding out one split. Left empty, the port reads one hold-out split. Select the trainer and the canvas suggests the scheme; one click adds it already wired.

Wiring it

After the folds the trainer refits one final model on every row (switch off with refit_final_model), so Trained Model still feeds whatever comes next. The metrics are the fold estimate. The input takes only a Validation Scheme or an Evaluation Protocol: a scikit-learn splitter such as KFold or a bare number of folds is refused, so the card and the run record always say how the run was validated.

Picking a strategy

Training several models

A trainer's Model port takes one wire, so comparing architectures used to mean one workflow — and one reload of every subject's recordings — per model. Model Collection gathers several models into one wire: each subject's data loads once, every model trains on it, and each gets its own row of results.

Wiring it

Naming them

Results rows are named "<workflow> · <model>", where <model> is the block wired into that port — its display name, or its label with the canvas's _1 counter dropped when that stays unique. Set model_names on the collection (“CNN, LSTM, GRU”) when several models end in a layer with the same label and would otherwise be indistinguishable on the card; a blank entry keeps the wired block's own name.

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 Select Files' subject_scope (the File grouping dropdown) to Combined subjects, combined sessions. That collapses every selected subject into a single run, which is what gives the trainer real subject groups to hold out. The trainer's own cohort_mode can say the same thing; leave it on Inherit from the data source, because the run refuses if the two disagree.

Wiring it

There are no group ids to wire. The trainer takes per-sample subject and session ids from the run's own provenance, selected by the scheme's group_by.

Train on one session, test on the others

Cross-validation mixes every session into every fold. When the question is whether a model trained in one session (or one condition, such as indoors) still works in another, the sessions have to stay whole: some train, the rest only test. Wire an Evaluation Protocol into the trainer's Val/Eval input — the same input a Validation Scheme uses.

Wiring it

Choosing the settings

The run reports every train → test pair (Session 1 -> Session 2 accuracy), the same-session check (within_accuracy) and, as the headline accuracy, the mean over the pairs to other sessions. On the Execute page, Detailed names what each number was tested on, Per Subject shows each subject's same-session and other-session score and the drop, Statistics → Same session vs another session tests whether that drop holds subject by subject, and Graphs has the train × test matrix (its diagonal is the same-session check) and a confusion matrix per pair.

With the other trainers

With the plain trainer the protocol only evaluates: a model never sees a row of a session it is tested on. Wire the same block into a dedicated trainer and it does what that trainer is for, and the run says so in every table:

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.

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.

Reusing a model trained earlier

Subject Adaptation above reuses a model within one run — the trainer's output feeds it directly. Across runs, or across studies, there is nothing to wire: the model that produced last month's number exists only inside that run's artifacts unless you bring it back. Load Trained Model does that — architecture and weights, from a published .bltm or a registry entry — and Forward Pass is how you call it once it's on the canvas.

Wiring it

The combined pipeline

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

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:

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 the trainer 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 Select Files' subject_scope set to a Combined subjects mode, 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.