Skip to content

Laboratory of Neuropsychology

Main Menu

Logo & Load/Save Settings

  • Three monkeys logo: Open the NIMH MonkeyLogic homepage.
  • Collapse/Expand menu button (at the top-right corner of the logo): Hide/Show submenus (Video, Input/Output and Task). The collapsed menu is useful when running NIMH MonkeyLogic on a small screen.
  • [Locate] config button: Open the config file folder. It is usually the current task directory.
  • Load settings: Once a config file is chosen, a pop-up window as below will show up and ask which subject’s configuration you want to load from the file. See "Subject name" in the "Conditions File & Run Button" menu section.

  • Save settings: Store the current settings to the config file (*_cfg2.mat). The button is activated only when there is something changed. The current config is saved without asking, when the ‘RUN’ button is clicked.

Conditions File & Run Button

  • [Load conditions file] button: Open a conditions/userloop file (i.e., load an experiment).
    • [Help] button: Open the conditions file manual.
    • [Edit] button: Open the current conditions file in the text editor. The conditions file should be reloaded after edits have been completed.
  • [Stimulus list] pane: Show the list of the stimuli found in the conditions file. In case that the opened file is a userloop function, it will display ‘user-defined’.
    • Earth icon: Display the stimulus selected in the [stimulus list] pane.
    • [Test] button: Display/play the selected stimulus, as if it is displayed/played during a trial. Pressing any key will stop the test.
  • Total # of cond. in this file: Displays the total number of conditions found in the selected conditions file.
  • [Blocks] pane: Display the available blocks.
    • Total # of cond. in this block: Displays the total number of conditions associated with the selected block.
    • # of trials to run in this block: Edit this value to determine the number of trials to be run in the selected block.
    • Count only correct trials: As it states.
    • [Chart blocks] button: Open a figure that shows which conditions appear in which blocks, such as the following one.
    • [Apply to all] button: Apply the changes to all blocks.

  • Blocks to run: Only the blocks selected here will be used during task execution. Initially all blocks are selected.
  • First block to run: Select the first block to run, when the task starts. ‘TBD (to be determined)’ will let ML determine it, according to the block selection logic in the Task submenu.
  • Timing files: Display the timing files used by the current conditions file. In case that a userloop function is selected, ‘user-defined’ will be displayed instead.
    • [Help] button: Open the timing script manual.
    • [Edit] button: Open the selected timing file in the MATLAB editor.
  • Total # of trials to run: Determines when the task will stop if not manually terminated. This number includes both correct and incorrect trials.
  • Total # of blocks to run: Determines the total number of blocks (not block numbers) to be run; the task will end once this number of blocks has executed (or the "Total # of trials to run" value has been reached, whichever comes first).
  • Subject name: NIMH ML keeps a separate configuration per each subject. If the entered subject name is new, then the current settings are copied under the new name and the “Save settings” button is activated. If the entered name already exists in the configuration file, the settings previously saved under the name are loaded automatically.
    • If there are unsaved changes when a new name is typed, a pop-up window will ask if you want to save the changes. However, it is not for the new name you just typed, but for the name there before you typed. Therefore, the “Save settings” button will stay active, even after you answer “Yes” to the pop-up.
    • When the task is loaded next time, the last subject’s configuration will be loaded.
    • Unlike the original ML, NIMH ML keeps the last changes of editable variables in the configuration file (per each subject) and does not read the variables from the timing script ever again. When a new subject’s profile is created, the values of editable variables are also copied from the current subject’s configuration. Therefore, in NIMH ML, editable variables are never reset to the initial values written in the timing script, once read. So, to modify their values, do not edit timing scripts. Use the editable variable dialog in the Pause menu.
  • Filename format: Set the format of the default data file name.
    • ‘expname’ or ‘ename’: Experiment Name
    • ‘yourname’ or ‘yname’: Investigator
    • ‘condname’ or ‘cname’: Conditions file name
    • ‘subjname’ or ‘sname’: Subject name
    • yyyy: Year in full (1990, 2002)
    • yy: Year in two digits (90, 02)
    • mmm: Month using first three letters (Mar, Dec)
    • mm: Month in two digits (03, 12)
    • ddd: Day using first three letters (Mon, Tue)
    • dd: Day in two digits (05, 20)
    • HH: Hour in two digits (05, 24)
    • MM: Minute in two digits (12, 02)
    • SS: Second in two digits (07, 59)
  • Data file: Leave this field blank, if you want it to be filled with the default formatted name.
  • [Locate] runtime button: Open the runtime folder. It is Windows’ temporary file folder.
  • [RUN] button: Activated when a task is loaded. Upon its being clicked, the current configuration is automatically saved and the task begins.


  • [Latency test] button: Run a benchmarking trial.
  • Subject screen device: List the screens on the system.
  • [Test] button: Display an animation on the selected screen.
  • Resolution: Pixel width & height of the selected screen. Use [Windows Display Settings] to change the resolution.
  • Diagonal size (cm): Enter the diagonal screen size (in cm) of the subject's screen.
  • Viewing distance (cm): Enter the distance (in cm) from the subject's eyes to the screen.
  • Pixels per degree: This number is used by Monkey Logic to compute the degrees of visual angle. It allows users to specify stimulus coordinates in degrees instead of pixels.
  • Fallback screen rect.: This fallback screen is a windowed subject screen and is used for testing when there is only one monitor. [LEFT TOP RIGHT BOTTOM] in Windows’ pixel coordinates.
  • Forced use of fallback screen: Force the subject screen to be displayed in a window.
  • Vsync spinlock: This is a period before the vertical blank time in which ML stops other jobs and just waits for screen flipping.
  • Subject screen background: Background color of the subject screen.
  • Fixation point, Eye tracer, Joystick cursor, Touch cursor: Allow you to use either an image/movie or a circle/square of given color and size for these objects.
  • Photodiode trigger: Display black and white squares in turns at the selected location to drive the photodiode.

Task Submenu(s)

Task Selection Settings

  • On Error: What to do if the subject makes an error.
    • Ignore will simply disregard errors when the next condition is selected.
    • Repeat immediately will cause the same condition to be played repeatedly until the correct response is chosen (i.e., trialerror(0) has been set by the timing file).
    • Repeat delayed will throw that condition into the queue, but at a later point in the block; this can happen an indefinite number of times for a given condition. If a particular condition is repeatedly performed incorrectly, increasing numbers of copies of this condition will "pile-up" later in the block, though still interspersed with whatever other conditions still remain to be played.
  • Conditions: Determines the method used to select the next condition.
    • Random with replacement causes the next trial's condition to be selected randomly, without regard to which conditions have already been used.
    • Random without replacement will randomly choose the next trial's condition but will exclude those trials already used; if the block length exceeds the total number of conditions available in that block, the available conditions from which to select will be replenished each time they are exhausted.
    • Increasing and Decreasing simply choose the next condition in numerical order, rising or falling as appropriate. The condition numbers will "wrap" when the end or beginning of the condition list has been reached.
    • User-defined allows the writing of a matlab function to determine how conditions are selected. This is useful to enact particular rules about how certain conditions should follow others, or how the selection of certain conditions preclude others, for example. This function should be contained in a typical m-file and should expect the TrialRecord structure as input, and should return a single scalar, the condition to-be-run. If a value of -1 is returned, this will indicate that the block has ended, and a new block should be selected.
  • Blocks: Identical in logic to Conditions, above. Here, however, the user-defined option should return the desired block-number as output. If a value of -1 is returned, this will indicate that the task has been completed, and task execution will end. Note that a user-defined block-selection function will be run on each trial to determine if the a new block should be chosen. A block-selection function is useful, for example, when behavior must reach a certain threshold before allowing the next block to proceed.
  • Condition-Selection Function: The name of the m-file containing the user-defined condition-selection function, if applicable. This function must be located in the experiment's base directory. This function is expected to return the condition number to be played next. Returning -1 indicates that this block is complete and a new block should be chosen according to the method selected above. This function, like all user-provided functions, has access to the TrialRecord structure, which provides information about the subject's performance, conditions- and blocks-played, thus far.
  • Block-Change Function: The name of the m-file containing the user-created block-selection function, if applicable. This function must be located in the experiment's base directory. This function, if specified and Blocks are set to be selected in a "user-defined" fashion, is called after the completion of each block, and is passed the TrialRecord structure. Your function should return the number of the new block to run (simple scalar value). This function is called when a block is determined to be complete based upon the parameters set above (e.g., number of trials to run within each block). In order to prescribe when a block should change from within an m-file, use the "Block-Change Function" described next. Note: if the Block-Selection Function is set to the same file as the Block-Change Function (see below), this indicates that the Block-Change Function returns not simply a block-switch flag, but actually determines the next block to be run (i.e., a non-zero flag indicates that a block-switch should occur, and the value of this flag is itself the number of the next block to be played).
  • Block-Change Function: This user-created function, if specified, is called after every trial to determine whether a new block should be initiated. It is passed the TrialRecord structure, and should return a value of "1" to change blocks, or "0" to continue the current block. The next block will be selected in the usual manner, according to the options described above. However: if the Block-Selection Function (above) is set to the same file as the Block-Change Function, this indicates that the Block-Change Function returns not simply a block-switch flag, but actually determines the next block to be run (e.g., return "3" to switch to running the third block). This feature allows one m-file to control both when a block switches and which block is selected next.
  • Inter-Trial Interval (ITI): Enter the desired inter-trial interval (in milliseconds). After house-keeping operations and the preparation of stimuli for the upcoming trial, a timer will subtract the used time and wait to initiate a new trial until the specified ITI time has elapsed. Note, however, that the actual ITI may be longer than this value if the chosen ITI is too short (less than a few hundred milliseconds, in most cases), such that these house-keeping and stimulus preparation events have not yet completed. Specifically, several hundred milliseconds are reqiured between trials in order to load / generate images and store them in video RAM, as well as to write data to the behavioral (.bhv2) file and to update stats on the control screen. The delay will be longer with more or larger stimuli to process, and is variable in exact length. If the selected ITI (as entered in the main menu) is very short (e.g., under a few hundred milliseconds) and there are many or large stimuli to be processed, the actual ITI might exceed the desired time. If this happens, a warning will be displayed.
  • Load settings: Allows one to load the settings from a configuration file associated with a different conditions file from the one currently selected.
  • Save settings: Saves all the options (except data file name) as currently set in a configuration file (named as the conditions file but with the suffix "_cfg.mat"). These options will then be re-loaded automatically each time that conditions file is selected.
  • Location : as the name implies, pressing this button will open a window where the settings file is located.
  • Alerts On/Off : This button will toggle the remote alerts feature and allows setting the type of alert (brief text alert vs web page update) depending on the type of alert function selected.

Input / Output Submenu

The I/O submenu is used to make assignments between channels and lines on the DAQ card and specific MonkeyLogic2 functions, such as eye-signal tracking, behavioral codes digital output, and reward delivery. In addition, the settings for signal-calibration and eye-drift correction can be accessed here.

An I/O assigment is made by selecting that signal in the scroll list near the middle of this panel and selecting the appropriate board-subysystem-channel/line in the upper three boxes, then pressing the "assign" button. See below for specific information on the I/O menu options. Also refer to the I/O Details page for more comprehensive information about making I/O assignments and the guidelines which should be followed.

I/O Assignments

  • Signal Type : This is a list of the types of signals we wish to measure and work with, i.e., eye tracking or joystick input. You must assign a signal to an I/O boards appropriate subsystem and channel. This allows for very flexible usage of all the board's capabitlies and at the same time allow for dynamic mapping any signal to any board.
  • I/O Boards: This listbox displays the DAQ boards found on the current system. If you board is not display, something might be wrong with it. First check to make sure National Instruments Measurement and Automation Explorer can see it.
  • Subsystem: This listbox shows the available subsystems on the selected board. These are usually of the type: Analog Input, Analog Output, and Digital In/Out. MonkeyLogic2 automatically populates this list based on the signal type selected, i.e. eyeX is an analoginput, while a stimulus1 is an analog output. This helps prevent mapping errors.
  • Channels / Ports: The assigned numbers of the available channels (on an analog subsystem) or ports (on a digital subsystem) are displayed. The number of lines available on a given digital port, and whether those ports are input, output, or user-configurable, depend on the specific hardware being used. Please see the daq device page for help.
  • Assign/Clear buttons: After selecting the appropriate signal, I/O board, subsystem, and channel/port, you must click the assign button to connect them. MonkeyLogic2 will update the list boxes to display the remaining available channels/ports. You can also clear assignments.

The below table shows the appropriate subsystem type that corresponds with a signal type. MonkeyLogic2 will automatically perform this lookup and populate the appropriate list boxes. Therefore, it is no longer necessary to "Check" an assignment. This table is provided for reference only.

Eye Signal X and Y Analog Inputs
Joystick X and Y Analog Inputs
Buttons & Levers Analog or Digital Inputs
Reward Analog Output or Digital
Digital Codes (for event markers) (n) digital lines to be chosen from among those available on the selected port
Digital Codes Strobe One digital line to be chosen from among those available on the selected port
Stimulation Analog Outputs


  • Non-DAQ devices: These are input devices that connect to MonkeyLogic digitally (USB, Network, etc.)
    • Digital Touch Screens, Joysticks and Eye Trackers should be configured here.

  • I/O Test : This button will pull up a new window which will either produce a signal (sine wave for analog output or square wave for digital out) or show the voltages on the selected channel of the selected subsystem of the selected board.
  • Analog Input Sample Rate: The frequency at which to acquire analog data (samples per second).
  • Analog Input Configuration : Select the input type which corresponds to the manner in which analog inputs are connected ("Differential", "Single Ended", or "NonReferencedSignleEnded").
  • Analog Input smooth : this is a simple way to condition the signal in order to remove noise artifacts. It is off by default.
  • Strobe : Parameters for controling the Bit Trigger-Edge (i.e., event markers) which can use either a rising or falling bit, depending on the configuration of the acquisition hardware (e.g., the Plexon "MAP" system and standard parallel ports trigger on the falling edge, whereas the Cyberkinetics "neuroport" system triggers on the rising edge).
  • Reward : always you to globally set all the essential reward properties so that each time GoodMonkey() is called it's not necessary to repeat the same parameters.

Signal Calibration Settings

  • Eye Calibration: Choose from the following:
    • Raw Data - no manipulations at all.
    • 2D Calibration (affine transformation which typically requires looking at 5 or 9 locations on the stimulus display)
    • Offset/gain control (look at center of the screen to find the midpoint, and then increase/decrease gain for the H/V components of the eye). This is a faster but cruder form of calibration that assumes the signal is linear.
  • Calibrate Eye : appears only if the "2-D Spatial Transformation" or "Origin & Gain" option is chosen. This will open a control and stimulus window to initiate the corresponding calibration routine.
  • Import Eye Cal(ibration): Loads a previously created eye-signal transformation matrix from any configuration file.
  • Auto drift correction : whenever the task requires the subject to hold fixation, the position of the fixation target and the real position of the eye are compared. Then calibration matrix is translated toward the real eye position according to the proportion that is set on the menu.
  • Joy Calibration : works essentially the same as eye calibration, but does not offer a drift correction