BCI2000 Wiki - Recent changes [en]

BCI2000 to BIDS Converter

Aes2376 — Tue, 29 Sep 2026 00:03:34 GMT

← Older revision		Revision as of 00:03, 29 September 2026
Line 37:		Line 37:
	</pre>		</pre>

	~~<!-- Add the public source-~~code ~~repository URL here when the repository is published~~. -->		Source code:

			[https://github.com/alexanderspeer/BCI2000-to-BIDS-Converter BCI2000 to BIDS Converter on GitHub]

	The converter relies on BCI2000Tools for reading BCI2000 recordings. See [[BCI2000Tools.EventRelated\|BCI2000Tools]] for information about BCI2000's Python tools.		The converter relies on BCI2000Tools for reading BCI2000 recordings. See [[BCI2000Tools.EventRelated\|BCI2000Tools]] for information about BCI2000's Python tools.
Line 1,230:		Line 1,232:
	# [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].		# [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].
	# [https://bids-standard.github.io/bids-validator/ BIDS Validator].		# [https://bids-standard.github.io/bids-validator/ BIDS Validator].
			# frederik-lam. [https://github.com/Cybernetics-and-Motor-Physiology-Lab/BCI2000-BIDS_converter BCI2000-BIDS_converter]. Cybernetics-and-Motor-Physiology-Lab. MATLAB-based framework for converting BCI2000 <code>.dat</code> recordings into BIDS-compatible electrophysiology datasets.

	==See also==		==See also==

BCI2000 to BIDS Converter

Aes2376 — Mon, 28 Sep 2026 23:58:39 GMT

Created page with "==Synopsis== '''BCI2000 to BIDS Converter''' (<code>bci2000-bids</code>) is an open-source Python tool for converting BCI2000 <code>.dat</code> recordings into datasets organized according to the [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)]. The converter reads signals, parameters, state definitions, and state values stored in a BCI2000 data file and maps them into BIDS-compatible electrophysiology, event, motion, and metadata files. The convert..."

New page

==Synopsis==

'''BCI2000 to BIDS Converter''' (<code>bci2000-bids</code>) is an open-source Python tool for converting BCI2000 <code>.dat</code> recordings into datasets organized according to the [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)].

The converter reads signals, parameters, state definitions, and state values stored in a BCI2000 data file and maps them into BIDS-compatible electrophysiology, event, motion, and metadata files.

The converter supports:

* Behavioral/state-only BIDS datasets.
* EEG datasets.
* Intracranial EEG (iEEG) datasets, including ECoG, SEEG, and DBS recordings.
* Conversion of BCI2000 signal channels to EDF.
* Conversion of BCI2000 state transitions into <code>*_events.tsv</code>.
* Conversion of continuous BCI2000 states into BIDS motion files.
* Reusable JSON or YAML state-routing profiles.
* Automatic generation of review-required starter profiles.
* Conversion of multiple <code>.dat</code> files into sequential BIDS runs.
* Optional preservation of the original BCI2000 files in <code>sourcedata/</code>.
* SHA-256 checksums for preserved source recordings.
* Command-line and graphical interfaces.
* Optional validation using the [https://bids-standard.github.io/bids-validator/ BIDS Validator].

The converter is intended for offline organization and export of data that have already been recorded by BCI2000. It does not modify the original <code>.dat</code> recordings.

==Project Source==

The Python package and command-line program are named:

<pre>
bci2000-bids
</pre>

The Python import package is:

<pre>
bci2000_bids
</pre>



The converter relies on BCI2000Tools for reading BCI2000 recordings. See [[BCI2000Tools.EventRelated|BCI2000Tools]] for information about BCI2000's Python tools.

==Versioning==

===Author===

'''Alexander Speer'''

Friedman Lab, Department of Neurosurgery

Washington University in St. Louis

Developed in the Friedman Lab.

Contact: speer@wustl.edu

===Version History===

Current software version: '''0.1.0'''

The initial implementation provides:

* Reading of BCI2000 <code>.dat</code> recordings using BCI2000Tools.
* Single-file and multi-file conversion.
* Deterministic BIDS run numbering.
* Behavioral, EEG, and iEEG output.
* EDF electrophysiology output.
* BIDS event generation from BCI2000 states.
* BIDS motion output from continuous BCI2000 states.
* JSON and YAML state-routing profiles.
* Automatic starter-profile generation.
* Source-file preservation and SHA-256 checksums.
* Staged conversion and protected publication of output datasets.
* Command-line interface.
* Tkinter graphical interface.
* Optional BIDS validation.

The software requires Python 3.10 or newer.

==Functional Description==

===BCI2000 Data Model===

A standard BCI2000 <code>.dat</code> file contains the recorded signal together with BCI2000 parameters and states. See [[Technical Reference:BCI2000 File Format|BCI2000 File Format]] for the complete native format specification.

The converter uses these components differently:

{| class="wikitable"
! BCI2000 information
! Use by the converter
|-
| Signal channels
| May be exported as BIDS EEG or iEEG electrophysiology data.
|-
| Sampling rate
| Used as the sampling frequency of the exported recording and motion data.
|-
| Channel names
| Used to name channels in the electrophysiology output.
|-
| Channel units
| Used when constructing the BIDS channel table and EDF output.
|-
| State definitions
| Used to identify states that may be mapped to events, event metadata, or continuous motion channels.
|-
| State samples
| Used to generate event timing and continuous motion data.
|-
| Parameters
| Used to obtain selected recording metadata such as sampling rate, channel names, channel units, application, signal source, and data format.
|}

Not every BCI2000 state or parameter is automatically exported. State routing is controlled by a conversion profile so that the scientific meaning of study-specific states remains under user control.

===Conversion Pipeline===

The overall conversion process is:

<pre>
BCI2000 .dat recording(s)
|
v
BCI2000Tools reader
|
+---- signal channels
|
+---- parameters
|
+---- state definitions and values
|
v
State-routing profile
|
+---- event states --------> *_events.tsv
|
+---- event metadata ------> additional event columns
|
+---- continuous states ---> motion/*.tsv
|
+---- ignored states
|
v
BIDS writers
|
+---- EEG/iEEG EDF
+---- channels.tsv
+---- JSON sidecars
+---- events.tsv
+---- motion files
+---- participants.tsv
+---- dataset_description.json
|
v
Optional BIDS validation
</pre>

For a normal conversion, the software:

# Loads the optional conversion configuration.
# Resolves subject, session, task, datatype, neural-export, preservation, and output settings.
# Normalizes BIDS labels.
# Discovers input <code>.dat</code> files.
# Sorts the files and assigns sequential BIDS run numbers.
# Loads the requested state-routing profile.
# If no profile is supplied, analyzes the first recording and generates a review-required starter profile.
# Creates a temporary staging dataset.
# Reads each BCI2000 recording.
# Extracts states referenced by the active profile.
# Generates BIDS events and/or motion data.
# Writes electrophysiology data if neural export is enabled.
# Optionally copies source data and calculates checksums.
# Optionally validates the staged BIDS dataset.
# Publishes the completed dataset.

The original <code>.dat</code> files are read-only during normal conversion.

==Supported Input==

===BCI2000 Files===

The converter accepts:

* A single BCI2000 <code>.dat</code> file.
* Multiple <code>.dat</code> files.
* A directory containing <code>.dat</code> files.
* A directory tree containing <code>.dat</code> files when recursive discovery is enabled.

For directory input, normal discovery searches the immediate directory.

Recursive discovery may be enabled with:

<pre>
--recursive
</pre>

Input recordings are sorted deterministically. Each discovered recording becomes a separate BIDS run beginning with <code>run-01</code>.

For example:

<pre>
recording1.dat -> run-01
recording2.dat -> run-02
recording3.dat -> run-03
</pre>

The converter does not currently infer recording groups from BCI2000 metadata. The supplied files are treated as recordings belonging to the subject/session/task selected for that conversion.

Duplicate source filenames are rejected even if the files originate from different directories.

===Reading BCI2000 Data===

BCI2000 files are opened using:

<pre>
BCI2000Tools.FileReader.bcistream
</pre>

The reader obtains:

* Parameters.
* State definitions.
* Sampling frequency.
* Number of samples.
* Number of channels.
* Channel names.
* Channel units.

Signal and state arrays are decoded when required by the requested conversion.

The sampling frequency is first obtained from the BCI2000 <code>SamplingRate</code> parameter. If that cannot be interpreted, the sampling frequency reported by the BCI2000Tools stream is used.

Channel names are normally obtained from:

<pre>
ChannelNames
</pre>

If valid channel names are unavailable, fallback names are generated:

<pre>
ch001
ch002
ch003
...
</pre>

Channel units are read from:

<pre>
SourceChUnits
</pre>

When units are unavailable for neural EDF output, the converter currently uses <code>uV</code> as the fallback unit.

The converter requests calibrated signal values from BCI2000Tools.

===Companion Files===

The current converter operates on information embedded in BCI2000 <code>.dat</code> files.

It does not automatically ingest companion files such as separate parameter files, video files, imaging files, or other study-specific files.

==BIDS Output==

===Supported BIDS Datatypes===

The converter currently supports:

{| class="wikitable"
! Datatype
! Purpose
! Neural export
|-
| <code>beh</code>
| Behavioral/state-only data
| No
|-
| <code>eeg</code>
| Scalp EEG recordings
| Yes
|-
| <code>ieeg</code>
| Intracranial electrophysiology
| Yes
|}

For iEEG conversion, the neural channel type may be specified as:

* <code>ECOG</code>
* <code>SEEG</code>
* <code>DBS</code>

Channels beginning with <code>ECG</code> or <code>EKG</code> are classified as ECG channels.

===Generated Dataset Structure===

A conversion containing iEEG, events, motion data, and preserved source data may produce a structure similar to:

<pre>
bids/
├── dataset_description.json
├── participants.tsv
├── participants.json
├── sub-001/
│ └── ses-01/
│ ├── ieeg/
│ │ ├── sub-001_ses-01_task-motor_run-01_ieeg.edf
│ │ ├── sub-001_ses-01_task-motor_run-01_ieeg.json
│ │ ├── sub-001_ses-01_task-motor_run-01_channels.tsv
│ │ ├── sub-001_ses-01_task-motor_run-01_events.tsv
│ │ └── sub-001_ses-01_task-motor_run-01_events.json
│ └── motion/
│ ├── sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.tsv
│ ├── sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.json
│ └── sub-001_ses-01_task-motor_run-01_tracksys-unknown_channels.tsv
├── sourcedata/
│ └── sub-001/
│ └── ses-01/
│ └── bci2000/
│ ├── recording.dat
│ └── checksums.tsv
└── code/
└── bci2000-bids/
└── auto-profile-motor.json
</pre>

The <code>code/bci2000-bids/auto-profile-*.json</code> file is generated only when automatic profile generation is used.

Behavioral-only conversion does not create a placeholder electrophysiology file.

===Dataset-Level Files===

The converter creates or maintains:

* <code>dataset_description.json</code>
* <code>participants.tsv</code>
* <code>participants.json</code>

The generated dataset description identifies the dataset as raw BIDS data and records <code>bci2000-bids</code> as conversion software.

The implementation writes BIDS version:

<pre>
1.10.1
</pre>

The participant table initially contains the BIDS participant identifier.

Study-specific clinical information is not automatically inferred from BCI2000 recordings.

==BCI2000 State Profiles==

===Purpose===

BCI2000 applications may define many study-specific states. Their names alone are not sufficient to determine their scientific meaning.

For this reason, the converter uses a '''state-routing profile''' to determine how states should be represented in BIDS.

Profiles may be written in:

* JSON.
* YAML.

A state may be assigned to:

* An event.
* An additional event column.
* A continuous motion channel.
* The ignore list.

A state should not be assigned to multiple routing categories.

===Example Profile===

A simple profile may look like:

<pre>
name: generic-motion

metadata:
tracking_system: unknown

events:
Marker:
strategy: rising_edge
trial_type: marker

motion:
PositionX:
column: position_x
type: POSITION
units: arbitrary

ignore:
- SourceTime
</pre>

In this example:

* <code>Marker</code> creates BIDS event rows.
* <code>PositionX</code> becomes a continuous BIDS motion channel.
* <code>SourceTime</code> is deliberately ignored.

===Profile Validation===

Profiles are checked before conversion.

Invalid profiles include cases such as:

* Invalid JSON or YAML.
* Unsupported event strategies.
* Duplicate state routing.
* Invalid event-column definitions.
* Duplicate event-column names.
* Reserved event-column names.
* Invalid motion definitions.
* Invalid metadata structures.

The standard BIDS event fields:

<pre>
onset
duration
trial_type
</pre>

are reserved and cannot be redefined as custom event columns.

==Automatic Profile Generation==

If a profile is not supplied, the converter may inspect the first recording and create a starter profile.

The automatic profile generator examines properties such as:

* State name.
* State bit width.
* Minimum value.
* Maximum value.
* Number of unique values.
* Number of transitions.
* Transition fraction.
* Number of nonzero samples.
* Percentage of nonzero samples.

States with names suggesting continuously varying signals such as joystick, cursor, gaze, position, or similar values may be proposed as motion channels.

Low-cardinality or event-like states may be proposed as events.

Internal-looking states such as:

* <code>SourceTime</code>
* <code>Running</code>
* <code>Recording</code>

may be proposed for exclusion.

Automatically generated profiles contain:

<pre>
"review_required": true
</pre>

and are saved inside the BIDS dataset under:

<pre>
code/bci2000-bids/
</pre>

'''Automatically generated profiles are suggestions and should be reviewed before scientific use.''' The converter cannot determine the experimental meaning of a state from its name or numeric behavior alone.

==Event Conversion==

BCI2000 states may be converted into BIDS <code>*_events.tsv</code> rows.

The base event table contains:

<pre>
onset duration trial_type
</pre>

Onsets and durations are expressed in seconds.

===Event Strategies===

The following event strategies are supported:

{| class="wikitable"
! Strategy
! Behavior
|-
| <code>rising_edge</code>
| Creates an event when the state changes from zero to nonzero.
|-
| <code>falling_edge</code>
| Creates an event when the state changes from nonzero to zero.
|-
| <code>change</code>
| Creates an event whenever the state value changes.
|-
| <code>value_change</code>
| Creates an event whenever the state value changes.
|-
| <code>nonzero_change</code>
| Creates an event when a transition results in a nonzero value.
|-
| <code>interval</code>
| Treats each continuous nonzero period as an event interval.
|}

Edge and value-change events have zero duration.

For <code>interval</code>, the duration corresponds to the length of the contiguous nonzero period.

===Additional Event Columns===

Other BCI2000 states may be mapped as additional columns associated with generated events.

For example, a task may use one state to trigger an event while states such as condition, target, block, response type, or trial number are sampled at that event and placed into additional TSV columns.

Additional nonstandard columns are described in the corresponding <code>*_events.json</code> sidecar.

An additional event-column mapping by itself does not create an event. An event rule must first define when event rows are generated.

==Motion and Continuous State Conversion==

Continuously varying BCI2000 states may be written to the BIDS <code>motion/</code> directory.

Examples may include states representing:

* Joystick position.
* Cursor position.
* Eye position.
* Gaze position.
* Limb position.
* Other continuous task or kinematic variables.

The converter does not determine these meanings automatically during normal conversion. The user specifies them through the state-routing profile.

A typical motion output consists of:

<pre>
sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.tsv
sub-001_ses-01_task-motor_run-01_tracksys-unknown_motion.json
sub-001_ses-01_task-motor_run-01_tracksys-unknown_channels.tsv
</pre>

The motion TSV is headerless.

Column information is stored in the motion channels TSV:

<pre>
name type units description
</pre>

A motion mapping may define:

* Column name.
* Motion type.
* Units.
* Description.

The associated JSON sidecar records information such as:

* Sampling frequency.
* Start time.
* Column order.
* Tracking-system name.

All motion states in one output file must contain the same number of samples.

==Neural Signal Conversion==

When neural export is enabled, BCI2000 signal channels are exported as EDF.

The converter currently supports:

* EEG EDF output.
* iEEG EDF output.

The BCI2000 signal matrix is read with calibration gains applied and converted into the orientation required by the output writer.

A corresponding BIDS channel table contains:

<pre>
name type units
</pre>

For EEG, channels normally use the BIDS channel type:

<pre>
EEG
</pre>

For iEEG, the channel type is selected from:

<pre>
ECOG
SEEG
DBS
</pre>

The electrophysiology JSON sidecar includes information such as:

* Task name.
* Sampling frequency.
* Recording duration.
* Reference.
* Source system.
* Conversion software.

The source system is identified as:

<pre>
BCI2000
</pre>

The conversion software is identified as:

<pre>
bci2000-bids
</pre>

==Installation==

===Requirements===

Python '''3.10 or newer''' is required.

The primary Python dependencies are:

* <code>numpy</code>
* <code>pyEDFlib</code>
* <code>PyYAML</code>
* <code>BCI2000Tools</code>

Tkinter is required for the graphical interface.

===Recommended Installation===

From a local checkout of the repository, create a Python virtual environment.

On macOS or Linux:

<pre>
python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
</pre>

On Windows PowerShell:

<pre>
py -3.14 -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
</pre>

The package also defines installation extras for BCI2000 and YAML support:

<pre>
python -m pip install -e ".[yaml,bci2000]"
</pre>

For development:

<pre>
python -m pip install -e ".[yaml,bci2000,dev]"
</pre>

On Debian or Ubuntu systems, Tkinter may need to be installed separately:

<pre>
sudo apt install python3-tk
</pre>

The external BIDS Validator is not installed automatically with the Python package.

==Graphical Interface==

The graphical interface may be launched with:

<pre>
bci2000-bids-gui
</pre>

or:

<pre>
python -m bci2000_bids.gui
</pre>

It may also be launched from the main command:

<pre>
bci2000-bids gui
</pre>

The GUI supports:

* Selecting one or more <code>.dat</code> files.
* Selecting an input directory.
* Recursive input discovery.
* Selecting a BIDS output directory.
* Subject label entry.
* Session label entry.
* Task label entry.
* Behavioral, EEG, or iEEG datatype selection.
* ECoG, SEEG, or DBS iEEG channel-type selection.
* Enabling or disabling neural export.
* Loading an existing profile.
* Creating a profile using an interactive state-routing editor.
* Automatic starter-profile generation.
* Source preservation.
* SHA-256 checksum generation.
* Existing-output policy selection.
* Recording inspection.
* Dry runs.
* Conversion.
* Optional BIDS validation.
* Progress and status reporting.

The default GUI configuration uses:

* Session <code>01</code>.
* Datatype <code>beh</code>.
* Neural export disabled.
* BIDS validation enabled.
* Existing-output policy <code>error</code>.

==Command-Line Interface==

The command-line program is:

<pre>
bci2000-bids
</pre>

The equivalent module invocation is:

<pre>
python -m bci2000_bids
</pre>

The primary commands are:

<pre>
inspect
convert
profile
validate
gui
</pre>

===Inspect===

To inspect one BCI2000 recording without converting it:

<pre>
bci2000-bids inspect recording.dat
</pre>

Inspection reports information including:

* File name.
* Resolved path.
* Recording duration.
* Sampling frequency.
* Number of channels.
* Number of samples.
* Channel names.
* State names.
* State bit widths.
* Selected BCI2000 parameters.

Selected parameters include:

* <code>SamplingRate</code>
* <code>DataFormat</code>
* <code>Application</code>
* <code>SignalSource</code>
* <code>ChannelNames</code>
* <code>SourceChUnits</code>

===Generate a Profile===

A starter state-routing profile may be generated with:

<pre>
bci2000-bids profile recording.dat --output profile.json
</pre>

If <code>--output</code> is omitted, the generated JSON profile is printed to standard output.

The profile should be reviewed before conversion.

===Basic Conversion===

A basic iEEG conversion is:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG
</pre>

===Behavioral/State-Only Conversion===

To convert states without neural data:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype beh \
--no-neural \
--profile profile.json
</pre>

===Directory Conversion===

To recursively discover BCI2000 files:

<pre>
bci2000-bids convert incoming/ \
--output bids/ \
--subject 001 \
--session 01 \
--task motor \
--datatype eeg \
--recursive
</pre>

===Source Preservation===

To retain the original BCI2000 recordings:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--preserve-source
</pre>

===Validation During Conversion===

To run BIDS validation before publishing the converted dataset:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--validate
</pre>

===Dry Run===

A conversion may be checked without publishing the final dataset using:

<pre>
--dry-run
</pre>

A dry run performs discovery, profile/configuration resolution, run assignment, and destination checking without publishing the final converted dataset.

===Debug Logging===

The global debugging option is:

<pre>
bci2000-bids --debug ...
</pre>

<code>--debug</code> must appear before the subcommand.

==Typical Workflow==

A typical command-line workflow is:

===1. Inspect the recording===

<pre>
bci2000-bids inspect recording.dat
</pre>

===2. Generate a starter profile===

<pre>
bci2000-bids profile recording.dat --output profile.json
</pre>

===3. Review the profile===

Inspect the generated state mappings and confirm that each BCI2000 state has been assigned to the correct scientific role.

In particular, confirm which states represent:

* Experimental events.
* Event metadata.
* Continuous behavioral or motion signals.
* States that should be ignored.

===4. Perform a dry run===

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--dry-run
</pre>

===5. Convert===

<pre>
bci2000-bids convert recording.dat \
--output bids \
--subject 001 \
--session 01 \
--task motor \
--datatype ieeg \
--channel-type ECOG \
--profile profile.json \
--preserve-source
</pre>

===6. Validate===

<pre>
bci2000-bids validate bids/
</pre>

==Configuration Files==

In addition to state-routing profiles, general conversion settings may be stored in JSON or YAML configuration files.

A configuration may contain fields such as:

* Subject.
* Session.
* Task.
* Datatype.
* Neural export.
* iEEG channel type.
* Source preservation.
* Existing-output behavior.
* Profile path.

For example:

<pre>
subject: "001"
session: "01"
task: "motor"
datatype: "beh"
preserve_source: true
profile: "generic-motion.yaml"
</pre>

A configuration may be supplied with:

<pre>
bci2000-bids convert recording.dat \
--output bids \
--config examples/configs/study.yaml
</pre>

Command-line configuration handling is still under development. Explicit <code>--subject</code> and <code>--task</code> arguments should currently be supplied for reliable noninteractive CLI use.

==Existing Output Handling==

The converter protects existing BIDS data by default.

The existing-output policy may be selected using:

<pre>
--on-existing
</pre>

Supported values are:

{| class="wikitable"
! Value
! Behavior
|-
| <code>error</code>
| Default. Stop if the target subject/session already exists.
|-
| <code>skip</code>
| Leave the existing subject/session unchanged and skip conversion.
|-
| <code>overwrite</code>
| Rebuild the requested subject/session while retaining other dataset content.
|}

The default policy is:

<pre>
error
</pre>

==Source Data Preservation==

When:

<pre>
--preserve-source
</pre>

is enabled, the original BCI2000 recording is copied to:

<pre>
sourcedata/sub-<subject>/ses-<session>/bci2000/
</pre>

For example:

<pre>
sourcedata/sub-001/ses-01/bci2000/recording.dat
</pre>

A SHA-256 checksum manifest is written as:

<pre>
sourcedata/sub-001/ses-01/bci2000/checksums.tsv
</pre>

with columns:

<pre>
filename sha256
</pre>

The preserved BCI2000 files are copies of the original recordings and are '''not anonymized by the converter'''.

Users should therefore review BCI2000 parameters and other source metadata before distributing <code>sourcedata/</code> outside the research environment.

==Data Safety==

Conversions are built in a temporary staging directory rather than directly modifying the published BIDS dataset.

When updating an existing dataset:

# The current dataset is copied into a staging location.
# New conversion output is created in staging.
# Validation may be performed against the staged dataset.
# The original dataset is retained until processing succeeds.
# The staged dataset is moved into place after successful conversion.

When replacement of an existing output root is necessary, the current output is temporarily renamed to a backup location before publication of the staged dataset.

If publication fails, the converter attempts to restore the previous dataset.

EDF files are also created through temporary output before final replacement.

Additional input checks include rejection of:

* Duplicate input basenames.
* Invalid subject labels.
* Invalid session labels.
* Invalid task labels.
* Invalid tracking-system names.
* Invalid iEEG channel types.
* Missing states required by a profile.
* Invalid signal dimensions.
* Duplicate or invalid EDF channel labels.
* Nonfinite neural samples.
* Certain EDF-incompatible signal conditions.

==BIDS Validation==

The converter includes an optional validation step.

To validate an existing converted dataset:

<pre>
bci2000-bids validate bids/
</pre>

The converter first performs basic internal checks, including confirming that:

<pre>
dataset_description.json
</pre>

exists and contains valid JSON.

When available, it then invokes the external BIDS Validator.

The [https://bids-standard.github.io/bids-validator/ official BIDS Validator] may also be used independently.

When validation is enabled during conversion, validation occurs against the staged dataset before it is published. A validation failure therefore prevents the invalid staged conversion from replacing the existing output dataset.

The external validator must currently be installed separately.

==Clinical and Participant Metadata==

The converter currently handles operational BIDS identifiers and recording metadata such as:

* Participant identifier.
* Session identifier.
* Task.
* Datatype.
* Run number.
* Sampling frequency.
* Recording duration.
* Channel names.
* Channel units.
* Neural channel type.
* Reference information.
* Motion tracking-system name.

The converter does '''not''' currently automatically extract or request study-specific clinical metadata such as:

* Diagnosis.
* Age.
* Sex.
* Handedness.
* Surgical procedure.
* Medication state.
* DBS stimulation state.
* Implant target.
* Recording location.
* Participant name.
* Medical record number.
* Date of birth.

Such metadata must be handled separately when required by a study.

==Limitations==

The current version is focused specifically on converting BCI2000 recordings and synchronized states into electrophysiology, behavioral, event, and motion components of BIDS.

The following are not currently supported:

* Imaging conversion.
* Video conversion.
* NeuroOmega file conversion.
* Automatic ingestion of BCI2000 companion files.
* Modalities other than <code>beh</code>, <code>eeg</code>, and <code>ieeg</code>.
* BrainVision output.
* FIF output.
* NIfTI output.
* Automatic grouping of recordings using BCI2000 recording metadata.
* Comprehensive export of every BCI2000 parameter into BIDS metadata.
* Automatic extraction of clinical or surgical metadata.
* Automatic anonymization of preserved BCI2000 source files.
* Automatic generation of <code>.bidsignore</code>.
* General provenance manifests beyond source checksums and generated conversion profiles.

Automatic state classification is heuristic and should not be treated as a substitute for knowledge of the experiment.

==Development and Testing==

The project contains unit and integration tests for core conversion functionality.

Current automated testing covers areas including:

* BIDS dataset initialization.
* Dataset descriptions.
* Participant-table creation.
* BIDS label normalization.
* BIDS run naming.
* Rising-edge event generation.
* Interval event generation.
* State-change event generation.
* Motion TSV output.
* Motion channel definitions.
* Duplicate state-routing rejection.
* BCI2000 parameter parsing utilities.
* Deterministic input discovery.
* Recursive input discovery.
* Synthetic state/event conversion.
* Synthetic iEEG EDF conversion.
* EDF read-back using pyEDFlib.
* Missing-unit fallback behavior.

The current integration tests use synthetic/mock BCI2000 recordings rather than decoding real clinical or experimental BCI2000 files.

Real BCI2000 files should therefore be tested and reviewed in the intended research environment before relying on a new conversion workflow for production datasets.

==BIDS Background==

[https://bids.neuroimaging.io/ BIDS] is a community-developed standard for organizing neural and associated experimental data in a consistent filesystem structure.

A typical BIDS hierarchy follows the general form:

<pre>
dataset/
└── sub-<subject>/
└── ses-<session>/
└── <datatype>/
</pre>

Within this structure, file names encode entities such as subject, session, task, and run.

The BCI2000 to BIDS Converter performs this transformation automatically for supported BCI2000 data while retaining synchronization between neural signals and selected BCI2000 states.

For the complete standard, see the [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].

==References==

# Gorgolewski KJ, Auer T, Calhoun VD, et al. [https://doi.org/10.1038/sdata.2016.44 The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments]. ''Scientific Data''. 2016;3:160044. doi:10.1038/sdata.2016.44.
# [https://bids.neuroimaging.io/ Brain Imaging Data Structure (BIDS)].
# [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification].
# [https://bids-standard.github.io/bids-validator/ BIDS Validator].

==See also==

* [[Technical Reference:BCI2000 File Format|BCI2000 File Format]]
* [[User Reference:Data File Formats|BCI2000 Data File Formats]]
* [[User Reference:BCI2000Export|BCI2000Export]]
* [[User Reference:Command Line Processing|BCI2000 Command Line Processing]]
* [[BCI2000Tools.EventRelated|BCI2000Tools and Python Data Analysis]]
* [[User Tutorial:Data Analysis|BCI2000 Data Analysis Tutorials]]
* [https://bids.neuroimaging.io/ Brain Imaging Data Structure]
* [https://bids-specification.readthedocs.io/en/stable/ BIDS Specification]
* [https://bids-standard.github.io/bids-validator/ BIDS Validator]

[[Category:Data Analysis Tools]]

Contributions:NetworkHID

Tytbutler — Sat, 26 Sep 2026 04:39:57 GMT

← Older revision		Revision as of 04:39, 26 September 2026
(4 intermediate revisions by the same user not shown)
Line 22:		Line 22:
	A NetworkHID setup consists of one computer running BCI2000, and a microcontroller connected to a target device. The microcontroller acts as a wireless access point, that is, the BCI2000 computer can connect to it over Wi-Fi, and can then send it commands. These commands can direct the microcontroller to press and release keys or mouse buttons, as well as move the mouse of the target device. In this way, BCI2000 can control the target device, either mirroring the keyboard and mouse inputs of the BCI2000 via the extension, or sending inputs in response to BCI2000's internal state, for example, moving the mouse in accordance with the cursor in a Cursor Task, or entering the chosen letters in a Speller Task.		A NetworkHID setup consists of one computer running BCI2000, and a microcontroller connected to a target device. The microcontroller acts as a wireless access point, that is, the BCI2000 computer can connect to it over Wi-Fi, and can then send it commands. These commands can direct the microcontroller to press and release keys or mouse buttons, as well as move the mouse of the target device. In this way, BCI2000 can control the target device, either mirroring the keyboard and mouse inputs of the BCI2000 via the extension, or sending inputs in response to BCI2000's internal state, for example, moving the mouse in accordance with the cursor in a Cursor Task, or entering the chosen letters in a Speller Task.

	===NetworkHID ~~Device~~ Details===		===NetworkHID Protocol Details===

	When a computer connects to the microcontroller's Wi-Fi network, the microcontroller itself will also be present on the network with its own IP address. This address is device-dependent, but on a Pi Pico 2 W, it is <code>192.168.4.1</code>. It will expose a port (by default <code>1024</code> as set in <code>code.py</code>) to receive commands.		When a computer connects to the microcontroller's Wi-Fi network, the microcontroller itself will also be present on the network with its own IP address. This address is device-dependent, but on a Pi Pico 2 W, it is <code>192.168.4.1</code>. It will expose a port (by default <code>1024</code> as set in <code>code.py</code>) to receive commands.
Line 54:		Line 54:
	These depend on the '''Type''', as detailed below		These depend on the '''Type''', as detailed below

	====NetworkHID Commands====		===NetworkHID Commands===

	These commands use the Adafruit HID library to emulate an HID.		These commands use the Adafruit HID library to emulate an HID.
Line 71:		Line 71:
	=====Mouse Button=====		=====Mouse Button=====
	Press or release mouse buttons. '''Arg1''' and '''Arg2''' correspond to buttons Mouse 1 and Mouse 2. If the argument is 1, the button is pressed, and if the argument is 0, the button is released.		Press or release mouse buttons. '''Arg1''' and '''Arg2''' correspond to buttons Mouse 1 and Mouse 2. If the argument is 1, the button is pressed, and if the argument is 0, the button is released.


	==Building a NetworkHID device==		==Building a NetworkHID device==
Line 77:		Line 76:
	The NetworkHID CircuitPython code has been tested with a Raspberry Pi Pico 2 W microcontroller, although theoretically it should work on any device which supports CircuitPython and is capable of acting as a wireless access point.		The NetworkHID CircuitPython code has been tested with a Raspberry Pi Pico 2 W microcontroller, although theoretically it should work on any device which supports CircuitPython and is capable of acting as a wireless access point.

	Acquire a microcontroller and ~~install CircuitPython onto it~~ [https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython].		Acquire a microcontroller and [https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython install CircuitPython on it].

	After installing CircuitPython, the microcontroller should appear as a storage device when plugged into your computer. Copy the <code>code.py</code> file into the device, replacing the existing one. (This file can be found within the BCI2000 source code at <code>src/extlib/NetworkHID/code.py</code>. Alternatively, it is also located externally at [https://codeberg.org/personator01/bci2000-nethid].		After installing CircuitPython, the microcontroller should appear as a storage device when plugged into your computer. Copy the <code>code.py</code> file into the device, replacing the existing one. (This file can be found within the BCI2000 source code at <code>src/extlib/NetworkHID/code.py</code>. Alternatively, it is also located externally at https://codeberg.org/personator01/bci2000-nethid.

	Once you plug the microcontroller into the target device, it will begin to act as a wireless access point. It will host a Wi-Fi network, with default name <code>"pico"</code> and default password <code>"pass12345"</code> (these values can be changed by editing the <code>code.py</code> file). On the BCI2000 computer, connect to this Wi-Fi network.		Once you plug the microcontroller into the target device, it will begin to act as a wireless access point. It will host a Wi-Fi network, with default name <code>"pico"</code> and default password <code>"pass12345"</code> (these values can be changed by editing the <code>code.py</code> file). On the BCI2000 computer, connect to this Wi-Fi network.
Line 113:		Line 112:
	==Implementing NetworkHID communication within a custom module==		==Implementing NetworkHID communication within a custom module==

	For behavior beyond just mirroring the keyboard and mouse inputs of the host machine, the NetworkHID can be used from a custom BCI2000 module. The <code>NetworkHID</code> class provides an interface within BCI2000 for sending commands to the microcontroller. Its interface is located within <code>src/extlib/NetworkHID/NetworkHID.h</code>. Additionally, the [https://codeberg.org/personator01/bci2000-nethid\|external git repository for NetworkHID] contains examples of it being used within a custom Cursor Task, and a P3 Speller task.		For behavior beyond just mirroring the keyboard and mouse inputs of the host machine, the NetworkHID can be used from a custom BCI2000 module. The <code>NetworkHID</code> class provides an interface within BCI2000 for sending commands to the microcontroller. Its interface is located within <code>src/extlib/NetworkHID/NetworkHID.h</code>. Additionally, the [https://codeberg.org/personator01/bci2000-nethid external git repository for NetworkHID] contains examples of it being used within a custom Cursor Task, and a P3 Speller task.

Contributions:NetworkHID

Tytbutler — Fri, 25 Sep 2026 11:37:14 GMT

Created page with "==Synopsis== Functionality for sending commands from BCI2000 to an external USB device which emulates a USB Human Interface Device (HID), that is, a keyboard and mouse. This consists of three components: a snippet of Python code which runs on a CircuitPython-capable microcontroller with Wi-Fi and USB functionality, a C++ class within BCI2000 which provides an interface for sending commands to the microcontroller from within a BCI2000 module, and an BCI2000 extension whi..."

New page

==Synopsis==

Functionality for sending commands from BCI2000 to an external USB device which emulates a USB Human Interface Device (HID), that is, a keyboard and mouse. This consists of three components: a snippet of Python code which runs on a CircuitPython-capable microcontroller with Wi-Fi and USB functionality, a C++ class within BCI2000 which provides an interface for sending commands to the microcontroller from within a BCI2000 module, and an BCI2000 extension which mirrors mouse and keyboard from the BCI2000 computer to the microcontroller.

==Location==
Microcontroller code:
http://{{SERVERNAME}}/svn/trunk/src/extlib/NetworkHID/code.py

BCI2000 internal interface
http://{{SERVERNAME}}/svn/trunk/src/extlib/NetworkHID/

BCI2000 Extension
http://{{SERVERNAME}}/svn/trunk/src/extlib/NetworkHID/

===Authors===
Ty Butler (butler@neurotechcenter.org)

==Functional Description==

Certain assistive devices allow input only via USB keyboard and mouse. Enabling BCI2000 to send keyboard and mouse inputs allows for the control of these devices by biosignal data.

A NetworkHID setup consists of one computer running BCI2000, and a microcontroller connected to a target device. The microcontroller acts as a wireless access point, that is, the BCI2000 computer can connect to it over Wi-Fi, and can then send it commands. These commands can direct the microcontroller to press and release keys or mouse buttons, as well as move the mouse of the target device. In this way, BCI2000 can control the target device, either mirroring the keyboard and mouse inputs of the BCI2000 via the extension, or sending inputs in response to BCI2000's internal state, for example, moving the mouse in accordance with the cursor in a Cursor Task, or entering the chosen letters in a Speller Task.

===NetworkHID Device Details===

When a computer connects to the microcontroller's Wi-Fi network, the microcontroller itself will also be present on the network with its own IP address. This address is device-dependent, but on a Pi Pico 2 W, it is <code>192.168.4.1</code>. It will expose a port (by default <code>1024</code> as set in <code>code.py</code>) to receive commands.

A NetworkHID command consists of 16 bytes, in the following format:

{| class="wikitable" style="text-align: center;"
|-
! 0 !! 1 !! 2 !! 3 !! 4 !! 5 !! 6 !! 7 !! 8 !! 9 !! 10 !! 11 !! 12 !! 13 !! 14 !! 15
|-
|colspan="4"|Magic
|colspan="4"|Type
|colspan="4"|Arg1
|colspan="4"|Arg2
|}

Each of '''Magic''', '''Type''', '''Arg1''', and '''Arg2''' is a 32-bit integer in big-endian form. Magic and Type are unsigned, while Arg1 and Arg2 are signed.

=====Magic=====
The constant value <code>0x0bc12000</code>.

=====Type=====
The type of command being sent. This can be one of four values:

# '''Key Press'''
# '''Key Release'''
# '''Move Mouse'''
# '''Mouse Button'''

=====Arg1 and Arg2=====
These depend on the '''Type''', as detailed below

====NetworkHID Commands====

These commands use the Adafruit HID library to emulate an HID.

=====Key Press=====
Press a key. Takes '''Arg1''' to be an ASCII character value, and presses the corresponding key, or combination of keys, necessary to input the character. The keys will remain held until they are released by a '''Key Release''' command. Currently, only ASCII characters are supported, and sending non-ASCII values will cause the device to crash, at which point it must be unplugged and plugged back in, and the client computer must reconnect to its Wi-Fi network.

=====Key Release=====
Release the keys corresponding to the ASCII key value given by '''Arg1'''.

=====Move Mouse=====
Move the mouse by ('''Arg1''','''Arg2''') units. The movement is relative to the current position of the mouse, and the units are those defined by the Adafruit HID library.

Due to limitations of the library, these values are clamped to the range (-100,100). In practice, if you are implementing precise control of the mouse using the NetworkHID, you will need to test until you find suitable movement values. Additionally, due to the relative nature of mouse movement, it may be difficult to maintain a consistent mouse position. The workaround for this is, when you need the mouse in a precise location, to move it to the top left corner of the screen to establish a known position by repeatedly sending '''Mouse Move''' commands with parameter (-100,100), and then moving the mouse to the desired location.

=====Mouse Button=====
Press or release mouse buttons. '''Arg1''' and '''Arg2''' correspond to buttons Mouse 1 and Mouse 2. If the argument is 1, the button is pressed, and if the argument is 0, the button is released.

==Building a NetworkHID device==

The NetworkHID CircuitPython code has been tested with a Raspberry Pi Pico 2 W microcontroller, although theoretically it should work on any device which supports CircuitPython and is capable of acting as a wireless access point.

Acquire a microcontroller and install CircuitPython onto it [https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython].

After installing CircuitPython, the microcontroller should appear as a storage device when plugged into your computer. Copy the <code>code.py</code> file into the device, replacing the existing one. (This file can be found within the BCI2000 source code at <code>src/extlib/NetworkHID/code.py</code>. Alternatively, it is also located externally at [https://codeberg.org/personator01/bci2000-nethid].

Once you plug the microcontroller into the target device, it will begin to act as a wireless access point. It will host a Wi-Fi network, with default name <code>"pico"</code> and default password <code>"pass12345"</code> (these values can be changed by editing the <code>code.py</code> file). On the BCI2000 computer, connect to this Wi-Fi network.

The device is now ready to receive commands from BCI2000.

==The NetworkHID Extension==
The NetworkHID extension is a source module extension that takes keyboard and mouse inputs made on the BCI2000 computer and mirrors them on the target device, via the NetworkHID microcontroller. It does this by reading the built-in <code>KeyDown</code>, <code>KeyUp</code>, <code>MousePosX</code>, <code>MousePosY</code>, and <code>MouseKeys</code> state variables, detecting when they have changed, and translating them into commands sent over the network to the microcontroller. Due to the synchronous nature of BCI2000, this happens once per sample block processing loop.

It is compiled by enabling the <code>EXTENSIONS_NETWORKHIDEXTENSION</code> CMake variable during the BCI2000 [[Programming Howto:Configure BCI2000 for Compilation|build process]] (If you have not build BCI2000 from source before, follow the instructions in [[Programming Howto:Building and Customizing BCI2000]]).

Once compiled, the NetworkHID Extension can be enabled by adding the <code>--EnableNetworkHIDLogging</code> flag to the source module in your BCI2000 startup script.

===Parameters===

=====EnableKeyboardLogging=====
Send keystrokes from the BCI2000 computer to the microcontroller.
Default: 1 (true)
=====EnableMouseMovementLogging=====
Send mouse movements from the BCI2000 computer to the microcontroller.
Default: 1 (true)
=====EnableMouseButtonLogging=====
Send mouse keypresses from the BCI2000 computer to the microcontroller.
Default: 1 (true)
=====MouseMovementLoggingScale=====
This decimal parameter scales the logged mouse movement.
Default: 1.0
=====NetworkHIDAddress=====
The network address of the microcontroller's input, in <code>ipv4:port</code> form. On a Pi Pico 2 W with default deployed <code>code.py</code>, this should be <code>192.168.4.1:1024</code>.
Default: <code>192.168.4.1:1024</code>

==Implementing NetworkHID communication within a custom module==

For behavior beyond just mirroring the keyboard and mouse inputs of the host machine, the NetworkHID can be used from a custom BCI2000 module. The <code>NetworkHID</code> class provides an interface within BCI2000 for sending commands to the microcontroller. Its interface is located within <code>src/extlib/NetworkHID/NetworkHID.h</code>. Additionally, the [https://codeberg.org/personator01/bci2000-nethid|external git repository for NetworkHID] contains examples of it being used within a custom Cursor Task, and a P3 Speller task.