bids-conversion

BIDS Conversion

Convert neuroscience datasets to Brain Imaging Data Structure (BIDS) format. Supports EEG, EMG, MEG, fMRI, and behavioral data with proper file naming, JSON sidecars, and metadata.

When to Use

• Converting raw data files to BIDS format
• Creating or fixing BIDS metadata (JSON sidecars, TSV files)
• Validating BIDS compliance
• Setting up a new BIDS dataset from scratch
• Converting between data formats (e.g., .set to .edf, .vhdr to .bdf)

BIDS Directory Structure

dataset/
  dataset_description.json
  participants.tsv
  participants.json
  README
  CHANGES
  sub-01/
    sub-01_scans.tsv
    eeg/
      sub-01_task-rest_eeg.set
      sub-01_task-rest_eeg.json
      sub-01_task-rest_channels.tsv
      sub-01_task-rest_electrodes.tsv
      sub-01_task-rest_coordsystem.json
      sub-01_task-rest_events.tsv
    emg/
      sub-01_task-grasp_emg.edf
      sub-01_task-grasp_emg.json
      sub-01_task-grasp_channels.tsv
      sub-01_task-grasp_events.tsv
    anat/
      sub-01_T1w.nii.gz
      sub-01_T1w.json
  derivatives/
    pipeline-name/
      sub-01/

File Naming Convention

sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_<suffix>.<extension>

• sub: subject identifier (required, alphanumeric, no special chars)
• ses: session (optional, for longitudinal studies)
• task: task name (required for functional data)
• acq: acquisition parameters (optional)
• run: run index (optional, for repeated acquisitions)
• suffix: data type (eeg, emg, meg, bold, T1w, events, channels, electrodes)

Conversion Workflow

Step 1: Inventory Source Data

Identify:

• Data format (BrainVision .vhdr, EEGLAB .set, EDF .edf, BDF .bdf, NIfTI .nii.gz)
• Number of subjects and sessions
• Task names and conditions
• Channel types (EEG, EMG, EOG, ECG, misc)
• Events/markers in the data
• Coordinate system for electrode positions

Step 2: Create Dataset Scaffold

import json
from pathlib import Path

def create_bids_scaffold(root: str, subjects: list[str], tasks: list[str], modality: str = "eeg"):
    root = Path(root)
    root.mkdir(exist_ok=True)

    # dataset_description.json
    desc = {
        "Name": "Dataset Name",
        "BIDSVersion": "1.9.0",
        "DatasetType": "raw",
        "License": "CC0",
        "Authors": ["Last, First"],
        "DatasetDOI": "",
        "GeneratedBy": [{"Name": "Manual conversion"}]
    }
    (root / "dataset_description.json").write_text(json.dumps(desc, indent=2))

    # participants.tsv
    with open(root / "participants.tsv", "w") as f:
        f.write("participant_id\tage\tsex\thand\n")
        for sub in subjects:
            f.write(f"sub-{sub}\tn/a\tn/a\tn/a\n")

    # Create subject directories
    for sub in subjects:
        for task in tasks:
            (root / f"sub-{sub}" / modality).mkdir(parents=True, exist_ok=True)