Behavioral Control in MATLAB


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

NEW! MonkeyLogic User's Forum 


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:

behaviorsummary figure

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:

behavior time-line

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:

Field Type Description File Version
BHV.MagicNumber Scalar Fixed number used to identify the file as a BHV data file > 1.0
BHV.FileHeader String "MonkeyLogic BHV File" > 1.0
BHV.FileVersion Scalar Data file version > 1.0
BHV.StartTime String The time & date at which the behavioral task began running > 1.0
BHV.ExperimentName String The experiment name as specified in the main menu > 1.0
BHV.Investigator String The name of the investigator as specified in the main menu > 1.5
BHV.SubjectName String The name of the subject as specified in the main menu > 1.0
BHV.ComputerName String The name assigned to the computer on which MonkeyLogic is running > 2.1
BHV.ConditionsFile String The path & name of the conditions file used to run the task > 1.0
BHV.TaskObject Cell array of strings The TaskObjects arranged according to (ConditionNumber, TaskObjectNumber) > 1.0
BHV.TimingFileByCond Cell array of strings The name of the timing file called for each condition > 2.65
BHV.BlockByCond Cell array of double vectors The blocks of which each condition is a member > 2.65
BHV.InfoByCond Cell array of structures The Info structure generated for each condition > 2.65
BHV.TimingFiles Cell array of strings The path(s) and name(s) of the timing script(s) used > 1.0
BHV.ErrorLogic String Describes the error-handling used while running the behavior (e.g., "On Error: Repeat Immediately") > 1.0
BHV.BlockLogic String Describes how blocks were chosen (e.g., "Blocks: Random with replacement") > 1.0
BHV.CondLogic String Describes how conditions were chosen within each block (e.g., "Conditions: Increasing condition order") > 1.0
BHV.BlockSelectFunction String If blocks were chosen in a "user-defined" manner, the path and name of the function used (else, "n/a") > 1.0
BHV.CondSelectFunction String If conditions were chosen in a "user-defined" manner, the path and name of the function used (else, "n/a") > 1.0
BHV.VideoRefreshRate Scalar Video refresh rate used in the experiment (Hz) > 2.0
BHV.VideoBufferPages Scalar Indicates whether single, double, or triple video buffering was used in running the experiment. > 2.0
BHV.ScreenXresolution Scalar X-dimension of the subject screen, in pixels > 1.0
BHV.ScreenYresolution Scalar Y-dimension of the subject screen, in pixels > 1.0
BHV.ViewingDistance Scalar Distance from the screen, in centimeters, as specified in the main menu > 1.0
BHV.PixelsPerDegree Scalar The calculated pixels per degree of visual angle > 1.0
BHV.AnalogInputType String The input type used (e.g., "Differential" or "Single-Ended" etc). > 2.01
BHV.AnalogInputFrequency Scalar The frequency (in Hertz) of analog data acquisition. > 2.01
BHV.AnalogInputDuplication String Indicates the state of analog input duplication during the task (e.g., "On" or "Off") > 2.0
BHV.EyeSignalCalibrationMethod String Describes how the eye-signal was calibrated (e.g., "Raw signal (precalibrated)") > 1.0
BHV.JoystickCalibrationMethod String Describes how the joystick was calibrated (e.g., "Online transformation matrix") > 1.0
BHV.PhotoDiode String Describes the position of the photodiode trigger, if used (e.g., "Upper left") > 1.0
BHV.ScreenBackgroundColor vector The R G B values of the subject's screen background > 1.8
BHV.Stimuli Structure Stores actual images used (currently stores only static visual objects, not movies) > 1.0
...BHV.Stimuli.NumPics Scalar The number of images stored > 1.0
...BHV.Stimuli.PIC.Name Cell array of strings The name(s) of the images, as specified in the conditions file > 1.0
...BHV.Stimuli.PIC.Size Matrix m by n by 3 element vector(s) corresponding to the size of the image(s) > 1.0
...BHV.Stimuli.PIC.Data Matrix The image data (each image contains 3 planes corresponding to the R, G, and B components) > 1.0
...BHV.Stimuli.NumMovs Scalar The number of movies stored > 2.4
...BHV.Stimuli.MOV.Name Cell array of strings The name(s) of the movies, as specified in the conditions file > 2.4
...BHV.Stimuli.MOV.Size Matrix m by n by 3 element vector(s) corresponding to the size of a frames in each movie > 2.4
...BHV.Stimuli.MOV.NumFrames Vector The number of video frames contained in each movie > 2.4
...BHV.Stimuli.MOV.Data Cell array of matrices The image data (each cell contains one frame with 3 planes corresponding to the R, G, and B components) > 2.4
BHV.TrialNumber Vector The list of trial numbers, one value for each trial > 1.0
BHV.AbsoluteTrialStartTime Matrix The absolute start time of each trial, as a "clock" vector (6 elements: [year month date hour minute second]) > 2.2
BHV.BlockNumber Vector The list of block numbers, one value for each trial > 1.0
BHV.BlockIndex Vector The ordinal number of the current block, one value for each trial > 1.0
BHV.CondNumber Vector The list of condition numbers, one value for each trial > 1.0
BHV.TrialError Vector The list of behavioral errors, one value for each trial

> 1.0

BHV.CycleRate Vector The list of average behavioral tracking cycle rates, one for each trial > 2.05
BHV.NumCodes Vector The number of event markers stored within each trial > 1.0
BHV.AnalogData Structure Stores analog data acquired for each trial.  
...BHV.AnalogData.EyeSignal Cell array of matrices (n x 2) The data points - x(n) and y(n) - corresponding to eye-position, one cell of vectors for each trial. > 1.5
...BHV.AnalogData.Joystick Cell array of matrices (n x 2) The data points - x(n) and y(n) - corresponding to joystick-position, one cell of vectors for each trial. > 1.5
...BHV.AnalogData.General.Gen1 ... Gen9 Cell arrays of vectors The data points - y(n) - corresponding to voltage level, one for each trial. > 2.5
...BHV.AnalogData.PhotoDiode Cell array of vectors The data points - y(n) - corresponding to the photodiode signal, one for each trial > 1.7
BHV.ReactionTime Vector The list of reaction times, one for each trial. Will be -1 if the timing file does not assign "rt" > 1.0
BHV.BlockOrder Vector The list of blocks in the order they were played (one value per block rather than one per trial) > 1.0
BHV.CodeNumbers Cell array The event markers, one vector for each trial > 1.0
BHV.CodeTimes Cell array The timestamps of the corresponding event markers, one vector for each trial > 1.0
BHV.CodeNumbersUsed Vector The list of unique event markers used in the task > 1.0
BHV.CodeNamesUsed Cell array of strings The descriptions of each corresponding unique event marker > 1.0
BHV.VariableChanges Structure array of vectors

The trial number and value of each variable change
...BHV.VariableChanges.(varname).Trial (a vector of trial numbers)
...BHV.VariableChanges.(varname).Value (a vector of corresponding values)

> 2.05
BHV.FinishTime String The date and time at which the behavioral task stopped > 1.0

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

Note: Trials lasting more than 2^16 milliseconds and up to 2^32 milliseconds are supported only in file versions >= 3.0 (September, 2012 update). If your trials last more than 136 years, you're out of luck.


Behavioral Codes (Event-Markers)

Behavioral codes are created during task execution by employing the eventmarker function. These are time-stamped values that refer to specific task occurrences. To retrieve the eventmarker values and their time-stamps, refer to the "CodeNumbers" and "CodeTimes" fields of the BHV structure retrieved by bhv_read. For example, the list of codes and corresponding code times for trial number 87 would be found in BHV.CodeNumbers{87} and BHV.CodeTimes{87}.

The text descriptions of 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 in this file must be listed consecutively, starting from number one, without breaks, but not all need to be used in an experiment.

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. Eventmarkers should be used very liberally, to time-stamp any discrete event in a trial. An example (very generic) codes file is available to download as codes.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):

ans =

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

ans =

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)
For example:

  • 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

Standard Information Fields:
ML_OverAllCorrect (percent over all trials)
ML_ThisBlockCorrect (percent over current block)
ML_BlockCount (number of blocks played so far, including current) ML_BlocksCompleted (number of blocks completed so far)
ML_MeanReactionTime (averaged over all trials)
ML_RecentTrialErrorsAll (25 most recent)
ML_RecentTrialErrorsThisCondition (25 most recent)

Special Objects:
ML_Status (e.g., "Running..." or "Paused" etc.)
ML_LastUpdate (the time the page data was last updated)
ML_ComputerName.bmp (the behavioral graph, 600x300 pixels)
[Note: "ML_ComputerName.bmp" is to be entered literally, without substituting the actual computer name]
ML_CommandEntry (the data entry fields for remote access)
ML_HTML (the template's name)


The Output Created by mlwebsummary.html

Web Update



This site last updated: May, 2014
© 2008-2014