The eyevec-convert command-line utility enables you to converts the content of an EyeVec data file (a binary file) to CSV format. You can feed the resulting CSV file into a spreadsheet program or a statistics program such as R.

The output that can be generated by this program is highly configurable. By default the CSV columns generated depend on the flags passed to the program. However by providing a so-called column definition file you can define which columns should be present in the output file, which names they should have, and in what order.

Synopsis

eyevec-convert [<option> ...] <file>

Options

Option Default Description

-u

show basic usage message

-h

show usage details, examples and version information

-v=num

0

verbosity level

-def=file

<empty>

column definitions file, leave empty to use defaults

-out=file

<empty>

CSV output file, leave empty to derive from input file

-list

off

show defined CSV column names and quit

-inf

on

include general file info

-cfg

on

include configuration records

-bas

on

include baseline start/end records

-cal

on

include calibration start/end records

-val

on

include validation start/end records

-dc

on

include drift-check start/end records

-rec

on

include recording start/end records

-msg

on

include text message records

-fix

on

include fixation start/end event records

-sac

on

include saccade start/end event records

-bli

on

include blink start/end event records

-fxu

off

include fixation update event records

-blu

off

include blink update event records

-eye

off

include eye sample record

-pp

off

include pupil data in eye sample record

-cr

off

include cr data in eye sample record

-ir

off

include iris data in eye sample record

-gz

on

include gaze data in eye sample record

-hd

off

include head sample record

-right

on

select right eye records

-left

on

select left eye records

-mean

on

select mean eye records (events records only)

-both

off

select only both-eyes records (eye sample records only)

-orc

off

also process gaze events and eye samples outside recording

-wide

off

for eye sample records use wide format

-r

off

use R-friendly format in message_text column

-px

off

convert logical gaze positions to pixels

-mm

off

convert logical gaze positions to millimeters

-utc

off

show timestamps in UTC, otherwise relative to start

-s

off

express relative timestamps in s rather than ms

  • The '=' symbol in options that have an argument may be replaced by a colon : or by whitespace. So -opt:arg or -opt arg are effectively the same as -opt=arg.

  • To turn off options that are on by default, put a dash after the option; for example, -foo- will turn off option foo. You may also specify -foo=x where x is one of false, true, no, yes, off, on, F, T, Y, N, 0, 1.

  • Options may be specified in any order. The order does not affect the program’s behavior.

Arguments

The program expects the name of one EyeVec data file (e.g. results.bed).

Examples

In the examples below we’ll be converting the following file: results-p15.bed

  • Converting to CSV format, with default columns; output file name derived from input file (so results-p15.csv):

eyevec-convert results-p15.bed

This yields: results-p15.csv

  • The same, with explicit output file name:

eyevec-convert results-p15.bed -out=foo.csv

This yields: foo.csv

  • Same as first example, with R-friendly output for the message_text column:

eyevec-convert results-p15.bed -r

This yields: results-p15.csv

  • Converting to CSV format, with default columns; now also including eye samples, excluding right and mean eye:

eyevec-convert results-p15.bed -eye -right=no -mean=no

This yields: results-p15.csv

  • Converting to CSV format, with default columns; including eye samples (gaze data only) in wide format:

eyevec-convert results-p15.bed -eye -wide

This yields: results-p15.csv

  • Converting to CSV format, with user defined columns (see columns.txt listed at the bottom of this page):

eyevec-convert results-p15.bed -def=columns.txt

This yields: results-p15.csv

  • Checking the columns definition file columns.txt listed at the bottom of this page:

eyevec-convert -def=columns.txt -list

This yields: output.txt

  • Checking the columns definition file columns-wide.txt listed at the bottom of this page:

eyevec-convert -def=columns-wide.txt -list -wide

This yields: output.txt

  • Showing the default column definitions used (adapts to specified options, try it):

eyevec-convert -list

This yields: output.txt

Defining columns

The output that can be generated by the eyevec-convert program is highly configurable.

By providing a so-called column definition file you can define which of the predefined columns should be present in the output file, which names the columns should have, and in which order they should be.

To compose your own column definition file just make a copy of one of the following and edit it it to your needs:

For a full description of the predefined columns please see EyeVec data file contents.