| name | bids-conversion |
| description | Use this skill for "convert to BIDS", "BIDS format", "create BIDS dataset", "BIDS sidecar", "participants.tsv", "events.tsv", "EEG BIDS", "EMG BIDS", "MEG BIDS", "fMRI BIDS", "BIDS validator", "channel locations", "electrode positions", "BIDS metadata", or when the user wants to convert neuroscience data to Brain Imaging Data Structure (BIDS) format or validate BIDS compliance. |
| version | 0.1.0 |
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)
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))
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")
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
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
bunx bids-validator /path/to/dataset
bun install -g bids-validator
bids-validator /path/to/dataset
Modality-Specific Notes
Read the detailed references for modality-specific conversion guidance:
