Getting Started

a. Obtaining NIMH MonkeyLogic

b. Software Installation

    You can use either a MATLAB app installer or a ZIP file.

    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, you can 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 like the following.

      >> 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 that you choose and add the directory to the MATLAB path. You can add the subdirectories as well, but it 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 you to install them if they are not found.

      For the VS2013 Redistributable, you need to 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, you will be asked 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) 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, whichever file you run. 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 you can safely delete it for upgrades, if you don't create any file there.

c. Starting NIMH MonkeyLogic

    Click the [NIMH MonkeyLogic] icon on the MATLAB APPS menu (if you installed with the MATLAB app installer) or type "monkeylogic" on the MATLAB command window (if you installed with the ZIP file), depending on your installation method.

    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.

    You can 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, like the following.

    • 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 most recommended. 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. MAT has a problem that it gets slower as more and more variables are stored, even though the 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 they are recorded in one single trial. This function is 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(__);

    If you saved file-source stimuli in the data file, you can retrieve them with the mlexportstim function.

    mlexportstim(destination_path, datafile);

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.