File Formats - Time Series Data (versions 5.0 and above)

This document describes the data file format used in version 5.0 of the EMSE software.  The data are represented with two files, the header file and the data file.  The header file is used to describe the nature of the data file.  It is a text file in Extensible Markup Language (XML) format*.  It consists of many “keyword-value” sections.  The data file is simply a matrix with rows and columns of numbers (real or complex).  It can be ASCII or binary as specified by a descriptor in the header file.  The data file has the name <filename>.bin while the header file has the name <filename>.bin.emse_hdr (or in the case of an ASCII data file, <filename>.txt and <filename>.txt.emse_hdr).  The <filename> portion of the name is the same in both the data and header files.  The following sections will describe each file in detail and will give examples of EMSE data files.  There is also an additional file, the event file, used in EMSE to mark the time points of events in the data.  The event file is also a text file in XML format.  It has the file name <filename>.evt.  An example is shown below.

The Header File Format

EMSE uses XML in the header file primarily because so that it can be viewed in any text editor or XML parser, and it is easily extendable.  The details of constructing an XML file are not described here. We simply define the fields used in EMSE.  All fields must be bounded inside the <EMSE_Header> and </EMSE_Header> tags.  The names of the fields are predefined.

The Data File Format

1.    Binary data

The size of a binary data file depends on the DataFormat of a datum. Short or Swab_Short has 2 bytes. Long or Swab_Long has 4 bytes. Float or Swab_Float has 4 bytes. Double or Swab_Double has 8 bytes. Therefore the size of a file in bytes = the number of channels * the number of total slices * sizeof(a datum), regardless of the matrix orientation. In slice mode, you may use the following lines to access the nth slice of data. In this case we assume that the data is of short type.

short* pBuffer = new short[ the number of channels ];

long lByteOffset = (the number of channels) * (n-1) * sizeof(short);

fseek(fp, lByteOffset, SEEK_SET);

fread(pBuffer, sizeof (short), (the number of channels), fp);

2.    ASCII data

The size of an ASCII data file varies. Like binary data files, they are in rows and columns. They also can be viewed in many spreadsheet programs such as Microsoft Excel. In slice mode each row represents a slice and each column represents a channel, while in trace mode each row represents a channel and each column represents a slice.

3.    The unit of the data

The unit for electric data is Volt,  and for magnetic data is Tesla (in the time domain).  For EMSE generated files, it is Volt or Tesla for EvokedPotential and FourierTransform; Volt^2 or Tesla^2 for PowerSpectrum; unitless for Coherence; unitless for EvokedPotential and PVALUES_P or PVALUES__LOGP or PVALUES_LOGQ or PVALUES_LOGQ_LOGP.

Examples of EMSE Data Files 

The following example illustrates a time series data file which has two EEG channels and four slices, and is stored in an ASCII text file, example1.txt with example1.txt.emse_hdr.

example1.txt.emse_hdr

<EMSE_Header>

<DataFileName>C:\Tmp\ example1.txt </DataFileName>

<DataDomain>TimeDomain</DataDomain>

<DataFormat>ASCII</DataFormat>

<NumChans>2</NumChans>

<SampleRate>500</SampleRate>

<RunType>SingleEpoch</RunType>

<NumSlices>200</NumSlices>

<PreStim>-0.1</PreStim>

<NumTrials>1</NumTrials>

<DataType>EvokedPotential</DataType>

<PValues>NA</PValues>

<ChannelList>

<Channel><Name>FP1</Name><Type>1024</Type><Scale>1</Scale></Channel>

<Channel><Name>FP2</Name><Type>1024</Type><Scale>1</Scale></Channel>

</ChannelList>

</EMSE_Header>

example1.txt

1.008e-007  -1.74e-008 

-3.742e-008-1.063e-007

-6.137e-008-9.006e-009

7.744e-008  2.041e-007