AnyWave:ADES

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 extension is .ades

The header file (.ades)

This is a text file using a very simple syntax. Let's have a look:

1. #ADES header file

2. samplingRate = 1000

3. numberOfSamples = 4000

4. # specifying layout for 2D or 3D mapping of activities. This keyword is optional.

5. layouts = 4DNI248

7. A1 = MEG

8. A2 = MEG

9. A3 = MEG

10. ...

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

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:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, arm, asm, asp, asymptote, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcl, dcpu16, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, freeswitch, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, haxe, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, ldif, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, nagios, netrexx, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, octave, oobas, oorexx, oracle11, oracle8, oxygene, oz, parasail, parigp, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, pys60, python, q, qbasic, rails, rebol, reg, rexx, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, spark, sparql, sql, stonescript, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, upc, urbi, uscript, vala, vb, vbnet, vedit, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

# SEEG and EEG channels contains V measures.
Unit = SEEG,V
Unit = EEG,V

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:

1. // AnyWave Marker File

2. Start	-1	0.957031        0

3. Section	-1	0.960938	2

4. Marker1	-1	150.957         0

5. CRISE	-1	213.023         0

6. Marker2	-1	300.957         0

7. Marker3	-1	450.957         0

8. Marker4	-1	578.707         0

9. Special	-1	600.957         0     A1

10. 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.
There is an optional fifth parameter : the channels or sensors targeted by the marker; AnyWave can handle markers which concern specific channels or sensors.
If no channel names are specified, AnyWave will consider the marker as a global marker.
To specify channel names, simply add the names of the channels separated by a coma ','

The marker named Special is an example of a marker which targets the A1 channel.

The duration attribute is only necessary to define markers of type Selection in AnyWave. Those are markers which mark a segment of data.

In our example, we have a total of 9 markers. One of them is a Selection marker, called Section and has a duration of 2 seconds. The first marker is called Start and the last one is called END.
Depending on the acquisition system used to record data or if the file was exported by AnyWave, markers can have different labels.

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, ))