Aes2376: Created page with "==Synopsis== '''BCI2000 to BIDS Converter''' (`bci2000-bids`) is an open-source Python tool for converting BCI2000 `.dat` 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..."

2026-09-28T23:58:39Z

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]]

BCI2000 to BIDS Converter - Revision history

Aes2376 at 00:03, 29 September 2026

← 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==