AFNI program: 3dsvm

Output of `-help`


Program: 3dsvm
Authors: Jeffery Prescott and Stephen LaConte

+++++++++++++++ 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. 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

6. Testing: compare predictions with 'truth'

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

7. 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 -------------------------------------------
-trainvol trnname A 3D+t AFNI brik dataset to be used for training.

-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

It is recommended to use a continuous set of class
labels, starting at 0. 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).

-a aname Write the alpha file generated by SVM-Light to
aname.1D
-alpha aname Same as -a option above.

-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).

-mask mname mname must be is a byte-format brik file used to
mask voxels in the analysis. 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 ommission of a mask file. If this
option is used for training, it must also be used
for testing.

------------------- TRAINING AND TESTING MUST SPECIFY MODNAME ------------------
-model modname modname = basename for the output model brik and any
axillary files during training. For testing, modname
is used to specify the model brik. As in the
examples above:

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

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

------------------- 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 files output for a test
dataset. These files consist of single columns of
value results for each training data timepoint. A
seperate file is generated for each possible pair of
training classes. If more than two class categories
were specified, an "overall" file is also generated.
By default, the prediction values take on a continuous
range; to output inter-valued class decision values,
use the -classout flag.

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

-nodetrend Flag to specify that pname files should not be
linearly de-trended (detrend is the current default).

-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 [Default]: Directed Acyclic Graph
vote : Max Wins from votes of all 1-vs-1 models

see http:\\cpu.bcm.edu\laconte\3dsvm for details and references.

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

-change_summary describes chages of note and rough dates of their implementation

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

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

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] -> verbosity 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 outweight 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 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. Schölkopf 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

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)

--------------------------------------------------------------------------
Jeff W. Prescott and Stephen M. LaConte

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

Questions/Comments/Bugs - email slaconte@cpu.bcm.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.

This page auto-generated on Fri Jul 3 05:16:58 EDT 2009

AFNI program: 3dsvm

Output of -help

Output of `-help`