COGTOOLBOX

The CogToolbox is a set of functions for MATLAB and Psychophysics Toolbox 3 for cognitive psychology experiments.

The toolbox includes some standard cognitive tasks such as cued and free recall tasks, self-paced reading, visual world eye-tracking, Likert scale questionnaires, and reading span and other working memory tasks. There are also functions for more general tasks such as selecting and verifying participant numbers, taking a screenshot of the experiment, and getting a keyboard or mouse response within a specific window of time.

Most of these functions were just written in the course of assembling our own experiments. So, they might not include particular functionality that you want or need for your own experiments. But, they may help you out, and you can always modify them for your own purposes!

Functions in the CogToolbox were written by Scott Fraundorf, Michael Diaz, Jason Finley, Molly Lewis, Kristen Tooley, Angie Isaacs, Tuan Lam, Alison Trude, Sarah Brown-Schmidt, and Laurel Brehm.

The CogToolbox is currently maintained at a GitHub repository.

DOWNLOAD & SETUP

Many of the functions in the CogToolbox rely on functions in the Psychophysics Toolbox 3 (Brainard, 1997; Kleiner, Brainard, & Pelli, 2007; Pelli, 1997). The CogToolbox will not work if you don't already have MATLAB and the Psychophysics Toolbox 3.

To use the CogToolbox:

  1. Download and install the Psychophysics Toolbox 3.
  2. Download the CogToolbox.
  3. The CogToolbox you downloaded in Step 2 comes as a ZIP file, a set of files compressed into a single file. On any modern computer, you should be able to "unzip" it (and get the full set of files) just by double-clicking on the ZIP.
  4. Put the resulting toolbox folder somewhere on your computer. (Many of the functions in the toolbox require other functions in the toolbox, so it is important to copy the entire folder.)
  5. In MATLAB, go to the Home tab.
  6. In the Environment block of that tab, choose Set Path...
  7. Click Add with Subfolders and then select the toolbox folder. This adds all of the subfolders to MATLAB. You should see them all listed in the Set Path window. (It's important to choose Add with Subfolders. If you just click Add Folder and not Add with Subfolders, MATLAB will not see all of the subfolders.)
  8. Click Save and then Close.
  9. ???
  10. Profit!

If you don't have a Home tab and an Environment block, you have an older version of MATLAB. Here are slightly different instructions that will work just fine for those versions:

  1. Download and install the Psychophysics Toolbox 3.
  2. Download the CogToolbox.
  3. The CogToolbox you downloaded in Step 2 comes as a ZIP file, a set of files compressed into a single file. On any modern computer, you should be able to "unzip" it (and get the full set of files) just by double-clicking on the ZIP.
  4. Put the resulting toolbox folder somewhere on your computer. (Many of the functions in the toolbox require other functions in the toolbox, so it is important to copy the entire folder.)
  5. In MATLAB, pull down the File menu and choose Set Path...
  6. Click Add with Subfolders and then select the toolbox folder. This adds all of the subfolders to MATLAB. You should see them all listed in the Set Path window. (It's important to choose Add with Subfolders. If you just click Add Folder and not Add with Subfolders, MATLAB will not see all of the subfolders.)
  7. Click Save and then Close.

TOOLBOX CONTENTS

Here is a full list of the functions in the CogToolbox and what they do.

For an exact description of how to use any of the functions, start MATLAB and type:

help functionname
Where functionname is the name of one of the CogToolboxfunctions, e.g.:
help makeValidPath

TROUBLESHOOTING

Q. It doesn't work / The computer crashes when I get to a particular part of my experiment / MATLAB says a particular function isn't found.

A. My experience is that the vast majority of errors with the CogToolbox stem from not having everything fully installed. First, make sure you've installed the Psychophysics Toolbox 3; it's required to use the CogToolbox! Then, make sure you've set up the entire CogToolbox following the instructions above. Trying to copy and use a single function from the CogToolbox on its own probably won't work; many of those individual functions rely on other functions in the CogToolbox and won't work in isolation.

Q. I get a JAVA error when I'm trying to install Psychophysics Toolbox.

A. When installing Psychophysics Toolbox 3, you may encounter the following caution during the installion process, especially on Macs. (If the caution pops up, it will make you press ENTER to continue, so you can't miss it!)

Running post-install routine...

Could not update the Matlab JAVA classpath.txt file due to the following error:
Error using ==> PsychtoolboxPostInstallRoutine at 456
Could not open Matlab's JAVA path definition file 'classpath.txt' for write access.

Either you have a very old Matlab version which does not support JAVA or, most
likely, you do not have sufficient access permissions for the Matlab application folder
to change the file /Applications/MATLAB_R2010a.app/toolbox/local/classpath.txt .
Please ask the system administrator to enable write-access to that file and repeat the
update procedure.
Alternatively, ask the administrator to add the following line:
/Applications/Psychtoolbox/PsychJava
to the file: /Applications/MATLAB_R2010a.app/toolbox/local/classpath.txt

If you skip this step, Psychtoolbox will still be mostly functional, 
with exception of the Java-based commands ListenChar, CharAvail, GetChar and FlushEvents
on Linux, MacOS-X and M$-Windows in Java mode. For more info see 'help PsychJavaTrouble'.

Why does this message appear, and what does it mean?

Some parts of Psychophysics Toolbox use Java. To use Java, you have to be on MATLAB's list of add-ons that can access Java. Think of it as a "guest list" of who can get into the Java club.

When you install Psychophysics Toolbox, it tries to add itself to the guest list. However, sometimes this doesn't work. The reason is that MATLAB normally doesn't permit other programs (like Psychophysics Toolbox) to alter its Java configuration.

What the error message is telling you is that that Psychophysics Toolbox wasn't able to add itself to the "guest list."

So, we have to do this manually, on our own. Fortunately, it's easy to change MATLAB's Java configuration to allow Psychophysics Toolbox to work. We just have to add Psychophysics Toolbox to the "guest list."

On Mac OS X:

  1. Open the Applications folder in Finder.
  2. Find MATLAB in this list.
  3. Control-click on MATLAB and choose Show Package Contents.
  4. Now, we're looking at MATLAB's internal files.
  5. Within this folder, navigate to the Toolbox folder and then to Local.
  6. This folder should contain a file called classpath.txt. This is the Java "guest list."
  7. Open classpath.txt.
  8. At the end of classpath.txt, add the following line on a new line of text:
    /Applications/Psychtoolbox/PsychJava
  9. Restart MATLAB and you should be fine!

I haven't yet encountered this problem on other platforms.

CITING THE TOOLBOX

If you use the CogToolbox in your research, a citation is always appreciated! You can cite the CogToolbox as follows:

The CogToolbox relies on Psychophysics Toolbox 3, so please also cite your use of the Psychophysics Toolbox. As of this writing, the instructions for citing the Psychophysics Toolbox include the following citations:

LICENSE

The CogToolbox is made available under the MIT license:

Copyright (c) 2014 Scott Fraundorf, Michael Diaz, Jason Finley, Molly Lewis, Kristen Tooley, Angie Isaacs, Tuan Lam, Alison Trude, Sarah Brown-Schmidt, and Laurel Brehm

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.