CORTEX data file structure

As the experiment runs, CORTEX writes on disk a binary file that contains all the information needed for off-line data analysis. At the end of each experimental trial, the collected data are appended to the current file, then CORTEX proceeds to run the next trial. Thus, the data file is a sequence of data blocks, each of them describing completely what happened during the corresponding trial. Incidentally, there is no global header in a CORTEX file, and analysis software (including the @cortex class) simply goes through it, trial-by-trial, until the end-of-file is encountered. One of the consequences of this simple sequential organization of the file is that it is possible (although not recommended) to keep appending data from one day's experiment to the previous day's data file, and the analysis programs "won't know" the difference.

The chunk of data file comprising one trial is further divided into 2 parts: a fix-sized header and 2, 3 or 4 arrays ("buffers") of values whose size depends on how much "stuff" happened during the trial.

Header

A trial header consists of the 15 values listed in the following table. Values in italics are meant for software programs to properly read the file, but are not directly used in data analysis. All the others carry relevant information that can be used to categorize trials.

nickname

type

meaning

header length

ushort

the size of the header in bytes. As far as I know this value is always 26

cond_no

ushort

the condition number (base 0)

repeat_no

ushort

the repetition number (base 0)

block_no

ushort

the block number (base 0)

trial_no

ushort

the trial number (starts from 1)

timebuf_size

ushort

length in bytes of the time stamp buffer

codebuf_size

ushort

length in bytes of the encodes buffer

eogbuf_size

ushort

length in bytes of the eog buffer

eppbuf_size

ushort

length in bytes of the epp buffer

eog_rate

ubyte

ms between eog samples. set in General Parameters

KHz_resolution

ubyte

data collection sampling rate. idem

exp_response

short

an attribute of the condition (trial_type)

response

short

the argument passed to the response_xxx() function

response_error

short

the value returned by the response_xxx() function

Buffers

During each trial, various events can be recorded. Some events are issued by the timing file by means of the function encode(code). Some other events (namely, spikes) are collected by CORTEX itself in the background. Either way, whenever an event occurs, its code number is appended to the codes buffer, while the time (in ms, relative to the beginning of the trial) at which the event occurred is appended to the times buffer. Thus, the times and codes buffers will always contain the same number of elements.

Unlike spikes, which occur at unpredictable times, eye positions are sampled at a fixed rate. They are, therefore, stored in a different way. The eog buffer is a sequence of X and Y coordinate values... [to be continued]

times

ulong

the time stamps

codes

short

the encodes

epp

short

evoked potentials

eog

short

eye movement data