Getting Started

a. Obtaining NIMH MonkeyLogic

b. Software Installation

    Either a MATLAB app installer or a ZIP file can be used for installation.

    i. Using a MATLAB app installer (R2012a or later)

      Double-click the downloaded *.mlappinstall file. It will open MATLAB and pop up a question dialog as below (left figure). Click the [Install] button and NIMH ML will be added to the MATLAB menu (arrow on the right figure). If this process fails for any reason, manually open MATLAB and install the package by clicking the [Install App] menu (circle on the right figure).

      The app installation path is different from MATLAB version to version and can be checked with the following commands.

      >> files = matlab.apputil.getInstalledAppInfo;
      >> files.location

      ans =

      'C:\Users\USERNAME\AppData\Roaming\MathWorks\MATLAB Add-Ons\Apps\NIMHMonkeyLogic2'

    ii. Using a ZIP file

      Decompress the zip file to a directory and add that directory to the MATLAB path. The subdirectories can be added, but that step is not necessary.

    iii. Installing additional libraries

      NIMH ML requires two libraries distributed for free by Microsoft: 1) Visual C++ Redistributable Packages for Visual Studio 2013 and 2) DirectX End-User Runtimes. NIMH ML tries to detect these libraries during initialization and will ask to install them if they are not found.

      For the VS2013 Redistributable, install vcredist_x64.exe, if you have a 64-bit MATLAB, and vcredist_x86.exe, if it is a 32-bit MATLAB. vcredist_arm.exe is not needed.

      If you have a parallel port, NIMH ML will ask to install Inpout32, an open source parallel port driver. To install it, run inpout32_installer.exe (for 32-bit Windows) or inpoutx64_installer.exe (for 64-bit Windows). These files are in the daqtoolbox directory of the NIMH ML installation path. The installation occurs instantly and there is no wizard window showing up. Both 32-bit and 64-bit drivers are installed together, irrespective of which installer is chosen. The admin privilege is required.

    iv. A tip for future upgrades

      Keep your task files separately outside of the NIMH ML installation directory. NIMH ML does not store anything in its main directory, so deleting the main directory is safe if your files are stored elsewhere.

c. Starting NIMH MonkeyLogic

    Click the [NIMH MonkeyLogic] icon on the MATLAB APPS menu (if NIMH ML was installed with the MATLAB app installer) or type "monkeylogic" on the MATLAB command window (if it was installed with the ZIP file).

    NIMH ML comes with many example tasks (see the "task" directory in the NIMH ML installation path). To start a task, choose a conditions file by clicking the [Load a conditions file] button on the ML GUI (left figure below) and then hit the [Run] button.

    It is possible run a task without a DAQ board or any input device, by activating the simulation mode in the pause menu. In the simulation mode, most input signals are replaced with mouse and key inputs shown here.

    • Eye #1: Mouse cursor
    • Eye #2: 'I', 'K', 'J', 'L'
    • Joystick #1: Arrow keys (↑, ↓, ←, →)
    • Joystick #2: 'W', 'S', 'A', 'D'
    • Touch: Mouse left click & right click
    • Buttons: '1', '2', '3', '4', '5', '6', '7', '8', '9', '0'

    For more information about how to run tasks, see "Running a Task".

d. File Formats Supported by NIMH MonkeyLogic

    NIMH ML supports its own data file format, called BHV2 (*.bhv2), as well as HDF5 (*.h5) and MAT (*.mat). BHV2 is a private format that is based on a simple recursive algorithm (see "BHV2 Binary Structure" in the appendix). It provides decent read and write performance and is recommended for most users. HDF5 is supported by many commercial and non-commercial software platforms, including Java, MATLAB, Scilab, Octave, Mathematica, IDL, Python, R and Julia, but its read performance in MATLAB is a bit disappointing. MAT is MATLAB’s native data format. NIMH ML uses the default MAT-file format that is set in the MATLAB Preferences. The MAT file format has a weakness in that it gets slower as more and more variables are stored, even though file compression is disabled.

    The mlread function provides a unified read interface for all the formats. It returns trial-by-trial data in a 1-by-n struct array.

    data = mlread;
    data = mlread(filename);
    [data, MLConfig, TrialRecord, filename] = mlread(__);

    The mlconcatenate function combines trial-by-trial analog data into one large seamless matrix and adjusts all timestamps accordingly, as if the data were recorded in one single trial. This function is especially useful for reading data files in which signals were continuously recorded through inter-trial intervals.

    data = mlconcatenate;
    data = mlconcatenate(filename);
    [data, MLConfig, TrialRecord, filename] = mlconcatenate(__);

    Some recorded signals, such as High Frequency, Voice or Webcam, have a large size and loading them all at once may cause an out-of-memory error. Those signals are stored as separate variables and not processed by mlread nor mlconcatenate. To read those data, use the mlreadsignal function.

    signal = mlreadsignal(signal_type);  % 'high1', 'voice', 'cam2', etc.
    signal = mlreadsignal(signal_type, trial_num);
    signal = mlreadsignal(signal_type, trial_num, filename);
    [video, timestamp] = mlreadsignal('webcam1',__);  % 'webcam' + cam#

    Saved file-source stimuli in the data file can be retrieved them with the mlexportstim function.

    mlexportstim(destination_path, datafile);

e. Aligning Timestamps and Analog Data

    In NIMH ML, a trial starts at Time 0 and so does data acquisition. Therefore, matrix indices to address analog data for a particular period can be calculated from the time of the period. For example, to get eye traces for an epoch marked by Eventcodes 10 and 20, write a script as below.

    data = mlread;  % read a data file
    trial_no = 1;
    code = data(trial_no).BehavioralCodes.CodeNumbers;
    time = data(trial_no).BehavioralCodes.CodeTimes;
    eye = data(trial_no).AnalogData.Eye;

    start_time = time(find(10==code,1));  % time is in milliseconds.
    end_time = time(find(20==code,1));

    start_index = round(start_time) + 1;  % data is sampled at 1 kHz.
    end_index = round(end_time) + 1;

    segment = eye(start_index:end_index,:);

    NIMH ML uses Eventcodes 9 (Start trial) and 18 (End trial) to mark the boundaries of a trial in the neural data stream. Note that the timestamps of those codes are just the times that the codes were sent to the neural recording system and not the actual start time and end time of a trial, depite the code labels. To get precise trial intervals, use the AbsoluteTrialStartTime field.

The National Institute of Mental Health (NIMH) is part of the National Institutes of Health (NIH), a component of the U.S. Department of Health and Human Services.