Skip to content

Laboratory of Neuropsychology

Main Menu

Logo & Load/Save Settings

MonkeyLogic load/save settings screen

  • Three monkeys logo: Opens the NIMH MonkeyLogic homepage.
  • Collapse/Expand menu button (at the top-right corner of the logo): Hides/shows submenus (Video, Input/Output and Task). The collapsed menu is useful when running NIMH MonkeyLogic on a small screen.
  • [Locate] config button: Opens 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. Note that "# of trials to run in this block", "Count correct trials only", "Blocks to run", "First block to run" and "Subject name" are not overwritten, if the settings are loaded in this way. See "Subject name" in the "Conditions File & Run Button" menu section

MonkeyLogic screen to save settings

  • Save settings: Stores the current settings to the config file (*_cfg2.mat). The button is activated only when there is something changed. If any change is about to be overwritten without being saved, a file save dialog will pop up. The current config is saved without asking, when the 'RUN' button is clicked.

Conditions File & Run Button

MonkeyLogic screen for conditions file and run button

  • [Load conditions file] button ("To start, load ..."): Opens a conditions/userloop file (i.e., load an experiment).
    • [Help] button: Opens the conditions file manual.
    • [Edit] button: Opens the current conditions file in the text editor. The conditions file should be reloaded after edits have been completed.
  • [Stimulus list] pane: Shows 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: Displays the stimulus selected in the [stimulus list] pane.
    • [Test] button: Displays/plays 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: Displays 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 correct trials only: As it states.
    • [Chart blocks] button: Opens a figure that shows which conditions appear in which blocks, such as the following one.
    • [Apply to all] button: Applies the changes to all blocks.

MonkeyLogic screen showing selected blocks to run

  • 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: Lists the timing scripts used by the current conditions file. In case that a userloop function is selected, 'user-defined' will be displayed instead. Double-clicking the timing script name will open its runtime file (or the runtime folder if the runtime file is not created yet). The runtime file is a custom MATLAB function that is created by combining the user timing script and a runtime function provider (trialholder_v1.m or trialholder_v2.m) when the RUN button is hit. What ML runs to start the task is this runtime file, not the timing script itself.
    • [Help] button: Opens the timing script manual.
    • [Edit] button: Opens 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.
    • 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.
    • 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.
  • 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.
  • Save stimuli: When this option is checked, stimuli used during the task are saved in the date file. All stimuli created from file sources will be saved. Saved stimuli can be extracted by using the mlexportstim function.
  • [RUN] button: Activated when a task is loaded. Upon its being clicked, the current configuration is automatically saved and the task begins.


MonkeyLogic video settings screen

  • [Latency test] button: Runs a benchmarking trial.
  • Subject screen device: Lists the screens on the system.
  • [Test] button: Displays 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. Set where you want to see it on the screen. [LEFT TOP RIGHT BOTTOM] in Windows’ pixel coordinates.
  • Forced use of fallback screen: Forces 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. Applicable to the runtime version 1 only.
  • Subject screen background: Background color of the subject screen.
  • Fixation point, Eye tracer, Joystick cursor, Touch cursor: Allows you to use either an image/movie or a circle/square of given color and size for these objects.
  • Photodiode trigger: Displays black and white squares in turns at the selected location to drive the photodiode.

Input / Output

MonkeyLogic input/output settings screen

  • [Edit behave. codes] button: Opens the "codes.txt" file that lists Behavioral Code numbers of the current task with their associated descriptions. If codes.txt exists both in the ML directory and the current task directory, the one in the task directory is opened and used for the task. You can also define this code-description association in the timing script with the bhv_code command.

DAQ board settings

  • Click the panels in the order shown on the left, to map behavioral signals with DAQ channels/ports that they are connected to. If you do not have this connection information, ask someone who knows it or visually check the wire connection with the device pinout diagram.
  • Eye X &Y (and Joystick X & Y) must be assigned on the same board. Otherwise, an error message will be displayed, when starting tasks.
  • Multiple channels/ports can be assigned to Reward and Behavioral Codes. Drag on the panel or use SHIFT + CLICK and CTRL + CLICK combinations.
  • In case of digital lines, a line selection dialog will appear additionally, on clicking the [Assign] button.

Non-DAQ devices (USB, TCP/IP. etc)

  • These devices do not have an ADC (analog digital converter), but NIMH ML monitors input from them every milliseconds based on the software timer.
  • TCP/IP Eye Tracker
    • Currently Arrington Research's ViewPoint EyeTrackers and SR Research's EyeLink trackers are supported.
    • [Test] button: Test the TCP/IP connection.
    • The first two signal sources must be X & Y gaze points. The GUI may be disabled patially, to make it sure.

MonkeyLogic input/output test settings screen

  • [I/O Test] button: Starts a task that can test the assigned I/O.
  • AI sample rate: NIMH ML always acquires samples at 1 kHz, regardless of this setting. Then it skips some samples at the time of data saving, if this number is set below 1000. In this way, NIMH ML can monitor behavior with high resolution but keep the data size small.
  • AI configuration: Sets the AI ground configuration of the DAQ board. See "Analog Input Ground Configuration" in the "NI Multifunction I/O Device" menu.
  • AI online smoothing: Smooths input signals to remove noise artifacts. Applicable to the runtime version 1 only.
  • Strobe: Set whether the Behavioral Codes (event markers) will be sent on the rising-edge or falling-edge of the Strobe Bit. There is also a third option that does not require the Strobe Bit ("Send and Clear") for systems that capture the codes based on change detection.
    • [Spec] button: You can change the duration of Strobe Bit pulses. See the figure below.
    • [Test] button: Sends a test Strobe Bit.
  • Reward
    • [Args] button: Edit the reward function arguments (i.e., goodmonkey) for testing.
    • [Edit] button: Opens the current reward function. By default, it opens reward_function.m in the ML directory. If there is a file in the current task directory with the same name, the one in the task directory has a priority.
  • Reward polarity: Sets whether the reward device will be triggered on a TTL HIGH or LOW signal.
    • [Test] button: Sends out a test reward pulse.
  • Eye calibration & Joy calibration: See the "Calibrating Eye/Joystick Signals" menu.
    • [Reset] button: Clears the calibration matrix of the currently selected method.
    • [Calibrate / Re-calibrate] button: Opens the selected calibration tool.
    • [Import] calibration button: Copies the calibration matrix of the currently selected method from another configuration file.
  • Eye [Auto drift correction]: If this number is larger than 0, the positions of the fixation target and the gaze are compared at the end of each trial. If there is a difference, the calibration matrix is updated to translate the eye position toward the fixation target according to the proportion that is set here.

MonkeyLogic auto drift correction settings screen


MonkeyLogic task settings screen

  • [Alert] button: Turns on/off the alert state. If it is ON, NIMH ML calls alert_function.m when special events occur, such as task_start, block_start, trial_start, etc. See alert_function.m in the ML directory for details. You can catch those hooks in the function and make ML do special things, such as sending you a text message and starting an external device.
    • [Edit] button: Opens the alert_function.m in the ML directory. If you have a copy of this file in the task directory, the one in the task directory is used instead.
  • 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 made (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.
    • 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 ("condition-selection 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.
  • Blocks: Identical in logic to Conditions above. The User-defined option here requires a MATLAB function that takes the TrialRecord structure as input and returns a new block number ("block-selection function"). Note that the function will be run on each trial to determine if a new block should be chosen. It is useful, for example, when behavior must reach a certain threshold before allowing the next block to proceed.
  • 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).
  • During ITI,
    • Show traces: Determines whether to display used stimuli and traces of input signals on the control screen during the ITI.
    • Record signals: Determines whether to record input signals during the ITI. If this option is selected, the ITI start time is regarded as the beginning of the next trial.
  • User plot function: Name of a MATLAB function that will draw to the space normally occupied by the reaction time histogram on the control screen. Users can use this function to display results of online trial-by-trial analysis. The function is supposed to take the TrialRecord structure as input and return nothing.