This is meant to serve as merely an overview of the basic mechanics underlying the iEye toolkit for MATLAB as well as explain some tips and tricks on getting it to do what you want.
//CONVERTING YOUR DATA TO THE .IYE FILE FORMAT
Although file conversion is currently being integrated into iEye directly, for the time being a Python script must be used to convert your data file to the iEye file format (.iye). Currently, both EDF (.edf) and ASCII (.asc) files are easily converted with a corresponding Python conversion script for each format respectively. This can be done from the terminal window with a simple command:
‘edf2eye6’ for EDF conversion
‘asc2eye6’ for ASCII conversion
The script will then convert the corresponding data file to a new .iye data file of the same name in the same directory. For example:
‘edf2eye6 c:datamyfile.edf’ would create the file ‘myfile.iye’ in the ‘c:data’ directory.
The iEye format is a 6 channel data file holding data for x, y, pupil, tarx, tary, and xdat. While future updates will allow a more customizable channel lineup, the current channel structure is a hard-coded limitation. However, more channels can be created in MATLAB and plotted into the iEye GUI at any time (see Variables: GUI vs Base Workspace).
//COMMAND LINE VS GUI
Most, if not all, of the functions in iEye can be accessed through either the command line or the GUI. Many of the functions in iEye include arguments that are necessary for the function to execute. When using the command line, you can either specify the arguments in the call to the function, or just call the function itself. In the latter case, you will then be prompted by a GUI window to specify the necessary arguments. For example:
‘ii_add(‘x’, ‘y’);’ will bypass any GUI controls and simply add channel y to channel x.
‘ii_add();’ will prompt you with a GUI input window asking you to specify the channel you would like to modify as well as what channel you would like to add to it. In effect, it does the same thing as if you had clicked the ‘Add’ option from the GUI menu.
The practical implications of this subtle difference become very important once you are trying to create your own more complex ii_functions that use other ii_functions as building blocks. If you forget to pass the necessary arguments in your code, it will pause when executed and the user will be prompted with a GUI window to manually fill out that information. Take for example, the ii_function ‘ii_preprocm’, whose purpose is to do all preprocessing tasks on memory-guided saccade tasks for a particular experiment:
%II_PREPROCM Summary of this function goes here
% Detailed explanation goes here
The entire function is built on existing ii_functions. By specifying the arguments in each call to the function, the preprocessing is automatic until the file is to be saved, in which the user will be prompted to specify a filename and directory for the changes. However, if the arguments were not passed in the function call, the user would be prompted 8 times by the GUI to fill out a total of 21 different pieces of information. If you are preprocessing 10 data files, that’s 210 boxes to manually fill out…quite inefficient.
//II_FUNCTIONS & HOW TO WRITE YOUR OWN
One of the strengths of iEye is the library of ii_functions able to be used as building blocks to create more complex, customized functions for your specific experiment or dataset. Each ii_function is a standalone ‘*.m’ function file grouped by folders based on their intended usage: analysis, channel, fileio, gui, modify, select, and view.
As this library grows and you add to it, it is incredibly important that this structure is maintained in order to keep things organized and easy to use for everyone. Name the file/function ‘ii_yourfunctionname’ and be sure to place it in the correct corresponding existing folder or if necessary, create a new folder in the base iEye directory to place it in.
Before you begin writing your own ii_functions please be sure to read and understand the relevant sections of this guide, especially ‘Variables: GUI vs Base Workspace’ and ‘Command Line vs GUI’. In addition to this guide, be sure to browse through the code of existing ii_functions to get a deeper understanding of what is going on.
//VARIABLES: GUI VS BASE WORKSPACE
MATLAB separates variables in the GUI workspace (your code/functions/scripts) and variables in the base workspace (Workspace window that lists variables). Therefore, if you intend on manipulating the X channel that exists in the base workspace within your code, simply referencing the variable ‘x’ will do nothing but create a new variable in a temporary workspace that exists only to be destroyed at the completion of that particular function call.
The purpose of the trial view in iEye is to offer a quicker, more streamlined way of viewing individual trials in a data file by specifying repetitive starting and ending cues (ie XDAT). After specifying said cues (as arguments when calling the function through the command line or through the GUI) a separate trial window will open up with an axes and slider. You can use the slider control to move through each trial one at a time, rather than search or scan through the whole data image to inspect your trials. For example:
‘ii_trial(‘xdat’, 4, ‘xdat’, 6);’ will open a new window to view each of our trials, which start when XDAT is at 4 and end once XDAT reaches 6. Obviously, although it is referred to as “Trial View”, there’s no reason the window can’t be used for viewing any specified range of data between two cues.