-------------------------------------------------------------------------------------
Searchmight Toolbox - contains code and third-party packages that my code depends on.
( (c) Francisco Pereira 2001-2010 (fpereira@princeton.edu)
and owners of these packages:

- LIBSVM
- CVX
- repmat and mexutil from Tom Minka's lightspeed toolbox

as described on their respective copyright notices )
-------------------------------------------------------------------------------------

--------------------------------------------------------------------
Installation
--------------------------------------------------------------------

We have tried to pre-compile everything for any architecture we distribute, this section is just to make sure everything is in place and works in your machine. 1) can likely be skipped even if there are problems but 2) you do have to check.

1) build various MEX files that are necessary, by typing

make

from the UNIX command line.
If running on OS X, you'll need Xcode installed in order to have make. You also
need to make sure that the MATLAB mex compiler is in the path
(type "which mex" and hopefully the path for the MATLAB bin directory appears).
If "which mex" does not return a path, you have to find out where MATLAB lives.
Type

which matlab

which will give you a path <path> to a symbolic link and then

ls -l <path>

to see where that symbolic link points to (a bin directory inside a MATLAB directory).
This directory must be in the path, as that is where mex resides.


2) This toolbox depends on some functions of CoreToolbox, which is automatically
checked out as a subdirectory of this one. Most of these are already
included via symlinks but a few others depend on external packages that
need to be built for each machine type/OS combination.

In order to check that that is the case, start MATLAB and type
(use an absolute path, please)

addpath('/path/to/where/you/put/SearchmightToolbox.<architecture>.<version>');
setupPathsSearchmightToolbox

this will set up paths to all the OS specific directories. 
This sequence of path commands needs to be called once when you start MATLAB
(put it in your startup.m file if you don't want to have to type it every time)
or at the beginning of a script if that is what you are passing the MATLAB interpreter.
Now we are doing it to be able to call one of the internal functions

checkExternalPackages

If this completes without errors, you are ready to go and can skip to the Usage section below.

If not, you'll have to build CoreToolbox for your architecture. You have two options: get fpereira an
account in your machine he can ssh into to build (recommended), or keep reading this
section and try to do it yourself (commended, but there may be pain:)

Please go to the CoreToolbox/ExternalPackages subdirectory and call

buildExternalPackages.pl

from the UNIX command line to prepare everything. The README in that
directory has more details, if necessary.

--------------------------------------------------------------------
Usage
--------------------------------------------------------------------

The main function is 

 computeInformationMap

which computes an information map based on cross-validated classification
accuracy at each voxel or a region around it, together with a p-value map.

In order to use this, you will have to read

 README.datapreparation.txt

in order to transform your dataset into a format Searchmight can use. This
is fairly straightforward, at least judging by the reaction of beta testers,
and should actually lower your memory footprint relative to working directly
with a AFNI/Analyze/NIfTI file. It also precomputes spatial relationships
between voxels, which speeds up computation considerably.

Once you are done with data preparation (or if you'd rather just try this out
immediately), look at

  demo.m

which contains MATLAB code for producing a small synthetic dataset and examples
of how to call the code for various types of classifier. It also shows how to
plot the resulting maps and how to obtain searchlight-level information.
Please don't run that function directly, as it's meant to facilitate cut-and-paste.

The demo has only the most basic features of the code at present, but will be
expanded soon.

There is a second demo

  demoFromMVPA.m

which converts the tutorial_easy.m dataset from the MVPA toolbox into our format,
trains a classifier and plots the results.
