search

bids-standard / pyedf

Python package to read from and write EEG data to European Data Format files.
BSD 3-Clause "New" or "Revised" License
15 stars 9 forks source link

Encoding electrode positions in EDF, EDF+, BDF #7

Open sappelhoff opened 5 years ago

sappelhoff commented 5 years ago

@robertoostenveld do you happen to know whether it is possible to encode digitized electrode positions in the EDF, EDF+, and BDF data formats?

For the BrainVision format, I know that there is an optional "Coordinates" section, which is used for transferring information about a "montage" (should not be used for actual, measured 3D digitized sensor positions)

For the EEGLAB format, it seems to be possible to encode locations as well, but I need to further look into this.

robertoostenveld commented 5 years ago

No, the EDF header (which is also used in EDF+ and BDF) does not have room for it.

For BrainVision I know there can be a coordinates section, but I recall that is not a proper ini-section, but rather a comment block just like for impedances. ... No I am wrong here, the brain vision core PDF has Coordinates as a normal ini-like section (with radius, theta, phi).

In the EEGLAB .set format electrode positions can be present.

Also something to consider: in most EEG lab setups the electrode digitization is not integrated with the recording of the EEG time courses. Different softwares, sometimes different computers, hence the two types of data are usually not merged around acquisition time, but only at time of analysis. For the EEGLAB format (which of course is analysis software, not acquisition software) the .set file typically gets written after merging the two.

sappelhoff commented 5 years ago

Thanks for the info on EDF, EDF+, and BDF!

In the EEGLAB .set format electrode positions can be present.

I will need to check out a .set file to see whether they supply all other necessary information to interprete the electrode positions (coord system, units) ... or whether they do some internal conversion to a common coordsystem+units (like MNE-Python converts all digitization to Elekta/Neuromag space)

edit: it appears that neither coord system nor units are supplied: https://sccn.ucsd.edu/wiki/A05:_Data_Structures#EEG.chanlocs

No I am wrong here, the brain vision core PDF has Coordinates as a normal ini-like section (with radius, theta, phi).

that is correct, however traditionally (i.e., BEFORE the BrainVision Core Data Spec) this section was only used for the interaction between BrainVision Recorder and BrainVision Analyzer. --> this was never really intended as a way to input digitization data into the raw data file ... however, I do see that now this could become the case.

Unfortunately, the part in the "Coordinates" section in the BV Core Spec says nothing about the Coordinate system and the units used. -> this would be needed to make the coordinates section truly useful beyond the traditional interfacing between BV Recorder and BV Analyzer.

From my email exchanges I know that BrainVision Analyzer interprets the "Coordinate Section" in the same ways as a BVEF file (=BrainVision Electrode File) would be interpreted ... which is according to the following coordinate system, specified in "milimeters" (see image):

image

BrainVision also provides the "CapTrak" digitization device, which can save in the BVCT format ... I have made an entry into the Fieldtrip Wiki for that a while ago ... also, I just realized that this typo should be corrected: CapTrack --> CapTrak

However, entering the CapTrak BVCT file into the BrainVision raw data seems like a hack, and would very likely produce issues.

TL;DL: Yes, BrainVision Core Data Format permits a "coordinates" section ... but I think it's underspecified and many software packages will likely misinterpret this section if it is written by anything other than BrainVision Recorder or BrainVision Analyzer.

sappelhoff commented 5 years ago

PS @robertoostenveld if you are interested in the correspondence surrounding BVEF, BVCT and the "Coordinates" section in BrainVision files, I can forward the emails to you.

robertoostenveld commented 5 years ago

just a question: why would you try to squeeze electrode position information in the EEG file, while it can already be stored in the electrodes.tsv (and with the coordsystem.json to explain)?

PS thanks for CCing me on the emails

sappelhoff commented 5 years ago

just a question: why would you try to squeeze electrode position information in the EEG file, while it can already be stored in the electrodes.tsv (and with the coordsystem.json to explain)?

This whole cascade of questions and problems originated from a simple problem:

--> The issues are:

  1. IF there is position information contained in the RAW files, ... I often don't know the exact format, so writing to BIDS is impossible (see e.g., lack of information in VHDR files, also the email I ccd you in)
  2. IF there is position information contained in the RAW files, ... some (all? many?) analysis softwares transform this information to their native space of choice (e.g. Elekta/Neuromag in MNE-Python) this is problematic for several reasons:
    1. For a given analysis software, I often don't know what this native space of choice is, and whether a transformation happened at all (that can be overcome by reading the sourcecode, but it's veeeery tedious)
    2. If a transformation happened and I am able to write that data to BIDS ... then electrodes.tsv and coordsystem.json will not correspond to the state of the data in the actual RAW file
  3. IF there is NO position data in the RAW files, it could be that ...
    1. the raw file was read and THEN some position data was added ... to only THEN pass this raw data to my BIDS writing function --> in that situation, I find myself as in step 2, but without the issue that data might not correspond ... so this might be cool/acceptable
  4. Finally, the only "issue - free" situation is, where no position data is in the RAW files, and no such data is added to the RAW files before passing to my BIDS writer
    1. instead, users should supply their native position file (e.g., BVCT, or whatever) and I will read that and write it and be happy

I think this describes the situation exhausitvely, and it might explain to you why:

robertoostenveld commented 5 years ago

interesting, and non-trivial.

Let me reply how we do it - more or less - in FieldTrip (but not always 100% perfect)

  1. we would call ft_read_sens(filename), although you would still have to know which filename has the electrode measured positions. However, that never seems to be the problem.
  2. i) we add the coordsys field to each FT data structure that contains geometrical data, and ii) if the researcher decides to write transformed data, there is probably a good reason for it. If he wants to write untransformed data, also fine with me. As long as the resulting BIDS represents the coordinate system properly.
  3. this is where FT uses ft_electroderealign, which adds the coordsys field to the elec structure. The elec structure can then be added to the data.
  4. if there is no real position data measured for the individual, then that should not be "invented" by the software. E.g. I don't like how EEGLAB does it: it adds template positions to the data that cannot be distinguished from actual positions. FieldTrip does not add positions to the data, but has template positions available when plotting. But those templates are not added to the data, pretending that those are the individuals positions.

The lack of position information being measured needs to be properly represented in the BIDS structure. The recipient of the data can always use the template positions provided in the software that he/she uses; the data does not need to contain fake positions (and if so, it should beindicated that the electrode positions have been imputed). You would also not add a template/fake anatomical MRI to an EEG dataset, or template/fake triggers if you don't know what task the subject was doing. BIDS raw is in my opinion about what we measured (factual), not about what we would have liked to measure (desired).

The challenge converting data with FIeldTrip data2bids is similar. I have some examples, two are EEG specific, but neither have electrode positions. It would actually interesting to also make an example that does include positions, also to test the completeness of the implementation. That would use this option. Do you know of a proper raw EEG dataset plus electrodes that is already shared? We do not have one in the tutorials.

sappelhoff commented 5 years ago

Thanks!

I completely agree with you that template positions should not be included in BIDS and have argued this way before.

If you want to read about opposing arguments, you can check out this thread (no need to check the code, the arguments are all in the comments): https://github.com/mne-tools/mne-bids/pull/244#discussion_r313958721

Do you know of a proper raw EEG dataset plus electrodes that is already shared? We do not have one in the tutorials.

Unfortunately I don't. I am currently collecting data, but it might well take another 6 months until I can share it.

robertoostenveld commented 5 years ago

Thanks for pointing out the MNE-python discussion.

I could use eeg-audodd for that. It is actually a Neuromag recording, but we reformatted it into BrainVision for an EEG-only workshop. I could also reformat the electrodes (now in a mat file) so that those are formatted (e.g. as BESA .sfp) as if they are recorded with more common digitizer software.

robertoostenveld commented 5 years ago

In case you are interested for testing purposes, you can download eeg-audodd.zip. It includes real electrodes in BESA .sfp format and real DICOM files. I think this is as close as it gets to a complete measured dataset in the original raw format prior to BIDS.

sappelhoff commented 5 years ago

Thanks, that looks like it would make a good candidate for an EEG BIDS dataset with actual coords.

Just out of curiosity: Which digitizing apparatus was used to save in BESA .sfp format?

robertoostenveld commented 5 years ago

All data was originally recorded with the Neuromag Triux MEG system (which also controls the Polhemus) and stored in a .fif file. I then used FieldTrip to selectively get the EEG time courses and electrode positions and wrote those to file formats corresponding to raw data.

The .sfp was written with ft_write_sens.m in the latest master version, it is not yet in the release. I just implemented it yesterday for this purpose ;-)