Setup

Princeton multi-voxel pattern analysis setup and installation guide

Before you begin

Compatibility and requirements

Almost all of the testing for the toolbox has been using Matlab R14 (version 7) on Linux and Mac OS X, though we don't anticipate any major roadblocks getting things to work on other operating systems. One user has reported that a few minor tweaks are necessary to get things working for version 6.5, and so we advise using version 7 wherever possible. Currently, none of the scripts require the Java Virtual Machine. Please contact us if you notice any compatibility issues.

Update: Keith Bartley has written OctaveMVPA, a port to Octave (for those without Matlab licenses).

The default ANOVA and zscoring functionality require the Matlab Stats toolbox, although home-grown alternatives have been provided instead for your use. Likewise, the default backpropagation classifier needs the Neural Networks toolbox, but we have bundled the Netlab open source toolbox that you can use instead. See the 'Mathworks toolboxes' and 'External bundled packages' in the Manual for more information.

Downloading the toolbox

The latest version can always be found at:

https://github.com/PrincetonUniversity/princeton-mvpa-toolbox

See the contact details in the Manual for more information about mailing lists.

There are two parts to download: the scripts and the sample dataset. You only really need the sample dataset if you want to try running through the tutorial (highly recommended).

Installation

Unpack the toolbox scripts

Clone or download & unzip the princeton-mvpa-toolbox GitHub repository.

This will create various directories:

1. afni_matlab, for importing from AFNI
2. bv2mat, for importing from BrainVoyager
3. core, the main toolbox scripts
4. netlab, for neural networks classification, if you don't have the Matlab Neural Networks toolbox
5. progress, changelogs, planned improvements etc. ' no actual functionality here
6. montage kas, scripts by Keith Schneider for making montage views of fMRI data

core is the one with all the toolbox scripts. See 'What is the toolbox_ in the ["MVPA manual"] for more detailed information about the other directories.

Unpack the sample dataset

You're also going to need to store a copy of the sample dataset files: just unpack the afni_set.tar.gz file as before, and it should create a tutorial_easy directory containing some AFNI .BRIK, .HEAD and Matlab .mat files. Alternatively you can use the nifti_set or analyze_set to run tutorial_easy_spm for those file formats.

Set the Matlab paths

Now you need to set your paths, so that when you run matlab, it will know about the toolbox m-files. One easy way is create a startup.m in ~/matlab that Matlab will run every time it opens, and add the addpath command to that.

Note: if you don't have a ~/matlab directory, just create one first.

Note for Windows users: I'm not sure what the Windows equivalent of ~/matlab is. Try something like c:\matlab\work, or _c:\program files\matlab_ or My Documents ' let me know which works.

A sample startup.m would look like this:

addpath ~/mvpa 

mvpa_add_paths;

Test that this is working by running Matlab while in another directory. Type:

>> help tutorial_easy 

[SUBJ RESULTS] = TUTORIAL_EASY() 

This is the sample script for the Haxby et al. (Science, 2001) 8-categories study. See the accompanying tutorial_easy.htm

If you see the above, you're in good shape. If not, your paths haven't been set correctly.

Compile C-Language .MEX files

N.B. We bundle a few already-compiled versions of the compute_xcorr mex file in the toolbox now, so you probably won't need to worry about compiling it yourself - in that case, you can skip this section.

Several of the more advanced features of the toolbox involving the computation of statistical maps using a correlation function. If you want to speed up the computeation of cross correlation statistical maps (and you most certainly do, we can assure you), you can compile the C-language version of the statmap_xcorr.m function. To do this, first start Matlab, and switch to your mvpa directory that contains the core MVPA scripts. Then enter the following command:

>> mex compute_xcorr.c

One of two things should happen. You should get output that looks vaguely like this:

compute_xcorr.c: In function `mexFunction':
compute_xcorr.c:123: warning: assignment discards qualifiers from pointer target type
compute_xcorr.c:124: warning: assignment discards qualifiers from pointer target type

Or, Matlab might complain that you don't have a default compiler selected. If this is the case, follow the directions from the Matlab documentation here to select a compiler, or simply select the gcc compiler if it's available. Then run the mex compute_xcorr.c command again, and you should get the desired output above.

A Few Articles on Using and Troubleshooting Mex

• Mathworks Mex Files Guide, including basic troubleshooting
• Matlab Article for configuring Mex
• Matlab Article for using Mex to run C and Fortran programs
• Matlab Article for using debuggers with Mex files
• An article detailing a simple Step-by-Step process for creating a Mex file

Start your engines

Ok, we're ready to go. Change directory to where your sample data was stored and run matlab. Then, follow the instructions in the tutorial.

Things are still in a state of flux, and we expect to be finding and fixing bugs for a little bit longer. To minimize your own and others' suffering, we ask that you let us know as soon as possible if you've found any serious bugs. Also, please contact [email protected] to be added to our mailing list so that we can let you know of any major new releases or bugfixes.

Good luck.