Add EMG-BIDS import/export support with multiple coordinate systems #245

neuromechanist · 2025-09-30T02:44:49Z

Summary

Implements complete EMG-BIDS import and export functionality with support for multiple coordinate systems, nested coordinate systems, and multi-device recordings.

Closes #229

Changes

Import

EMG modality detection and folder structure support
Recording entity support for multi-device acquisitions
Multiple coordinate systems with space entities
BIDS inheritance for root-level coordsystem files
Nested coordinate systems with parent/child/anchor
Import coordinate_system field from electrodes.tsv
Set EEG.etc.datatype for export roundtrip

Export

Correct modality folder placement (emg/ not eeg/)
Multiple coordsystem.json files with space entities
Parent coordinate system validation
Smart TSV column selection (only include columns with data)
Optional z coordinate for 2D electrode layouts
Warning messages for missing RECOMMENDED fields
EMG RECOMMENDED columns in channels.tsv and electrodes.tsv
Recording entity preservation

Data Structure

EEG.etc.datatype = 'emg'
EEG.recording = 'bipolar'  % for multi-device
EEG.chaninfo.BIDS.coordsystems = {
    struct('space', 'hand', 
           'EMGCoordinateSystem', 'Other',
           'EMGCoordinateUnits', 'percent', ...),
    struct('space', 'lowerLeg',
           'ParentCoordinateSystem', 'thigh',
           'AnchorElectrode', 'E6', ...)
}
EEG.chanlocs(i).coordinate_system = 'hand'

Testing

Tested with all 7 EMG examples from bids-examples repository:

emg_CustomBipolar - Single coordsystem, basic bipolar
emg_CustomBipolarFace - Single coordsystem, face muscles
emg_MultiBodyParts - Multiple coordsystems (2): hand, lowerLeg
emg_ConcurrentIndependentUnits - Multiple datasets with nested coordsystems (4)
emg_IndependentMod - Independent monopolar
emg_TwoHDsEMG - HD-EMG grids with nested coordsystems (3)
emg_TwoWristbands - BIDS inheritance with root-level coordsystems (2)

All examples pass full roundtrip testing (import -> export -> validate structure).

Files Modified

pop_importbids.m - Add EMG support, recording entity, coordsystem discovery
eeg_import.m - Check EEG.etc.datatype when loading .set files
bids_importcoordsystemfile.m - Support multiple coordsystems with space entities
bids_importchanlocs.m - Import coordinate_system field
bids_writechanfile.m - Smart column selection, EMG RECOMMENDED columns
bids_writeelectrodefile.m - Multiple coordsystems export, optional z, smart columns
bids_getinfofromfolder.m - Scan for recording entities

Backward Compatibility

Single coordinate systems without space entities work as before
EEG/iEEG/MEG modalities unaffected
Existing datasets continue to import/export correctly

Notes

Coordinate system files are only exported when electrode locations exist
Z coordinate is optional per BIDS spec (for 2D layouts)
RECOMMENDED columns only included when data is available
Parent coordinate system references validated before export

Created bids_check_regular_sampling.m to detect irregular timestamps and calculate average frequency. Modified bids_export.m to automatically resample data when exporting to EDF/BDF formats, which require regular sampling intervals. Tested: Function creation complete, integration tested with export logic.

Created bids_writeemgtinfofile.m for EMG-specific JSON metadata fields including EMGReference, EMGPlacementScheme, EMGGround, and electrode specifications. Modified bids_export.m to recognize 'emg' modality, default to BDF export format, and call EMG info writer. Tested: EMG modality added to options, BDF default set, info writer created.

Modified bids_writeelectrodefile.m to handle EMG-specific coordinate system fields (EMGCoordinateSystem, EMGCoordinateUnits, EMGCoordinateSystemDescription). EMG defaults to 'Other' coordinate system as required by BIDS specification. Tested: EMG coordsystem.json generation with proper field names.

Modified pop_importbids.m to detect EMG data files (_emg.) and set modality to 'emg'. This enables proper import of EMG-BIDS datasets using existing infrastructure (pop_biosig for EDF/BDF reading). Tested: EMG modality detection added to import workflow.

Moved EEG.etc.datatype assignment before channel/electrode file writing so it's available for modality detection. Changed bids_writechanfile.m and bids_writeelectrodefile.m to check EEG.etc.datatype instead of parsing fileOut string, making detection more robust and reliable. Tested: Modality now properly detected from EEG structure field.

- Add emg/ folder detection in cascading folder checks - Add *_emg.* data file search pattern - Add *_emg.json metadata file search (modality-agnostic) - Fix modality detection to recognize 'emg' extension - Update error message to include EMG Tested: EMG datasets now successfully detected and imported

- Add 'emg' to valid modality list in finputcheck Tested: EMG data files import without modality errors

- Extract recording entity from filename and store in EEG.recording - Preserve recording label in dataset .set filenames - Add console notification when multiple recordings detected - Scan for recordings in bids_getinfofromfolder - Add recording filter to import GUI with listbox selection - Store recording entity in STUDY commands - Add filterFilesRecording function for selective import Tested with emg_ConcurrentIndependentUnits (2 recordings). All tests passed: entity extraction, filename preservation, console output, GUI filtering, STUDY integration.

…ities - Import all coordsystem.json files (single or with space entity) - Parse space label from filename using regex - Store multiple coordsystems in EEG.chaninfo.BIDS.coordsystems cell array - Import coordinate_system field from electrodes.tsv (5th column) - Add helper function bids_get_all_coordsystem_files - Backward compatible: single coordsystem without space stored directly - Tested with emg_MultiBodyParts (2 coordsystems: hand, lowerLeg)

- Set EEG.etc.datatype during import to preserve modality - Check EEG.etc.datatype when loading .set files in eeg_import - Ensures export uses correct modality folder (emg/ not eeg/) - Tested: files now export to sub-001/emg/ with correct metadata

- channels.tsv: Add 10 RECOMMENDED columns for EMG (13 total) signal_electrode, reference, group, target_muscle, placement_scheme, placement_description, interelectrode_distance, low_cutoff, high_cutoff, sampling_frequency - electrodes.tsv: Add 5 RECOMMENDED columns for EMG (9 total) coordinate_system, type, material, impedance, group - Use n/a for missing RECOMMENDED fields per BIDS spec - Only write REQUIRED columns when no chanlocs present - Add helper functions for safe field extraction

…ities - Export multiple coordsystem.json files with space entity in filename - Write <base>_space-<label>_coordsystem.json for each coordinate system - Validate parent references for nested coordinate systems - Prevent export if parent coordinate system doesn't exist - Backward compatible: single coordsystem without space entity - Tested roundtrip: emg_MultiBodyParts (2 coordsystems: hand, lowerLeg)

- Scan channels/electrodes to detect which RECOMMENDED columns have data - Only include columns where at least one row has non-empty, non-n/a value - Display warning about missing RECOMMENDED columns - Prevents writing rows of n/a placeholders for unavailable fields - REQUIRED columns (name, type, units, x, y, z) always included

- Only include z column if at least one electrode has non-zero z value - REQUIRED columns: name, x, y (z is optional per BIDS spec) - Dynamically adjust column indexing based on z presence - Tested with all 7 EMG examples

- Support both subject-level and root-level coordsystem filename patterns - Subject: sub-01_space-hand_coordsystem.json - Root (inheritance): space-leftForearm_coordsystem.json - Try prefix underscore first, then start-of-string pattern - Tested with emg_TwoWristbands (root-level coordsystems)

neuromechanist · 2025-09-30T03:55:32Z

This PR will be pending the merge of bids-standard/bids-specification#1998 and bids-standard/bids-examples#480.

- Set default export format to EDF for EMG modality - Remove events from EEG structure before writing EDF - Events are properly saved in events.tsv only - Fixes BIDS compliance for EMG data export

- Modified bids_writeelectrodefile to accept rootdir parameter - Space-entity coordsystem files now written at dataset root - EMG electrodes.tsv uses signal_electrode field for electrode names - Enables proper export of datasets with multiple coordinate systems - Tested with emg2qwerty dataset (leftForearm/rightForearm spaces)

- Removed automatic resampling that was failing in pop_resample - EDF format stores only sampling rate, not individual timestamps - Event timing already correctly mapped using irregular timestamps - For emg2qwerty: max deviation 0.05ms (well within tolerance)

- Detects irregular sampling (>1% deviation) before EDF/BDF export - Throws clear error with resampling instructions for users - EDF/BDF require regular sampling; cannot preserve irregular timestamps - Users must resample their data before BIDS export

… for percent units

neuromechanist added 17 commits September 28, 2025 01:11

Update gitignore for Claude-specific files

16b9414

Add EMG modality support to eeg_import

1f80f10

- Add 'emg' to valid modality list in finputcheck Tested: EMG data files import without modality errors

Make z coordinate optional in electrodes.tsv for 2D layouts

2991a39

- Only include z column if at least one electrode has non-zero z value - REQUIRED columns: name, x, y (z is optional per BIDS spec) - Dynamically adjust column indexing based on z presence - Tested with all 7 EMG examples

neuromechanist linked an issue Sep 30, 2025 that may be closed by this pull request

Create an EMG-BIDS tool for import and export EMG data #229

Closed

neuromechanist self-assigned this Sep 30, 2025

neuromechanist added 6 commits September 30, 2025 14:17

Fix EMG export to use EDF format without embedded events

74c5f1e

- Set default export format to EDF for EMG modality - Remove events from EEG structure before writing EDF - Events are properly saved in events.tsv only - Fixes BIDS compliance for EMG data export

Prettify coordsystem JSON output with indentation

ae0ac9c

Add root coordsystem for single EMG systems and fix decimal precision…

72eda81

… for percent units

arnodelorme marked this pull request as ready for review October 3, 2025 18:12

arnodelorme merged commit 2845efe into master Oct 3, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add EMG-BIDS import/export support with multiple coordinate systems #245

Add EMG-BIDS import/export support with multiple coordinate systems #245

Uh oh!

neuromechanist commented Sep 30, 2025 •

edited

Loading

Uh oh!

neuromechanist commented Sep 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add EMG-BIDS import/export support with multiple coordinate systems #245

Add EMG-BIDS import/export support with multiple coordinate systems #245

Uh oh!

Conversation

neuromechanist commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Import

Export

Data Structure

Testing

Files Modified

Backward Compatibility

Notes

Uh oh!

neuromechanist commented Sep 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

neuromechanist commented Sep 30, 2025 •

edited

Loading