|
File Formats - Time Series Data
Description
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.
Minor Rev
The current minor rev for data time series
files is 4. This should be used when creating files for use by EMSE v4.1
and above. Use minor rev = 3 (described below) for EMSE v4.0, and use
minor rev =2 for versions prior to 4.0.
Minor rev = 4
The block structure of minor rev = 4 files is : header, channel list,
data.
Minor rev = 3
The block structure of minor rev = 3 files is : header, data, channel
list.
Minor rev = 2
The block structure of minor rev = 2 files is : header, data, channel
list.
Minor rev = 1
The block structure of minor rev = 1 files is : header, data. There is no
channel list.
In addition, the minor revs differ in the definition of the channel state,
as described in Table A-3.
Comments
Any line beginning with '//' is a comment line, and will be
ignored. However, comment lines may not be inserted within an amplitude
list for a single channel. Comments may appear between channels in trace
mode, or between slices in slice mode.
Header
The header consists of 7 or 8 entries (in mandatory sequence), shown in
Table A-1.
| Name |
Format |
Description |
| Mode |
%x |
101 (trace mode) or 102 (slice mode) or 8101
(8102) if #Epochs Used is set) |
| #Channels |
%d |
number of channels (1 gradiometer or 1 electrode
= 1 channel) |
| #Slices |
%d |
number of points per channel per epoch
|
| Sample Period |
%g |
a/d sample period (seconds) |
| Conversion Factor |
%g |
multiplier to convert channel amplitude list
values to Tesla or Volts |
| Trigger Time |
%g |
time (in seconds) to trigger after start
of epoch (or 0 if no trigger) |
| #Epochs |
%d |
number of epochs in this file |
| #EpochsUsed |
%d |
number of epochs used to create average |
| state |
%d |
Set to 0 (reserved by Source Signal Imaging) |
Table A-1
Channel list
The channel list consists of one row per channel. Each row consists of two
columns: channel name and channel state, separated by white space, as
defined in Table A-2. Note that the channel state encoding depends on the
minor rev.
|
Name |
Format |
Description |
|
Channel name |
%s |
channel name |
|
Channel state |
%x (rev=4)
%d (rev=3) |
Channel state encoding
depends on the minor rev, as defined below
| type |
min.rev = 4 |
min.rev = 3 |
| magnetic |
200 |
512 |
| electric |
400 |
1024 |
| optical |
4000 |
not defined |
| trigger |
8000 |
not defined |
| other |
10000 |
not defined |
|
Table A-2
On/Off
On/Off channel state encoding depends on the minor rev. In minor rev=4
files, the default channel state is On. To load a channel in the off state,
logically OR the channel state with 0x800. For example an off electric
channel (0x400) becomes 0xC00. In minor rev = 3, the default channel state
is off. To load a channel in the on state, add 1. For example, an off
electric channel (1024) becomes 1025 in the On state. For minor rev = 2
files, only the on/off state is encoded, where 1 = On, and 0 = Off.
Data
The data are represented by a matrix. In trace mode, rows represent
channels, and columns represent time slices. In slice mode, rows represent
slices, and columns represent channels. These formats are described in
greater detail following the channel list description.
| Header |
|
|
|
| Epoch 1 |
Channel 1 |
Slice 1,
Slice N |
each
channel is a row |
|
Channel M |
Slice 1,
Slice N |
|
| Epoch L |
Channel 1 |
Slice 1,
Slice N |
|
|
Channel M |
Slice 1,
Slice N |
|
Trace mode
In trace mode, Each epoch list consists of one or more channel amplitude
lists. Each channel amplitude list consists of one or more time slice values
for that channel. The channel amplitude list order must correspond to the
sequence of channels in the associated sensor position file, and each epoch
must have the same number of channels. Each channel amplitude list must have
the same number of time slice values. Each amplitude value in the list must
be separated by one or more tab, space, or newline characters. Optional
comment lines (lines beginning with the characters '//') may appear at the
beginning of the file and before or after any channel amplitude list.
Comments may not appear within a channel amplitude list. Figure A-1
illustrates some of these definitions.
Example
The following example illustrates a data time series file
(minor rev = 4) in trace mode with 1 epoch of data, with three channels
and 10 slices per channel. The sample period is 0.004 seconds ( = 4
milliseconds) and a trigger occurs at 0.008 seconds. The data are
expressed in femtoTesla, so the conversion factor is 1e-15, or micro volts
(conversion factor = 1e-6).
1
// First comes the prolog (must be line 1), followed by the minor rev
number,
4
//
then the header,
//Mode #Chan #Slices Sample Period ConvFact Trig #Epochs #EpochsInAvg
8101 3 10 0.004 1e-15 0.008 1 128
// then the state
0
// now comes the channel names and states
// note all channels are magnetic, but A3 is off, the others are on
A1 200
A2 200
A3 A00
//
followed by the data
// Channel 1, epoch 1
-0.02 0.02 0.05 0.00 -0.16 -0.28 -0.31 -0.25 -0.13 0.06
// Channel 2, epoch 1
0.19 0.22 0.22 0.24 0.21 0.15 0.06 0.03 0.02 0.05
// Channel 3, epoch 1
0.13 0.22 0.26 0.30 0.36 0.41 0.51 0.67 0.73 0.67
// The end
Slice mode
In slice mode, Each epoch list consists of one or more slice lists. Each
slice list consists of one or more channel amplitude values for that
slice. The channel order must correspond to the sequence of channels in
the associated sensor position file, and each epoch must have the same
number of channels and slices. Each amplitude value in the list must be
separated by one or more tab, space, or newline characters. Optional
comment lines (lines beginning with the characters '//') may appear at the
beginning of the file and before or after any slice list. Comments may not
appear within a slice list. Figure A-2 illustrates some of these
definitions.
| Header |
|
|
|
| Epoch 1 |
Channel 1 |
Slice 1,
Slice M |
each
channel is a row |
|
Channel N |
Slice 1,
Slice M |
|
| Epoch L |
Channel 1 |
Slice 1,
Slice M |
|
|
Channel N |
Slice 1,
Slice M |
|
Example
Here is similar data to the previous example, but now coded in slice mode.
1
// First comes the prolog (must be line 1), followed by the minor rev
number,
4
//
then the header (Note the 102),
//Mode #Chan #Slices SamplePeriod ConvFact Trig #Epochs
102 3 10 0.004 1e-6 0.008 2
// then the state
0
// now comes the channel names and states
// note all channels are electric, but E3 is off, the others are on
E1 400
E2 400
E3 C00
//
followed by the data from Epoch 1
// Slice 1, epoch 1
-0.02 0.19 0.13
// Slice 2, epoch 1
0.02 0.22 0.22
// Slice 3, epoch 1
0.05 0.22 0.26
//
the remainder of the file continues
// considered as data matrices, slice and trace
// modes are the transpose of each other.
Return to File Formats page
|
|
