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 ```python 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: ```bash 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: ```bash 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: ```bash 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: ```bash cp source.edf sub-01/emg/sub-01_task-grasp_emg.edf ``` ### Step 4: Create JSON Sidecars #### EEG sidecar (required fields) ```json { "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) ```json { "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 ```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 ```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) ```tsv name x y z Fp1 -0.0294 0.0839 -0.0069 Fp2 0.0303 0.0835 -0.0083 ``` #### coordsystem.json ```json { "EEGCoordinateSystem": "CapTrak", "EEGCoordinateUnits": "m", "EEGCoordinateSystemDescription": "Based on 10-20 system with 3D digitization" } ``` ### Step 6: Validate ```bash # 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](references/eeg-bids.md) - EEG-specific BIDS requirements and common pitfalls - [references/emg-bids.md](references/emg-bids.md) - EMG-specific BIDS requirements (BEP 038) - [references/bids-common-errors.md](references/bids-common-errors.md) - Common validation errors and fixes