Behavioral Data

Viewing Behavioral Data
The BHV Data Structure
Behavioral Codes (Event-Markers)
Understanding Timing of Behavioral Event Codes
On-Line Behavioral Updates / Remote Alerts

Viewing Behavioral Data

MonkeyLogic will store behavioral information pertaining to the task in data files specified by the ".bhv" extension. These files contain basic information about conditions played, behavioral errors ("trial errors"), event markers (as well as their text descriptions) and associated timestamps, etc. In addition, these data files will save a replica of the conditions file structure. Combined with the event markers and condition numbers, this information allows complete reconstruction of an experiment's events from the data file. This is illustrated by the behaviorsummary function, which plots performance over time, displays a reaction-time histogram, and will also play-back any selected trial using the actual visual stimuli used on that trial and the continuous eye- and joystick signals saved for that trial:

The top panel displays the moving-average trial-by-trial behavior, color-coded to match the scheme used in the control screen (e.g., green = correct, red = incorrect, etc). Vertical white lines in this graph represent block transitions, and the white numbers at the bottom indicate the block number played during each of these intervals. The bottom-right panel shows the reaction-time histogram, as determined on-line during task execution. The bottom left panel allows you to select a trial (which can also be done by clicking on the top graph), and then displays the condition, block, error, and RT information, as well as a list of event-markers for that condition.

Pressing the "Play" button will play back a trial in the bottom-middle panel. The eye- or joystick-position is overlaid onto the images as seen by the subject for demonstration purposes. Toggling the "Play at Full Resolution" button will play the trial back in a window which conforms to the actual dimensions of the subject's screen during the task.

Toggling the "Make AVI Movie" button to the "on" position will activate the FPS box, which determines the Frames Per Second that will be written to the AVI file. Clicking "Play" will bring up a dialog prompting for the filename of the AVI movie, and then will proceed to generate that video file.

Pressing the "Timeline" button displays a standard event raster for the selected trial:

Here, green vertical bars indicate reward delivery, and the yellow traces at the bottom are the recorded x- and y- eye position data. Note that the alignment between visual events and analog data here is approximate (though it shouldn't deviate by more than 2-3 milliseconds); simultaneous acquisition of slow analog signals into the neural recording system (e.g., Plexon) is mandatory in order to know the precise relationship between these data.

The BHV Data Structure

Behavioral files can be read manually with the command:

BHV = bhv_read([datafile])

where BHV is a structure with the following fields:

Note: Playing a movie of each trial is available only for file versions >= 2.0.

Behavioral Codes (Event-Markers)

The behavioral codes used as event markers are stored explicitly in the behavioral data file, in BHV.CodeNamesUsed. This allows fuller reconstruction of an experiment post-hoc using only this data file. These behavioral codes and descriptions are determined by a simple text file with two tab-separated columns for code number and code description, respectively (the first line is always assumed to be a header and is ignored). Codes 9 and 18 are reserved (they are used to mark the beginning and end of each trial), and so should not be over-written or coded into the task. Codes must be listed consecutively, starting from number one, without breaks.

During task execution, the eventmarker command, and the "eventmarker" parameter of the toggleobject command, are used to timestamp a behavioral event (both locally and externally on a separate neural data acquisition system, if applicable).

In order to make a task decipherable in the future to other people who might potentially be looking at the data, the code descriptions should be clearly reflective of the specific events they indicate. An example (very generic) codes file s available to download as newcodes.txt.

Codes 9 and 18 are reserved and should remain unmodified. They are used to synchronize a behavioral data file with a neural data file, as they represent the first and last events within a trial; three code 9's and three code 18s are written to the beginning and end of each trial, respectively.

Different codes files can be associated with different conditions files, as specified in the main menu.

Understanding the Timing of Behavioral Event Codes (Event-Markers)

Trials begin when the trial timer (maintained by the trialtime function in trialholder.m and embedded in the experiment's runtime file) is initialized. When the trial timer is initialized, sample collection begins from the analog inputs of the DAQ device (through the DAQ toolbox in Matlab). After this, Monkeylogic initializes all the subroutines that will be used during the trial - video, I/O, end_trial and eventmarker.

Once these are initialized, eventmarker writes 3 '9's to the BHV file to mark the beginning of the trial. This information is recorded in the BHV.CodeNumbers field in the BHV file. The BHV.CodeTimes field records the corresponding time from the onset of the trial (as measured by trialtime) for each eventmarker. The first value in each trial's CodeTimes field represents the writing of the first '9' marking the beginning of the trial. Each subsequent value corresponds to a trial marker in CodeNumbers, and the last three correspond to the 3 '18's that are written to mark the end of a trial.

Thus, the first Analog Input sample occurs before the onset of the first '9'. Timing of the trial starts with the acquisition of samples from the DAQ device. The first Analog Input sample that aligns with the 9 (assuming a 1 kHz sampling rate) will occur at the time specified in the first value of BHV.CodeTimes (which stores the time of the first '9').

For example, if data from the BHV file looked like this (the data we're looking at is from the 10th trial in a session, and is read from the BHV file):

The code times for the eventmarkers that occurred during this trial are:

The first '9' (representing the start of the trial) occurred 109 ms after the first sample is recorded from the Analog Input. Thus, the Analog Input sample corresponding to the start of the trial also occurred at 109 ms (sampled at 1 kHz).

The last value in the CodeTimes represents the onset of the third '18' (representing the end of the trial), which occurred 1717 ms after the onset of the trial.

On-Line Behavioral Updates / Remote Alerts

Behavioral performance can be tracked remotely using the "Remote Alerts" functionality, configured in the lower-right-hand corner of the main menu. Two options are available:

1) Short Text Summary: Turn on Remote Alerts and specify an alert function which will be passed standard information (in the form of a text string) regarding the subject's performance at the end of each block. This function is then expected to send this string to a remote device, such as cell phone or pager, using whatever means are possible within one's available networks. One may optionally specify user-defined criteria for sending alerts by pressing the indicated button and selecting an m-file which takes TrialRecord as its input and returns a 1 or 0, the former indicating a "send" request; the standard string will then be sent to the alert function.

2) Web-Based Update: Turn on Remote Alerts and then enable the dynamic updating of a web page by selecting an HTML template as the alert function. For this to work, one must have ftp access to a web-hosting account. This web page will be updated during each inter-trial-interval with the subject's latest peformance characteristics (graphs will be updated every 10 trials). This function requires two components:

• A simple text file containing information about one's ftp server, to be named ftpinfo.txt and placed in the MonkeyLogic directory. It must contain five lines, listing
  • 1) the server address (without the preceding "http://").
  • 2) the username for the ftp site.
  • 3) the ftp password for that username.
  • 4) the pass-code you wish to use for authorizing remote commands. This can be the same or different than the ftp password.
  • 5) the directory on the ftp server in which to place the files. (To place files in the root directory, indicate this with a single ".", i.e., period)

• An HTML template containing place-markers for the information to be displayed. One such template, named mlwebsummary.html, is provided. Note that the web page to be uploaded (into the root directory of the server account) will be renamed: ComputerName.HTML, where "ComputerName" is the assigned name of the computer running MonkeyLogic. To access the web page, go to: http://Server/Directory/ComputerName.HTML, replacing "Server," "Directory" and "ComputerName" with the appropriate strings.

The following is a list of place-holders available for use in the template file (these are case-sensitive; most are self-explanatory):

HTML Template File Place-Holders

The Output Created by mlwebsummary.html