BIDS Conversion

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)

Step 3: Convert Data Files

EEG (EEGLAB .set)

EEGLAB .set files are BIDS-compatible as-is. Copy and rename:

cp source.set sub-01/eeg/sub-01_task-rest_eeg.set
cp source.fdt sub-01/eeg/sub-01_task-rest_eeg.fdt  # if separate .fdt file

EEG (BrainVision .vhdr)

BrainVision files come in triplets (.vhdr, .vmrk, .eeg). All three must be renamed consistently:

cp source.vhdr sub-01/eeg/sub-01_task-rest_eeg.vhdr
cp source.vmrk sub-01/eeg/sub-01_task-rest_eeg.vmrk
cp source.eeg  sub-01/eeg/sub-01_task-rest_eeg.eeg

Update internal references in .vhdr and .vmrk to point to renamed files.

EEG (EDF/BDF)

Copy and rename:

cp source.edf sub-01/eeg/sub-01_task-rest_eeg.edf

EMG

EMG follows the same pattern but uses the emg directory and suffix:

cp source.edf sub-01/emg/sub-01_task-grasp_emg.edf

Step 4: Create JSON Sidecars

EEG sidecar (required fields)

{
  "TaskName": "rest",
  "TaskDescription": "Eyes-open resting state recording",
  "InstitutionName": "University Name",
  "InstitutionAddress": "Address",
  "Manufacturer": "BioSemi",
  "ManufacturersModelName": "ActiveTwo",
  "SamplingFrequency": 512,
  "EEGChannelCount": 64,
  "EOGChannelCount": 2,
  "EMGChannelCount": 0,
  "ECGChannelCount": 0,
  "MiscChannelCount": 0,
  "TriggerChannelCount": 1,
  "PowerLineFrequency": 60,
  "EEGPlacementScheme": "10-20",
  "EEGReference": "CMS/DRL",
  "EEGGround": "n/a",
  "SoftwareFilters": "n/a",
  "HardwareFilters": {"Highpass": {"HalfAmplitudeCutoffHz": 0.01}},
  "RecordingType": "continuous",
  "RecordingDuration": 300
}

EMG sidecar (required fields)

{
  "TaskName": "grasp",
  "TaskDescription": "Grasping task with force measurement",
  "SamplingFrequency": 2000,
  "EMGChannelCount": 8,
  "PowerLineFrequency": 60,
  "EMGPlacementScheme": "bipolar",
  "EMGReference": "differential",
  "Manufacturer": "Delsys",
  "ManufacturersModelName": "Trigno",
  "RecordingType": "continuous"
}

Step 5: Create TSV Files

channels.tsv

name	type	units	sampling_frequency	status	description
Fp1	EEG	uV	512	good	Frontal pole 1
Fp2	EEG	uV	512	good	Frontal pole 2
HEOG	EOG	uV	512	good	Horizontal EOG
VEOG	EOG	uV	512	good	Vertical EOG
EMG1	EMG	uV	2000	good	First dorsal interosseous

events.tsv

onset	duration	trial_type	value	sample
0.0	0.0	stimulus	1	0
1.5	0.5	response	2	768
3.0	0.0	stimulus	1	1536

electrodes.tsv (for EEG)

name	x	y	z
Fp1	-0.0294	0.0839	-0.0069
Fp2	0.0303	0.0835	-0.0083

coordsystem.json

{
  "EEGCoordinateSystem": "CapTrak",
  "EEGCoordinateUnits": "m",
  "EEGCoordinateSystemDescription": "Based on 10-20 system with 3D digitization"
}

Step 6: Validate

# Using the official BIDS validator (Node.js CLI)
bunx bids-validator /path/to/dataset

# Or install globally
bun install -g bids-validator
bids-validator /path/to/dataset

Modality-Specific Notes

Read the detailed references for modality-specific conversion guidance:

• references/eeg-bids.md - EEG-specific BIDS requirements and common pitfalls
• references/emg-bids.md - EMG-specific BIDS requirements (BEP 038)
• references/bids-common-errors.md - Common validation errors and fixes