The Three Steps

The ML Suite sidebar is numbered for a reason — it is a pipeline of its own, and each step consumes what the one before it produced.

  1 · Pipeline                   2 · Workflow                 3 · Execute
  ┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
  │ build a REUSABLE │ compile │ wire real DATA   │ compile │ run it, per      │
  │ processing/model │────────▶│ into one or more │────────▶│ subject, and see │
  │ unit             │  block  │ compiled units   │         │ metrics + graphs │
  └──────────────────┘         └──────────────────┘         └──────────────────┘
   no files here                Select Files lives here      results land here

Where everything is

Every path below starts from the main sidebar on the left of the app.

Which canvas do I want?

The split confuses people at first, and the rule is simpler than it looks:

1 · Pipeline

A Pipeline is a reusable unit: a named box with named input and output ports. It deliberately has no file picker — it does not know or care which recordings it will see. That is what makes it reusable.

Building a pipeline

Building a model: the wires are forward

If you know PyTorch, the mapping is one table and everything follows from it:

Chain layer blocks and they compose into one nn.Module, in the order you wired them. Recurrent layers chain too — LSTM → Flatten → Linear works, even though nn.Sequential cannot express it.

You never wire data into a layer. A layer with nothing feeding it is a root and receives the trainer's input. That is what makes parallel branches simply a matter of drawing them:

  Conv1d(k=3) → ReLU ─┐
  Conv1d(k=5) → ReLU ─┼─▶ Model Concat ─▶ Linear ─▶ Trainer.Model
  Conv1d(k=7) → ReLU ─┘
      each branch sees the SAME input

Model Concat and Model Add (palette: Model Structure) apply every wired Branch N to the same input. Concat joins the outputs; Add sums them, which is how you draw a skip connection — put an Identity layer on the other branch.

What compiling checks

Compile is validation, not just a save. It refuses a graph that:

• has no input node — at least one Input Block is required, unless the pipeline only defines a model, which takes no data;
• does not have exactly one final output node. Zero is ambiguous, and so is two;
• contains a cycle — the graph has to have a running order;
• has no model or trainer node, matched against the catalog by type or category, never by guessing at names.

Blocking errors stop the compile and the offending nodes are marked red on the canvas. Warnings are shown in a dialog and you can choose to proceed.

Compiling and publishing

A successful compile registers the pipeline under its tab name and a stable internal id, and it appears in the Workflow palette under Model/Pipelines (Compiled). Recompile whenever you change the pipeline — a workflow that already embeds it keeps using the last compiled version until you do, which is deliberate: editing a pipeline never silently changes a workflow mid-experiment.

2 · Workflow

A Workflow is where abstract processing meets actual recordings. This canvas has Select Files, and it is the only one that does.

Building a workflow

  Select Files ─X──▶ BCILattice Trainer . Dataset
               └Y──▶ BCILattice Trainer . Labels
  your model ──────▶ BCILattice Trainer . Model

  Trainer . Metrics ──────────▶ Output Block
  Trainer . Predictions ──────▶ Confusion Matrix Graph . y_pred
  Trainer . True Labels ──────▶ Confusion Matrix Graph . y_true
  Trainer . Training History ─▶ Data Graph . Data

What compiling checks

The same rules as a pipeline, with a wider set of accepted endpoints: the input may be an Input Block or Select Files, and the single final output may be an Output Block, a Graph Output or a Graph Endpoint.

3 · Combining the two

This is the part worth understanding properly, because everything else follows from it.

The port contract

Which trainer port a pipeline block feeds follows from what comes out of it: a model goes to Model, processed data goes to Dataset.

So the shape of the block you drop into a Workflow is decided entirely by how many Input/Output Blocks you put in the pipeline, and what you named them. Two inputs and one output in the pipeline gives you a block with two inputs and one output in the Workflow.

Give every Input Block a distinct name. Two blocks sharing one name compile to two identically named ports, which cannot be told apart when wiring.

A worked example

A preprocessing-plus-decoder pipeline that takes a signal and labels, and returns a trained model.

Pipeline tab — "EEG Decoder"
┌──────────────────────────────────────────────────────────────────┐
│  [Input Block]                                                   │
│   port_name: Signal ──┐                                          │
│                       ├──▶ [Channel Selection] ──▶ [BCILattice   │
│  [Input Block]        │                             Trainer] ──┐ │
│   port_name: Labels ──┘                                        │ │
│                                          [Output Block] ◀──────┘ │
│                                           port_name: Model       │
└──────────────────────────────────────────────────────────────────┘
                              │  Compile
                              ▼
Workflow tab — the same pipeline, now one block
┌──────────────────────────────────────────────────────────────────┐
│  [Select Files]              ┌─────────────────┐                 │
│    modality: EEG             │  EEG Decoder    │                 │
│    X ───────────────────────▶│ Signal    Model │──▶ [Output      │
│    Y ───────────────────────▶│ Labels          │      Block]     │
│                              └─────────────────┘                 │
└──────────────────────────────────────────────────────────────────┘
        Signal / Labels / Model are the port_names you set above.

Note what did not happen: the pipeline never mentioned EEG, a session, or a subject. Point a second Select Files at fNIRS recordings and the same compiled block runs against those instead.

Moving a tab to the other canvas

You imported someone's published work, it opened in the Workflow tab, and it belongs in the Pipeline one — or the reverse. Right-click the tab and choose Move to Pipeline… or Move to Workflow….

This is not a rename. The two canvases carry different palettes and enforce different rules, so some blocks change shape and some cannot come with you. Nothing happens until a report has shown you every block, grouped by what happens to it, with the reason attached:

Saving, renaming, reopening

• Saving a workflow writes a .workflow file and co-saves every pipeline it references as a .pipeline file in the same folder, so the pair travels together. Keep the referenced pipelines open in the Pipeline tab when you save, or they cannot be bundled.
• Loading a workflow reads those .pipeline files back, recompiles them, and marks any block red whose pipeline file is missing or failed to compile.
• References are stored by stable id, not by name, so renaming a pipeline does not break a workflow that embeds it.
• Both canvases are saved into the study itself, so reopening a study restores every pipeline and workflow tab as you left them.

4 · Execute

The Execute tab lists compiled workflows for the active study. Pick one, pick your subjects, and run. Metrics, training history, confusion matrices and any graphs your blocks produced land in the results tabs.

Per-subject vs pooled

By default a run fans out one job per subject — each subject is trained and evaluated independently, which is usually what you want for a within-subject BCI result.

Free vs Researcher

One thing in the ML Suite depends on your plan, and it is worth being precise about what it is — because it gates a shortcut, not a capability.

Importing an Analysis stage

Select Files's data_source lets you train directly on a stage the Analysis suite already produced — channel-selected data, a dimensionality reduction, an extracted feature table, a time-frequency transform, a signal projection. That reuse is a Researcher feature.

On a Free plan the locked entries are refused when you pick one, and Compile also refuses a graph that reached a locked source another way — by loading a file, importing from the community, or generating with AI.

Rebuilding it yourself

Building it in the canvas has a real advantage too: the processing is part of the pipeline, so it travels with it, recompiles with it, and is visible to anyone reading the graph — rather than being an out-of-band step someone has to know was run.

Faster starts

Three ways to avoid starting from a blank canvas. All three produce an ordinary editable graph — nothing they generate is locked, and nothing runs until you compile it yourself.

Build with AI

Where: the Build with AI button at the bottom of the block palette, on either canvas.

Describe what you want in plain language and it lays out a starting graph for the canvas you are on. It is catalog-aware: your description is matched against the live block catalog and the most relevant blocks are given to the model, so it builds from blocks that actually exist in your installation rather than inventing plausible names.

Import from Community

Where: the Import from Community button, directly below Build with AI.

Browses published community pipelines and workflows and imports one into your study, as a new tab or merged into the current canvas. Useful when someone has already solved the preprocessing you need. The same review applies — an imported graph is a starting point, and its parameters were tuned for someone else's recordings.

Standard Preprocessing starter

When you create a new Workflow tab from the + tab, you are asked whether to start Blank or from Standard Preprocessing — the bundled community EEG preprocessing pipeline. Pick Blank when you know what you are building; pick Standard Preprocessing when you want a known-good chain to adapt.

Troubleshooting

Block-by-block reference: Custom Blocks for the everyday palette, Advanced Blocks for control flow, domain adaptation, continual learning and training primitives, and Extensions for turning a package we did not bundle — Cedalion, or anything on the curated shelf — into blocks on this same canvas.