Bids Compatibility

The brain imaging data structure (BIDS) is a standard-in-development. This includes specifications for EEG data which is very relevant for BCI research. BIDS in general is described here https://bids-specification.readthedocs.io/en/stable/ The motivation is to reduce the amount of time wasted rearranging data by having it arranged in a specified structure. This is becoming increasingly important as more and more journals are requiring the publication of data.

There are common principles for all BIDS data types and principles specific to EEG. The paper explaining EEG BIDS can be found here EEG-BIDS Paper. There is a BIDS Validator to check to make sure that your data is BIDS compliant. The BIDS format

Modality Agnostic BIDS Files

The modality agnostic files are outlined in detail here. I have included below a summary of the files and which ones I think we should include.

• README (required)
  • Includes a detailed description of the dataset
• CHANGES (optional)
  • Must follow CPAN Changelog convention if it is included
  • I think we should include
• LICENSE (optional)
  • We will need to decide on a license, then it can be included either here OR in the dataset_description.json
• dataset_description.json (required)
  • Includes at least the Name and BIDS Version (this page is based on v1.8.0)
  • Recommended to include HEDVersion (if HED tags are used), DatasetLinks, DatasetType, License, Authors
• participants.tsv (optional)
  • By default includes age, sex, handedness, can be extended to include other measures such as group, bci experience, etc.
  • I think we should include these defaults whenever we have them, and should discuss any other data we want to include here such as bci experience,
• participants.json (optional)
  • This is highly recommended if participants.tsv includes more than age, sex, handedness, species
• samples.tsv and samples.json
  • This is only required if sample data is included in the dataset, which I don’t believe we have and so don’t need this part
• phenotype and assessment data (optional)
  • phenotype/<measurement_tool_name>.tsv
  • phenotype/<measurement_tool_name>.json
    • I am not 100% clear on when to use this over participants.tsv/.json, but this seems like it would be more relevant for the kids in our clinical program.
• scans (optional)
  • This includes timings and acquisition metadata for any scans that may be included with the dataset. We don’t have any so we can leave it out
• sessions (optional)
  • One per subject for studies involving more than one session, describes changing variables between sessions
  • Should be in sub-/sub-_sessions.tsv
  • Includes session_id, acq_time, for us it may also include whether that calibration session was gamified or not

EEG Specific BIDS Files

Now for the fun stuff! The EEG specific structure is where we may have to adapt more. The structure for saving EEG data is shown below. Items in [ ] are optional. We will need sessions (ses), and maybe run, but probably not acquisition (acq) or recording.

EEG data is broken down by task. Eli had a good point of separating the calibration from the task. This means that we would have the following tasks for the fatigue study:

• rest pre
• mi calibration
• mi task
• p300 calibration
• p300 task
• rest post

And the following tasks for the gamification study:

• rest pre (includes eyes open and eyes closed)
• mi gamified calibration
• mi standard calibration
• mi cursor task (do we want to have different task names for when it is preceded by gamified v. standard training?)
• p300 gamified calibration
• p300 standard calibration
• p300 copy spelling task (do we want to have different task names for when it is preceded by gamified v. standard training?)

For each task there are the following files related only to the EEG.

• *_eeg.edf (required)
  • This is the EEG data, and is clearly required
• *_eeg.json (required)
  • Includes some required and a lot of optional metadata about the EEG, we should strive to add all that we have available.
• *_channels.tsv (recommended)
  • Includes information about the channels including their names, type, units, description, status, etc.
  • Again we should include whatever we can
• *_electrodes.tsv (optional)
  • Includes more detailed information about the electrodes, specifically their x,y,z positions. I would be hesitant to add this unless we have a high level of certainty about electrode placement.
• *_coordsystem.json (optional)
  • Includes more detail on the coord system, only required if *_electrodes.tsv is included, so I recommend not including it.
• *_photo.jpg (optional)
  • “Photos of landmarks and/or fiducials, we don’t have these.

For each task there are also the following files related to the events.

• *_events.tsv
• *_events.json

Events include stimulus the user, responses from the user or combinations of the two. For each tasks, the relevant events are listed. Each event must have a specified start time and duration.

• Rest (pre or post)

  • Eyes open cue
  • Relax cue
  • Eyes closed cue

• MI Calibration

  • Left cue
  • Right cue
  • Left selection
  • Right selection

• P300 Calibration

  • Stim (include in .tsv the object index, target index, and maybe a target flag)
  • Feedback

• MI Task

  • Left intended
  • Right intended
  • Left selection
  • Right selection

• P300 Task

  • Stim (include in .tsv the object index, intended target index, and maybe an intended target flag)
  • Feedback (selections made by user)

*- a small note on language, “cue” is used to represent when the user is directly told to select a certain object, “intended” is used to represent the correct selection to complete a task (ie. when the user is asked “does cake grow on trees?” the correct answer is no and so the user should use left hand MI to go left to select “no”, but there is no cue directly telling them to do left hand MI)

So after all that we should have a project directory that looks something like this. This is an example for a single participant in the fatigue study where session 1 is MI, session 2 is P300, and session 3 is video.

README
CHANGES
LICENSE
dataset_description.json
participants.tsv
participants.json
sub-001/
    sub-001_sessions.tsv
    ses-001/
        eeg/
            sub-001_ses-001_task-restpre_eeg.edf
            sub-001_ses-001_task-restpre_eeg.json
            sub-001_ses-001_task-restpre_channels.tsv
            sub-001_ses-001_task-restpre_events.json
            sub-001_ses-001_task-restpre_events.tsv
            sub-001_ses-001_task-micalibration_eeg.edf
            sub-001_ses-001_task-micalibration_eeg.json
            sub-001_ses-001_task-micalibration_channels.tsv
            sub-001_ses-001_task-micalibration_events.json
            sub-001_ses-001_task-micalibration_events.tsv
            sub-001_ses-001_task-mitask_eeg.edf
            sub-001_ses-001_task-mitask_eeg.json
            sub-001_ses-001_task-mitask_channels.tsv
            sub-001_ses-001_task-mitask_events.json
            sub-001_ses-001_task-mitask_events.tsv
            sub-001_ses-001_task-restpost_eeg.edf
            sub-001_ses-001_task-restpost_eeg.json
            sub-001_ses-001_task-restpost_channels.tsv
            sub-001_ses-001_task-restpost_events.json
            sub-001_ses-001_task-restpost_events.tsv
        sourcedata/
            sub-001_ses-001_task-restpre_eeg.xdf
            sub-001_ses-001_task-mi.xdf
            sub-001_ses-001_task-restpost.xdf
    ses-002/
        eeg/
            sub-001_ses-002_task-restpre_eeg.edf
            sub-001_ses-002_task-restpre_eeg.json
            sub-001_ses-002_task-restpre_channels.tsv
            sub-001_ses-002_task-restpre_events.json
            sub-001_ses-002_task-restpre_events.tsv
            sub-001_ses-002_task-p300calibration_eeg.edf
            sub-001_ses-002_task-p300calibration_eeg.json
            sub-001_ses-002_task-p300calibration_channels.tsv
            sub-001_ses-002_task-p300calibration_events.json
            sub-001_ses-002_task-p300calibration_events.tsv
            sub-001_ses-002_task-p300task_eeg.edf
            sub-001_ses-002_task-p300task_eeg.json
            sub-001_ses-002_task-p300task_channels.tsv
            sub-001_ses-002_task-p300task_events.json
            sub-001_ses-002_task-p300task_events.tsv
            sub-001_ses-002_task-restpost_eeg.edf
            sub-001_ses-002_task-restpost_eeg.json
            sub-001_ses-002_task-restpost_channels.tsv
            sub-001_ses-002_task-restpost_events.json
            sub-001_ses-002_task-restpost_events.tsv
    ses-003
        eeg/
            sub-001_ses-003_task-restpre_eeg.edf
            sub-001_ses-003_task-restpre_eeg.json
            sub-001_ses-003_task-restpre_channels.tsv
            sub-001_ses-003_task-restpre_events.json
            sub-001_ses-003_task-restpre_events.tsv
            sub-001_ses-003_task-restpost_eeg.edf
            sub-001_ses-003_task-restpost_eeg.json
            sub-001_ses-003_task-restpost_channels.tsv
            sub-001_ses-003_task-restpost_events.json
            sub-001_ses-003_task-restpost_events.tsv
sub-002/
sub-003/
...