Behavioral Control in MATLAB



Input / Ouput
Timing Script
Other Problems / When all else fails...

Known Bugs & Limitations


NEW! MonkeyLogic User's Forum 


1. Cannot get MonkeyLogic to run, or an error is encountered when launching the main menu with the "monkeylogic" command:

  • Make certain the hardware conforms to those listed in the system requirements.
  • Make certain the required directx drivers are installed (specifics available upon request).
  • Make certain Matlab is of at least version r2007b.

2. An error is encountered when trying to load a conditions file:

  • An comment should appear in the message box in the lower-right-hand corner of the main menu, describing the encountered problem.
  • Make certain all required files (image files, condition- and block-selection / change routines, timing scripts,etc) are in the experimental directory.

3. An error is encountered when trying to launch a task:

  • Make certain Matlab is being run without JAVA enabled (type "matlab -nojvm" from the command prompt).
  • Check the video.
  • Check the I/O.
  • Debug the timing script.



1. Video doesn't work at all or only transiently:
  • Make certain Matlab is running with JAVA disabled (launch by typing "matlab -nojvm" from the command prompt).
  • Make certain the required DirectX drivers are installed.
  • Try the "Test" button near the top of the video pane in the main menu. If an error occurs here, try different settings, particularly for refresh rate and resolution, until a combination is found that works for the installed video hardware.
  • If running under Windows 7, make certain the desktop is not using an "Aero" theme.

2. Video intended for the subject appears on the experimenter's display, or the desired subject screen is not available from the pull-down list:

  • Exit Matlab and go to the OS video system properties. Enable the second display, then restart Matlab. Now, launch MonkeyLogic and select the desired subject screen device from the top of the video pane in the main menu.

3. Images appear distorted, or do not display at all:

  • Check the video settings, as for #1, above.
  • If the video test works properly, but images are distorted, check the appearance of the images in the middle pane, in the stimulus section. If the stimulus here appears incorrect, then either that image is in an unsupported format or the file is corrupted.
  • Pressing the "Test" button here will display the image on the designated "subject" screen at the currently selected video hardware settings. If the image displays properly in the menu, but does not display correctly on the subject screen (despite the video test working properly, see above), this may represent a bug in the software; please contact us for assistance.

4. A "could not blit" error is encountered:

  • If a "could not blit" error occurs during task performance, this likely means the stimulus image is either too big to fit on the screen, or is placed at least partially off the screen, at the currently-selected resolution (and pixels-per-degree settings, which determine actual eccentricity given a particular position in degrees of visual angle). If, in the main menu, that stimulus is clicked (in the center pane), a statement will appear in the message box (bottom right corner of the main menu) indicating if that image is either too big or placed out-of-bounds. Note that this cannot check an image along any translation paths defined for it using the set_object_path command.
  • This error can also occur if a subject's joystick cursor is calibrated such that extreme movements will place it outside of screen boundaries. The solution is to recalibrate the joystick such that the limits of movement do not take the cursor off the screen.

5. Images flash-off, or recently extinguished stimuli briefly re-appear when calling showcursor:

  • A fix has been applied in the 9/08 revision of MonkeyLogic.

6. The video refresh period, as displayed when starting a task, does not conform to the refresh rate set in the menu:

  • This is usually due to hardware limitations, most often in the capabilities of the video card. For example, setting the subject's screen to run at 1280 x 768 at 100 Hz may result in a 16.7 ms frame period (60 Hz) because the video card cannot keep up with the chosen refresh rate at this resolution.



Make certain to first read the Input / Output System & Calibration guide.

1. Unable to initialize or read the I/O hardware when launching the main menu:

  • Make certain the Matlab Data Acquisition Toolbox is installed.
  • If only some boards appear, then either Matlab does not recognize the type of board in use, the board is not installed properly, or the driver is not installed properly.

2. Cannot acquire or analog input signals:

  • If using National Instruments devices: Open the National Instruments "Measurement and Automation" application, and navigate to "Test Panels" for the DAQ board intended for use with MonkeyLogic. If signals cannot be acquired in this application, then there is a problem with the DAQ hardware or the drivers.
  • From the MonkeyLogic main menu, select a board, subsystem, and channel in the top-right menus, then click on "Test" (just below these list-boxes). If the signal cannot be acquired here, then the problem lies in the Matlab DAQ toolbox.

3. An error is encountered when attempting to calibrate analog inputs:

  • Make certain both the x and y inputs are working properly (see #2, above).
  • Make certain at least 5 non-colinear points are selected as the calibration coordinates.

4. Effective sampling rates are much less than 1 kHz, as tested using the "Test analog inputs" button in the right-hand "Input/Output" pane of the main menu:

  • Install a duplicate DAQ board and split analog inputs into the same channels of both boards. See temporal precision (first reference) for details.

5. Matlab does not recognize the parallel port:

  • Try the matlab command: daqregister('parallel').
  • Make sure the parallel port driver is set to run automatically at start-up (not just "on-demand").

6. Cannot send behavioral codes or the values recorded on the acquisition systrem are not as expected:

  • Make certain the correct bits (lines) are selected for the data and strobe functions (e.g., for parallel ports, the data bits are port 0, lines 0-7, and the strobe bit is port 2, line 0).
  • Make certain the correct strobe bit polarity (falling or rising edge) is selected (e.g., on Plexon, it should be set to "falling" whereas on Cyberkinetics system, it should be "rising.").
  • Click on "Test Behavioral Codes" to send a sequence of 20 through 2n values, ten times (n is the number of assigned lines). This tests each line independently.

7. A DAQ error is encountered when launching the task

  • Go to the main menu and assign each desired I/O function, one at a time, pressing "Check" after each. The button should turn green and read "Passed" if the assignments are permitted, or "Failed" if an assignment is incorrect (e.g., the type of I/O subsystem is not appropriate for the behavioral function).

Timing Scripts

If an error occurs in a timing script, the error-escape routines will attempt to gracefully shutdown the video and DAQ devices before throwing an error report and returning control to the user. This error report contains line-number references to the run-time function, not the user's actual timing script (the run-time function is the m-file into which the user's script has been embedded). To review the source of the error, open the "runtime" directory in the MonkeyLogic base directory, and open the m-file, named [user's timing script name]_runtime.m. Once the error has been identified, fixes must be applied to the user's timing script, not to this run-time function, in order for them to take effect.


Other Problems / When all else fails...

1. MonkeyLogic crashes unexpectedly during task execution:

  • Make certain no other instance of Matlab is running with Java enabled.
  • The most common causes include timing script errors and errors in user-provided functions such as block-selection / block-change / condition-selection functions; if that is the case, the error message should trace back to the user's function.
  • In addition, this can on some systems be caused by any event that takes focus away from the subject's screen, such as a Windows pop-up warning or a errant mouse-click. The solution, for now, is to turn-off warnings and to avoid re-focusing the display with the mouse.

2. Cycle rate is unexpectedly low:

  • Make certain no foreground applications other than Matlab are running.
  • Make certain time-consuming background applications (e.g., Google Toolbar) are disabled or uninstalled.
  • Disable any "user plot" functions and re-assess the cycle rates, as complicated figures can sometimes slow-down behavioral sampling.
  • Cycle rates can be increased by using behavioral signals "raw" (i.e., pre-calibrated).
  • Cycle rates will be increased if using only one, rather than two, data acquisition boards (not recommended).

3. The task is taking very long to start-up (more than a few seconds):

  • This can be caused by a conditions file with many conditions (e.g., several thousand), but should nevertheless take only several seconds.
  • This can also be caused by running an experiment with a large number of movies, or fewer, but very large movies. To avoid this, uncheck the "Save full movies to BHV file" option on the main menu. In this case, only the first frame of each movie will be saved, saving start-up time and decreasing file size.

4. Inter-trial-intervals lasting too long:

  • Most often, this is caused by delays in the processing of large stimuli (e.g., large or long movies). Enable the "process" option in the task panel adjacent to the stimulus box. This will cause all stimuli to be pre-processed ahead of the first trial.
  • If running with web updates enabled, try disabling them. If the ITIs are now the expected length, check the FTP server to make certain it is responding in a timely fashion.

5. AbsoluteTrialStartTime is not accurate / shows discontinuities:

  • This may occur because Windows occasionally updates its clock by checking in with a remote server. If you need to use AbsoluteTrialStartTime (such as in an fMRI experiment), disabling this clock-checking may solve this problem (Thanks to Andy Mitz for identifying both the problem & the solution):
  • Method 1: Open the registry editor, regedit, and navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Parameters. Find the REG_SZ value named Type. Change the value to NoSync. Change it back to Nt5DS to re-enable syncing.
  • Method 2: From the command line, type: reg add HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Parameters /v Type /d NoSync /f

6. When all else fails:

  • At most error occurrences, MonkeyLogic will attempt to exit gracefully (closing DAQ objects, releasing video objects, and returning control of the keyboard) and save the workspace as a ".mat" file, called ml_error_workspace.mat in the current Matlab working directory . This file can be loaded and variable values inspected to determine the source of a problem.
  • If the error is suspected to lie in core MonkeyLogic code rather than in user-provided code (e.g., in timing files or block-selection functions, etc.), write to one of us, as listed on the contacts page. Include the error message and the ml_error_workspace.mat file, if possible.

Known Bugs and Limitations

Currently unresolved issues:

  • Despite attempts to initialize all trial subfunctions before the first trial, there remains a one-time cost impairing timing accuracy in that trial.
  • Analog stimulation objects ("stm" objects in the conditions file), can be triggered only once from within any single trial.
  • Analog data is not stored continuously in the BHV file; it is stored in segments spanning only the trial itself, excluding the inter-trial-interval.


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