Skip to content

Your own electrode carrier (montage editor)

Experimental in v1.0: the file format and the editor may change before they settle.

The toolbox ships a few stock carriers (the 10-10 occipital array, the 8-site Electro-Cap, the actiCAP 64-channel and 32-channel posterior caps, and so on). If your cap or headband is none of them, describe it once in the montage editor and pick it by name in the designer.

What a carrier is

A carrier is a name, the standard 10-10 sites you use, the amplifier channel number each one is wired to, and the electrode kind. Sites are limited to the standard 10-10 positions the toolbox already knows, so a saved carrier plots exactly like the stock ones and an analysis can name its channels. A site the toolbox does not know is refused rather than guessed.

Channel numbers run 1 to N with no gap and no repeat, in the order the amplifier delivers them. A carrier may not take the name of a built-in carrier.

Editing

In Build Protocol → Set up acquisition hardware (and in Set up Session's hardware fields), click Edit carriers… next to Headset / electrodes. Choose a saved carrier to edit or click New, then fill in the name, the electrode kind and one row per channel. The editor lists every problem it finds and enables Save only when there are none.

Where carriers are stored

One JSON file per carrier, in a carriers/ folder under your lab's design folder (the first paths.designs entry of the site profile). The folder is shared through your lab's own repository, so every acquisition PC sees the same carriers. With no design folder declared, carriers are saved to a git-ignored carriers/ folder in the checkout. The toolbox ships no carriers of its own in that folder.

{
  "schema": 1,
  "name": "My posterior cap",
  "electrode_type": "active (actiCAP)",
  "note": "",
  "channels": [
    {"channel": 1, "label": "Oz"},
    {"channel": 2, "label": "O1"},
    {"channel": 3, "label": "O2"}
  ]
}

A file that cannot be read, names an unknown site, repeats the name of another carrier, or comes from a newer toolbox is skipped and reported in the editor, and never stops the others loading.

How a recording uses it

The manifest stays authoritative. Picking a carrier copies it whole into the protocol's acquisition block: the carrier name as headset, the electrode kind as electrode_type, and the full montage with each channel's position. A run reads only that block and never reads carriers/, so a recording never depends on the file still existing. Opening a protocol on a machine that lacks the carrier file keeps the carrier the protocol names rather than substituting a stock one.

Telling two copies of one name apart

A name is not a stable key for a carrier you define yourself: you can edit the wiring and keep the name. So the copy in the acquisition block also carries carrier_hash, a short fingerprint (12 hex characters) of the wiring: each montage entry's amplifier channel and site, in order, plus the electrode kind. It is computed from the copy itself, so it can be re-checked anywhere the manifest travels. Positions and measured impedance are not part of it.

  • A copy whose wiring no longer matches its hash was edited by hand, and the manifest is refused on load and on save. Re-pick the carrier in the designer instead.
  • The recorded run keeps the hash. The analysis report and the batch log show it in brackets beside the headset name, and the per-run metrics record it.
  • A contrast refuses a within-subject pair whose two runs were made on different wirings, and says so in its notes when pooled runs differ.
  • Stock carriers carry no hash (their name identifies them), and neither do manifests written before the field existed; both keep working unchanged. The field is optional and additive, so the manifest version does not change.

Which devices offer them

The OpenBCI boards accept any carrier. The actiCHamp offers its two stock actiCAP layouts (64-channel, and the 32-channel posterior cap) and your saved carriers, because the operator must say which cap is on the participant (any other partly-populated cap is a carrier with fewer channels, and the bridge trims the stream to its length). A device with moulded-in electrodes, such as the Unicorn, offers only its own.

A carrier does not carry a reference or ground site. Reference and ground follow the amplifier, as for any carrier the toolbox does not wire itself.