3dsvm


Program: 3dsvm

+++++++++++ 3dsvm: support vector machine analysis of brain data  +++++++++++

3dsvm - temporally predictive modeling with the support vector machine

   This program provides the ability to perform support vector machine
   (SVM) learning on AFNI datasets using the SVM-light package (version 5)
   developed by Thorsten Joachims (http://svmlight.joachims.org/).

-----------------------------------------------------------------------------
Usage:
------
     3dsvm [options]

Examples:
---------
1. Training: basic options require a training run, category (class) labels
   for each timepoint, and an output model. In general, it usually makes
   sense to include a mask file to exclude at least non-brain voxels

     3dsvm -trainvol run1+orig \
           -trainlabels run1_categories.1D \
           -mask mask+orig \
           -model model_run1

2. Training: obtain model alphas (a_run1.1D) and
   model weights (fim: run1_fim+orig)

     3dsvm -alpha a_run1 \
           -trainvol run1+orig \
           -trainlabels run1_categories.1D \
           -mask mask+orig \
           -model model_run1
           -bucket run1_fim

3. Training: exclude some time points using a censor file

     3dsvm -alpha a_run1 \
           -trainvol run1+orig \
           -trainlabels run1_categories.1D \
           -censor censor.1D \
           -mask mask+orig \
           -model model_run1
           -bucket run1_fim

4. Training: control svm model complexity (C value)

     3dsvm -c 100.0 \
           -alpha a_run1 \
           -trainvol run1+orig \
           -trainlabels run1_categories.1D \
           -censor censor.1D \
           -mask mask+orig \
           -model model_run1
           -bucket run1_fim

5. Training: using a kernel

     3dsvm -c 100.0 \
           -kernel polynomial -d 2 \
           -alpha a_run1 \
           -trainvol run1+orig \
           -trainlabels run1_categories.1D \
           -censor censor.1D \
           -mask mask+orig \
           -model model_run1

6. Training: using regression

     3dsvm -type regression \
           -c 100.0 \
           -e 0.001 \
           -alpha a_run1 \
           -trainvol run1+orig \
           -trainlabels run1_categories.1D \
           -censor censor.1D \
           -mask mask+orig \
           -model model_run1

7. Testing: basic options require a testing run, a model, and an output
   predictions file

     3dsvm -testvol run2+orig \
           -model model_run1+orig \
           -predictions pred2_model1

8. Testing: compare predictions with 'truth'

     3dsvm -testvol run2+orig \
           -model model_run1+orig \
           -testlabels run2_categories.1D \
           -predictions pred2_model1

9. Testing: use -classout to output integer thresholded class predictions
   (rather than continuous valued output)

     3dsvm -classout \
           -testvol run2+orig \
           -model model_run1+orig \
           -testlabels run2_categories.1D \
           -predictions pred2_model1


options:
--------

------------------- TRAINING OPTIONS -------------------------------------------
-type tname            Specify tname:

                             classification [default]
                             regression

                       to select between classification or regression.

-trainvol trnname      A 3D+t AFNI brik dataset to be used for training.

-mask mname            Specify a mask dataset to only perform the analysis
                       on non-zero mask voxels.
                       ++ If '-mask' is not used '-nomodelmask must be
                          specified.
                       For example, a mask of the whole brain can be
                       generated by using 3dAutomask, or more specific ROIs
                       could be generated with the Draw Dataset plugin or
                       converted from a thresholded functional dataset.
                       The mask is specified during training but is also
                       considered part of the model output and is
                       automatically applied to test data.

-nomodelmask           Flag to enable the omission of a mask file. This is
                       required if '-mask' is not used.

-trainlabels lname     lname = filename of class category .1D labels
                       corresponding to the stimulus paradigm for the
                       training data set. The number of labels in the
                       selected file must be equal to the number of
                       time points in the training dataset. The labels
                       must be arranged in a single column, and they can
                       be any of the following values:

                              0    - class 0
                              1    - class 1
                              n    - class n (where n is a positive integer)
                              9999 - censor this point

                       See also -censor.

-censor cname          Specify a .1D censor file that allows the user
                       to ignore certain samples in the training data.
                       To ignore a specific sample, put a 0 in the
                       row corresponding to the time sample - i.e., to
                       ignore sample t, place a 0 in row t of the file.
                       All samples that are to be included for training
                       must have a 1 in the corresponding row. If no
                       censor file is specified, all samples will be used
                       for training. Note the lname file specified by
                       trainlabels can also be used to censor time points
                       (see -trainlabels).

-kernel kfunc          kfunc = string specifying type of kernel function:

                             linear     : <u,v>  [default]
                             polynomial : (s<u,v> + r)^d
                             rbf        : radial basis function
                                          exp(-gamma ||u-v||^2)
                             sigmoid    : tanh(s <u,v> + r))

                       note: kernel parameters use SVM-light syntax:

                             -d int     : d parameter in polyniomial kernel
                                            3 [default]
                             -g float   : gamma parameter in rbf kernel
                                            1.0 [default]
                             -s float   : s parameter in sigmoid/poly kernel
                                            1.0 [default]
                             -r float   : r parameter in sigmoid/poly kernel
                                            1.0 [default]

-max_iterations int    Specify the maximum number of iterations for the
                       optimization. 1 million [default].

-alpha aname           Write the alphas to aname.1D

-wout                  Flag to output sum of weighted linear support
                       vectors to the bucket file. This is one means of
                       generating an "activation map" from linear kernel
                       SVMs see (LaConte et al., 2005). NOTE: this is
                       currently not required since it is the only output
                       option.

-bucket bprefix        Currently only outputs the sum of weighted linear
                       support vectors written out to a functional (fim)
                       brik file. This is one means of generating an
                       "activation map" from linear kernel SVMS
                       (see LaConte et al, 2005).

------------------- TRAINING AND TESTING MUST SPECIFY MODNAME ------------------
-model modname         modname = basename for the model brik.

                       Training: modname is the basename for the output
                       brik containing the SVM model

                           3dsvm -trainvol run1+orig \
                                 -trainlabels run1_categories.1D \
                                 -mask mask+orig \
                                 -model model_run1

                       Testing: modname is the name for the input brik
                       containing the SVM model.

                           3dsvm -testvol run2+orig \
                                 -model model_run1+orig  \
                                 -predictions pred2_model1

-nomodelfile           Flag to enable the omission of a model file. This is
                       required if '-model' is not used during training.
                       ** Be careful, you might not be able to perform testing!

------------------- TESTING OPTIONS --------------------------------------------
-testvol tstname       A 3D or 3D+t AFNI brik dataset to be used for testing.
                       A major assumption is that the training and testing
                       volumes are aligned, and that voxels are of same number,
                       volume, etc.

-predictions pname     pname = basename for .1D prediction file(s).
                       Prediction files contain a single column, where each line
                       holds the predicted value for the corresponding volume in
                       the test dataset. By default, the predicted values take
                       on a continuous range; to output integer-valued class
                       decision values use the -classout flag.
                       For classification: Values below 0.5 correspond to
                       (class A) and values above 0.5 to (class B), where A < B.
                       For more than two classes a separate prediction file for
                       each possible pair of training classes and one additional
                       "overall" file containing the predicted (integer-valued)
                       class membership is generated.
                       For regression: Each value is the predicted parametric rate
                       for the corresponding volume in the test dataset.

-classout              Flag to specify that pname files should be integer-
                       valued, corresponding to class category decisions.

-nopredcensored        Do not write predicted values for censored time-points
                       to predictions file.

-nodetrend             Flag to specify that pname files should NOT be
                       linearly detrended (detrending is performed by default).
                       ** Set this options if you are using GLM beta maps as
                          input for example. Temporal detrending only
                          makes sense if you are using time-dependent
                          data (chronological order!) as input.

-nopredscale           Do not scale predictions. If used, values below 0.0
                       correspond to (class A) and values above 0.0 to
                       (class B).

-testlabels tlname     tlname = filename of 'true' class category .1D labels
                       for the test dataset. It is used to calculate the
                       prediction accuracy performance of SVM classification.
                       If this option is not specified, then performance
                       calculations are not made. Format is the same as
                       lname specified for -trainlabels.

-multiclass mctype     mctype specifies the multiclass algorithm for
                       classification. Current implementations use 1-vs-1
                       two-class SVM models.

                       mctype must be one of the following:

                             DAG   :  Directed Acyclic Graph [default]
                             vote  :  Max Wins from votes of all 1-vs-1 models

                       see https://lacontelab.org/3dsvm.htm for details and
                       references.

------------------- INFORMATION OPTIONS ---------------------------------------
-help                  this help

-version               print version history including rough description
                       of changes




-------------------- SVM-light learn help -----------------------------

SVM-light V5.00: Support Vector Machine, learning module     30.06.02stim

Copyright: Thorsten Joachims, thorsten@ls8.cs.uni-dortmund.de

This software is available for non-commercial use only. It must not
be modified and distributed without prior permission of the author.
The author is not responsible for implications from the use of this
software.

   usage: svm_learn [options] example_file model_file

Arguments:
         example_file-> file with training data
         model_file  -> file to store learned decision rule in
General options:
         -?          -> this help
         -v [0..3]   -> level (default 1)
Learning options:
         -z {c,r,p}  -> select between classification (c), regression (r),
                        and preference ranking (p) (default classification)
         -c float    -> C: trade-off between training error
                        and margin (default [avg. x*x]^-1)
         -w [0..]    -> epsilon width of tube for regression
                        (default 0.1)
         -j float    -> Cost: cost-factor, by which training errors on
                        positive examples outweigh errors on negative
                        examples (default 1) (see [4])
         -b [0,1]    -> use biased hyperplane (i.e. x*w+b>0) instead
                        of unbiased hyperplane (i.e. x*w>0) (default 1)
         -i [0,1]    -> remove inconsistent training examples
                        and retrain (default 0)
Performance estimation options:
         -x [0,1]    -> compute leave-one-out estimates (default 0)
                        (see [5])
         -o ]0..2]   -> value of rho for XiAlpha-estimator and for pruning
                        leave-one-out computation (default 1.0) (see [2])
         -k [0..100] -> search depth for extended XiAlpha-estimator
                        (default 0)
Transduction options (see [3]):
         -p [0..1]   -> fraction of unlabeled examples to be classified
                        into the positive class (default is the ratio of
                        positive and negative examples in the training data)
Kernel options:
         -t int      -> type of kernel function:
                        0: linear (default)
                        1: polynomial (s a*b+c)^d
                        2: radial basis function exp(-gamma ||a-b||^2)
                        3: sigmoid tanh(s a*b + c)
                        4: user defined kernel from kernel.h
         -d int      -> parameter d in polynomial kernel
         -g float    -> parameter gamma in rbf kernel
         -s float    -> parameter s in sigmoid/poly kernel
         -r float    -> parameter c in sigmoid/poly kernel
         -u string   -> parameter of user defined kernel
Optimization options (see [1]):
         -q [2..]    -> maximum size of QP-subproblems (default 10)
         -n [2..q]   -> number of new variables entering the working set
                        in each iteration (default n = q). Set n<q to prevent
                        zig-zagging.
         -m [5..]    -> size of cache for kernel evaluations in MB (default 40)
                        The larger the faster...
         -e float    -> eps: Allow that error for termination criterion
                        [y [w*x+b] - 1] >= eps (default 0.001)
         -h [5..]    -> number of iterations a variable needs to be
                        optimal before considered for shrinking (default 100)
         -f [0,1]    -> do final optimality check for variables removed
                        by shrinking. Although this test is usually
                        positive, there is no guarantee that the optimum
                        was found if the test is omitted. (default 1)
Output options:
         -l string   -> file to write predicted labels of unlabeled
                        examples into after transductive learning
         -a string   -> write all alphas to this file after learning
                        (in the same order as in the training set)

More details in:
[1] T. Joachims, Making Large-Scale SVM Learning Practical. Advances in
    Kernel Methods - Support Vector Learning, B. Schoelkopf and C. Burges and
    A. Smola (ed.), MIT Press, 1999.
[2] T. Joachims, Estimating the Generalization performance of an SVM
    Efficiently. International Conference on Machine Learning (ICML), 2000.
[3] T. Joachims, Transductive Inference for Text Classification using Support
    Vector Machines. International Conference on Machine Learning (ICML),
    1999.
[4] K. Morik, P. Brockhausen, and T. Joachims, Combining statistical learning
    with a knowledge-based approach - A case study in intensive care
    monitoring. International Conference on Machine Learning (ICML), 1999.
[5] T. Joachims, Learning to Classify Text Using Support Vector
    Machines: Methods, Theory, and Algorithms. Dissertation, Kluwer,
    2002.



-------------------- SVM-light classify help -----------------------------

SVM-light V5.00: Support Vector Machine, classification module     30.06.02

Copyright: Thorsten Joachims, thorsten@ls8.cs.uni-dortmund.de

This software is available for non-commercial use only. It must not
be modified and distributed without prior permission of the author.
The author is not responsible for implications from the use of this
software.

   usage: svm_classify [options] example_file model_file output_file

options: -h         -> this help
         -v [0..3]  -> verbosity level (default 2)
         -f [0,1]   -> 0: old output format of V1.0
                    -> 1: output the value of decision function (default)



--------------------------------------------------------------------------
Significant programming contributions by:

  Jeff W. Prescott, William A. Curtis, Ziad Saad, Rick Reynolds,
  R. Cameron Craddock, Jonathan M. Lisinski, and  Stephen M. LaConte

Original version written by JP and SL, August 2006
Released to general public, July 2007

Questions/Comments/Bugs - email slaconte@vtc.vt.edu


Reference:
LaConte, S., Strother, S., Cherkassky, V. and Hu, X. 2005. Support vector
    machines for temporal classification of block design fMRI data.
    NeuroImage, 26, 317-329.

Specific to real-time fMRI:
S. M. LaConte. (2011). Decoding fMRI brain states in real-time.
    NeuroImage, 56:440-54.
S. M. LaConte, S. J. Peltier, and X. P. Hu. (2007). Real-time fMRI using
brain-state classification. Hum Brain Mapp, 208:1033–1044.

Please also consider to reference:
T. Joachims, Making Large-Scale SVM Learning Practical.
     Advances in Kernel Methods - Support Vector Learning,
     B. Schoelkopf and C. Burges and A. Smola (ed.), MIT Press, 1999.

RW Cox. AFNI: Software for analysis and visualization of
    functional magnetic resonance neuroimages.
    Computers and Biomedical Research, 29:162-173, 1996.