Difference between revisions of "AnyWave:ADES"
(→The marker file (.mrk)) |
(→The marker file (.mrk)) |
||
(34 intermediate revisions by 2 users not shown) | |||
Line 3: | Line 3: | ||
ADES format is composed of at least two files but a third file can be used for markers.<br/> | ADES format is composed of at least two files but a third file can be used for markers.<br/> | ||
− | The most important file is the header file for which extension is '''.ades'''<br/> | + | The most important file is the header file for which the extension is '''.ades'''<br/> |
==The header file (.ades)== | ==The header file (.ades)== | ||
Line 11: | Line 11: | ||
samplingRate = 1000 | samplingRate = 1000 | ||
numberOfSamples = 4000 | numberOfSamples = 4000 | ||
− | A1 = | + | |
− | A2 = | + | A1 = MEG |
− | A3 = | + | A2 = MEG |
+ | A3 = MEG | ||
+ | ... | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | Line 1 begins with '''#''' which is the starting character for comments. However | + | Line 1 begins with '''#''' which is the starting character for comments. However, this first line is mandatory and defines the header file as ADES header.<br/> |
The next line defines the sampling rate of the data. This parameter is mandatory and must be expressed in Hertz.<br/> | The next line defines the sampling rate of the data. This parameter is mandatory and must be expressed in Hertz.<br/> | ||
− | + | The third line defines the total number of samples per channel in the data file.<br/> | |
The following lines describe the channels present in the data file. In our example, there are 3 channels, A1, A2, A3.<br/> | The following lines describe the channels present in the data file. In our example, there are 3 channels, A1, A2, A3.<br/> | ||
The channels are defined to be EEG channels but could be defined as SEEG, MEG, EMG, ECG, or even Trigger.<br/> | The channels are defined to be EEG channels but could be defined as SEEG, MEG, EMG, ECG, or even Trigger.<br/> | ||
− | It is also possible to omit the channel's type | + | It is also possible to omit the channel's type; '''AnyWave''' will consider channels as EEG by default in that case.<br/> |
− | + | ==Optional keywords== | |
+ | ===Specify units=== | ||
+ | Sometimes, data could be exported in the wrong unit.<br /> | ||
+ | For example, some software export EEG/SEEG data in Volt but AnyWave expects micro Volt (µV).<br /> | ||
+ | <br /> | ||
+ | Use the following keyword to specify the data unit for a channel type:<br /> | ||
+ | <syntaxhighlight lang="text" line="GESHI_FANCY_LINE_NUMBERS"> | ||
+ | # SEEG and EEG channels contains V measures. | ||
+ | Unit = SEEG,V | ||
+ | Unit = EEG,V | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | ===Specify a 2D or 3D layout=== | ||
+ | You can specify a layout name that AnyWave will use to compute the 2D and/or 3D mappings of activities.<br /> | ||
+ | |||
+ | <syntaxhighlight lang="text" line="GESHI_FANCY_LINE_NUMBERS"> | ||
+ | # specifying layout for 2D or 3D mapping of activities. | ||
+ | # here we define a MEG 4DNI layout to visualize MEG mappings. | ||
+ | layouts = 4DNI248 | ||
+ | </syntaxhighlight> | ||
==The data file (.dat)== | ==The data file (.dat)== | ||
Data are stored in a binary file which name is exactly the same than the header file except the extension: '''.dat'''<br/> | Data are stored in a binary file which name is exactly the same than the header file except the extension: '''.dat'''<br/> | ||
− | + | The samples are stored as float, 4 bytes per sample, little endian. The channels are multiplexed.<br/> | |
==The marker file (.mrk)== | ==The marker file (.mrk)== | ||
− | It is possible to have a third optional file describing markers in the data. This file is an AnyWave marker file. The name must be the same than the header file but with extension .mrk<br> | + | It is possible to have a third optional file describing markers in the data. This file is an AnyWave marker file. The name must be the same than the header file but with extension '''.mrk'''<br> |
This is a text file with a simple format: | This is a text file with a simple format: | ||
<syntaxhighlight lang="text" line="GESHI_FANCY_LINE_NUMBERS"> | <syntaxhighlight lang="text" line="GESHI_FANCY_LINE_NUMBERS"> | ||
// AnyWave Marker File | // AnyWave Marker File | ||
− | Start -1 0.957031 | + | Start -1 0.957031 0 |
Section -1 0.960938 2 | Section -1 0.960938 2 | ||
− | Marker1 -1 150.957 | + | Marker1 -1 150.957 0 |
− | CRISE -1 213.023 | + | CRISE -1 213.023 0 |
− | Marker2 -1 300.957 | + | Marker2 -1 300.957 0 |
− | Marker3 -1 450.957 | + | Marker3 -1 450.957 0 |
− | Marker4 -1 578.707 | + | Marker4 -1 578.707 0 |
− | + | Special -1 600.957 0 A1 | |
− | END -1 621.582 | + | Colored -1 610.0 0 #FF0000 A1,A2 |
+ | END -1 621.582 0 | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | + | The first line must be ''// AnyWave Marker File''. '''AnyWave''' will then recognize the file as a marker file.<br/> | |
− | The first line must be ''// AnyWave Marker File''. AnyWave will then recognize the file as a marker file.<br/> | + | |
Next come the markers, one marker by line.<br/> | Next come the markers, one marker by line.<br/> | ||
Attributes must be separated by tabulations.<br/> | Attributes must be separated by tabulations.<br/> | ||
− | The first attribute is | + | The first attribute is the marker's label.<br/> |
The second attribute is the integer value associated with the marker. -1 means that there is no value.<br/> | The second attribute is the integer value associated with the marker. -1 means that there is no value.<br/> | ||
− | The third | + | The third attribute is the position in seconds, from the begining of the data file.<br/> |
− | + | The fourth parameter is the duration in seconds, 0 means no duration.<br/> | |
− | + | '''Optional columns''':<br/> | |
− | <br/> | + | ''Color parameter'':<br/> |
− | In | + | The fifth column may represent the color of the marker OR a list of targeted channels.<br/> |
− | + | If the parameter starts with an #, then it's a color enconding:<br/> | |
+ | In the example above, we can see Colored marker at position 610s which has a fifth parameter #FF0000. <br/> | ||
+ | The #FF0000 is the hexadecimal representation of RVB color. In this case the red color.<br/> | ||
+ | ''Targeted channels'':<br/> | ||
+ | The fifth column may contains coma separated list of channels as targets.<br/> | ||
+ | If only one channel is target, then the column will contain only the label of the channel.<br/> | ||
+ | In the example above, look a Special marker which targets the channel A1, or at marker Colored targeting the channels A1 and A2. | ||
+ | ''Color AND Targets'':<br/> | ||
+ | The color parameter may be followed by a list of targeted channels, like in our case (A2 channel).<br/> | ||
+ | |||
+ | == Building your own ADES file== | ||
+ | It is quite simple to build a ADES file from MATLAB for example. Suppose you have data stored in a MATLAB matrix that you would like to export to ADES format:<br/> | ||
+ | |||
+ | <syntaxhighlight lang="matlab"> | ||
+ | function mat2ades(data,fileName,FS,labels,labelType) | ||
+ | |||
+ | % write in the current folder ADES and DAT files from matrix in MATLAB workspace | ||
+ | % data = matrix of data (nbchannel * time points) - the data have to be in | ||
+ | % microVolt | ||
+ | % fileName = string of the output files without extension ; the ades and | ||
+ | % dat files will have the same name | ||
+ | % FS = sampling rate | ||
+ | % labels = cell array with channel labels | ||
+ | % labelType : 'EEG' or 'MEG' | ||
+ | % Sophie Chen - January 2014 | ||
+ | |||
+ | %% generate the ADES file | ||
+ | adesFile = [fileName '.ades']; | ||
+ | |||
+ | fid = fopen(adesFile,'wt'); | ||
+ | |||
+ | fprintf(fid,'%s\r\n','#ADES header file '); | ||
+ | fprintf(fid,'%s','samplingRate = '); | ||
+ | fprintf(fid,'%d\r\n',FS); | ||
+ | fprintf(fid,'%s','numberOfSamples = '); | ||
+ | fprintf(fid,'%d\r\n',size(data,2)); | ||
+ | |||
+ | for lab = 1:length(labels) | ||
+ | fprintf(fid,'%s\r\n',[labels{lab} ' = ' labelType]); | ||
+ | end | ||
+ | |||
+ | fclose(fid); | ||
+ | |||
+ | %% generate the DAT file | ||
+ | |||
+ | datFile = [fileName '.dat']; | ||
+ | |||
+ | fad = fopen(datFile,'wb'); | ||
+ | fwrite(fad, data, 'float32'); | ||
+ | fclose(fad); | ||
+ | end | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | Note that '\r' may be necessary even on non-Windows systems. | ||
+ | |||
+ | An MNE-Python Raw object may be written to ADES files with the following function: | ||
+ | |||
+ | <syntaxhighlight lang="python"> | ||
+ | def write_ades(basename, raw, overwrite=False): | ||
+ | """ | ||
+ | Write MNE Raw object to ADES files. | ||
+ | |||
+ | Parameters | ||
+ | ---------- | ||
+ | basename: str | ||
+ | Base name for ADES files, creating basename.{ades,dat} | ||
+ | raw: mne.Raw instance | ||
+ | Continuous raw data to write to file. | ||
+ | overwrite: bool | ||
+ | If True, an existing file may be overwritten | ||
+ | |||
+ | """ | ||
+ | |||
+ | # write signal data to file | ||
+ | raw._data.T.astype('f').tofile(basename + '.dat') | ||
+ | |||
+ | # (over)write header | ||
+ | with open(basename + '.ades', 'w') as fd: | ||
+ | fd.write('#ADES header file\r\n') | ||
+ | fd.write('samplingRate = %d\r\n' % (raw.info['sfreq'], )) | ||
+ | fd.write('numberOfSamples = %d\r\n' % (raw._data.shape[1], )) | ||
+ | for name in raw.ch_names: | ||
+ | fd.write('%s\r\n' % (name, )) | ||
+ | |||
+ | </syntaxhighlight> |
Latest revision as of 10:58, 14 October 2019
ADES stands for AnyWave DEScriptive format.
ADES format is composed of at least two files but a third file can be used for markers.
The most important file is the header file for which the extension is .ades
Contents
The header file (.ades)
This is a text file using a very simple syntax. Let's have a look:
#ADES header file
samplingRate = 1000
numberOfSamples = 4000
A1 = MEG
A2 = MEG
A3 = MEG
...
Line 1 begins with # which is the starting character for comments. However, this first line is mandatory and defines the header file as ADES header.
The next line defines the sampling rate of the data. This parameter is mandatory and must be expressed in Hertz.
The third line defines the total number of samples per channel in the data file.
The following lines describe the channels present in the data file. In our example, there are 3 channels, A1, A2, A3.
The channels are defined to be EEG channels but could be defined as SEEG, MEG, EMG, ECG, or even Trigger.
It is also possible to omit the channel's type; AnyWave will consider channels as EEG by default in that case.
Optional keywords
Specify units
Sometimes, data could be exported in the wrong unit.
For example, some software export EEG/SEEG data in Volt but AnyWave expects micro Volt (µV).
Use the following keyword to specify the data unit for a channel type:
# SEEG and EEG channels contains V measures.
Unit = SEEG,V
Unit = EEG,V
Specify a 2D or 3D layout
You can specify a layout name that AnyWave will use to compute the 2D and/or 3D mappings of activities.
# specifying layout for 2D or 3D mapping of activities.
# here we define a MEG 4DNI layout to visualize MEG mappings.
layouts = 4DNI248
The data file (.dat)
Data are stored in a binary file which name is exactly the same than the header file except the extension: .dat
The samples are stored as float, 4 bytes per sample, little endian. The channels are multiplexed.
The marker file (.mrk)
It is possible to have a third optional file describing markers in the data. This file is an AnyWave marker file. The name must be the same than the header file but with extension .mrk
This is a text file with a simple format:
// AnyWave Marker File
Start -1 0.957031 0
Section -1 0.960938 2
Marker1 -1 150.957 0
CRISE -1 213.023 0
Marker2 -1 300.957 0
Marker3 -1 450.957 0
Marker4 -1 578.707 0
Special -1 600.957 0 A1
Colored -1 610.0 0 #FF0000 A1,A2
END -1 621.582 0
The first line must be // AnyWave Marker File. AnyWave will then recognize the file as a marker file.
Next come the markers, one marker by line.
Attributes must be separated by tabulations.
The first attribute is the marker's label.
The second attribute is the integer value associated with the marker. -1 means that there is no value.
The third attribute is the position in seconds, from the begining of the data file.
The fourth parameter is the duration in seconds, 0 means no duration.
Optional columns:
Color parameter:
The fifth column may represent the color of the marker OR a list of targeted channels.
If the parameter starts with an #, then it's a color enconding:
In the example above, we can see Colored marker at position 610s which has a fifth parameter #FF0000.
The #FF0000 is the hexadecimal representation of RVB color. In this case the red color.
Targeted channels:
The fifth column may contains coma separated list of channels as targets.
If only one channel is target, then the column will contain only the label of the channel.
In the example above, look a Special marker which targets the channel A1, or at marker Colored targeting the channels A1 and A2.
Color AND Targets:
The color parameter may be followed by a list of targeted channels, like in our case (A2 channel).
Building your own ADES file
It is quite simple to build a ADES file from MATLAB for example. Suppose you have data stored in a MATLAB matrix that you would like to export to ADES format:
function mat2ades(data,fileName,FS,labels,labelType) % write in the current folder ADES and DAT files from matrix in MATLAB workspace % data = matrix of data (nbchannel * time points) - the data have to be in % microVolt % fileName = string of the output files without extension ; the ades and % dat files will have the same name % FS = sampling rate % labels = cell array with channel labels % labelType : 'EEG' or 'MEG' % Sophie Chen - January 2014 %% generate the ADES file adesFile = [fileName '.ades']; fid = fopen(adesFile,'wt'); fprintf(fid,'%s\r\n','#ADES header file '); fprintf(fid,'%s','samplingRate = '); fprintf(fid,'%d\r\n',FS); fprintf(fid,'%s','numberOfSamples = '); fprintf(fid,'%d\r\n',size(data,2)); for lab = 1:length(labels) fprintf(fid,'%s\r\n',[labels{lab} ' = ' labelType]); end fclose(fid); %% generate the DAT file datFile = [fileName '.dat']; fad = fopen(datFile,'wb'); fwrite(fad, data, 'float32'); fclose(fad); end
Note that '\r' may be necessary even on non-Windows systems.
An MNE-Python Raw object may be written to ADES files with the following function:
def write_ades(basename, raw, overwrite=False): """ Write MNE Raw object to ADES files. Parameters ---------- basename: str Base name for ADES files, creating basename.{ades,dat} raw: mne.Raw instance Continuous raw data to write to file. overwrite: bool If True, an existing file may be overwritten """ # write signal data to file raw._data.T.astype('f').tofile(basename + '.dat') # (over)write header with open(basename + '.ades', 'w') as fd: fd.write('#ADES header file\r\n') fd.write('samplingRate = %d\r\n' % (raw.info['sfreq'], )) fd.write('numberOfSamples = %d\r\n' % (raw._data.shape[1], )) for name in raw.ch_names: fd.write('%s\r\n' % (name, ))