+--------------------------------------------------------+
SVM-lite 6.01 / MATLAB MEX Interface
(c) Thorsten Joachims (Original SVM-Lite software)
(c) The Mathworks (MATLAB/MEX interface)
(c) Tom Briggs 2005 (MEX extensions)
+--------------------------------------------------------+

AUTHOR: 

Tom Briggs (thb@ship.edu), 
Computer Science Department
Shippensburg University
1871 Old Main Drive
Shippensburg, PA
USA


This work is meant as an extension to the SVM-Lite package
developed by Thorsten Joachims (thorsten@joachims.org), 
see LICENSE.txt in SVM-Light's source for more information.

INSTALLATION REQUIREMENTS:
	* MATLAB (tested with R13 and R14 Linux, Windows, and Solaris SPARC)
	* A working C compiler (or the built-in LCC compiler)^*
	  (lcc seems not to work under Windows)




INSTALLATION (BINARY UNIX)

1. Extract the archive file to any directory on your computer system.

	$ cd /work
 	$ tar xvfz svm-mex601.tar.gz 
        $ cd /work/svm-mex601

2. Run MATLAB

3. Add the following two paths to your MATLAB search path:
   >> addpath /work/svm-mex601/bin
   >> addpath /work/svm-mex601/matlab

4. Installation is complete.





INSTALLATION (BINARY WINDOWS)

1. Unzip the archive file to any directory on your system:
   (i.e. use WinZip)

2. Run MATLAB

3. Add the "svm-lite" directory you created in step 1 to your MATLAB path

	File->Set Path->Add
	Browse to the directory in step 1, and find "bin"

	repeat, and add matlab

	Click on the "Save" button




INSTALLATION (SOURCE UNIX)

1. Unzip the archive file anywhere on your system:

   $ cd /work
   $ tar xvfz ~/svm-mex601.tar.gz
   $ cd svm_mex601

2. Extract the SVM-Light 6.01 source from Joachim's website directly
   into the "src" sub-directory
   $ cd src
   $ tar xvfz ~/svm-light.tar.gz

3. Execute the "install.sh" script in the "svm_mex601" directory:
  $ cd ..
  $ ./install.sh

  This will patch the distributed code for svm_light, and compile
  the mex libraries for your system (*note* MATLAB must be installed
  and in your path, and a "mex -setup" command was performed).


  *Note: if you have custom modifications to the svm-light package, 
  you may copy your files into the src directory.  The principle changes
  are the renaming of "free()" , "malloc()" and "realloc()" function calls
  to "myfree()", "mymalloc()", and "myrealloc()" to satisfy MATLAB.

4. Add the path to the "bin" and "matlab" directories (as noted above).




INSTALLATION (SOURCE WINDOWS)

1. A working "patch" utility is required (can be downloaded from sourceforge).

2. Follow the UNIX source instructions as above, however, run "install.bat"
   instead of "install.sh"

   *If compiling manually, look at the install.bat file.  There are two
   "defines":  -DMATLAB_MEX and -DMEX_MEMORY that *must* be set for Windows
   to avoid double-free on a pointer.  


TESTED ENVIRONMENTS:
     * MATLAB R13 


     *Windows			* Solaris
	LCC			   GCC
	Mingw-GCC		   Sun Workshop
	
     *Linux
	GCC


USAGE EXAMPLE:

	* Assuming there are two MATLAB matrices X and Y, that correspond
	  to the training data (X) and training labels (Y); and another
	  pair, testing data (XT) and testing labels (YT).

	* Execute 'svmlearn' with the training data, and the same
          command-line argument usually given to SVM-Lite -
	  Here, the RBF kernel (-t 2) is selected, with its Gamma parameter
	  to 0.3 (-g 0.3) and an error penalization parameter set to 0.5,
	  (-c 0.5).  (See Example Session for details).

	model = svmlearn(x,y,'-t -g 0.3 -c 0.5');

	* This produces the following output to the command window, and a
	  new MATLAB variable, "model" is created.  This is a structure that
	  contains the support vectors, and values computed by the optimization
	  procedures (e.g. alpha values, model_length, ...).

	* Note: Adding a '-v 0' to the parameter string disables output
	  from the SVM software.

	* Execute 'svmclassify' with the testing data and the model
	  generated by 'svmlearn'.

	[err, predictions] = svmclassify(xt,yt,model);

	* Note: it is safe to ignore the warning about "lin_weights".	

	* An example session follows.  It demonstrates training a 
	  SVM with the parameters described above.  The error rate
	  of the testing (using the learned model) is displayed at 
	  the end (as a percentage).


EXAMPLE SESSION:
-----------------------------------------------------------------------	
>> model = svmlearn(x,y,'-t 2 -g 0.3 -c 0.5')
Optimizing...................................................................
.............................................................................
.............................................................................
.............................................................................
.....
 Checking optimality of inactive variables...done.
 Number of inactive variables = 335
done. (304 iterations)
Optimization finished (46 misclassified, maxdiff=0.00073).
Runtime in cpu-seconds: 0.13
Number of SV: 272 (including 262 at upper bound)
Computing XiAlpha-estimates...done
Runtime for XiAlpha-estimates in cpu-seconds: 0.00
Number of kernel evaluations: 79422

model = 

           sv_num: 273
      upper_bound: 262
                b: -0.1069
         totwords: 2
           totdoc: 400
        loo_error: -1
       loo_recall: -1
    loo_precision: []
         xa_error: 60.2500
        xa_recall: 44.7005
     xa_precision: 44.4954
          maxdiff: 7.3188e-004
       r_delta_sq: 1.8625
      r_delta_avg: 0.8535
     model_length: 7.6915
             loss: 148.5834
            vcdim: 107.3005
            alpha: [400x1 double]
      lin_weights: []
            index: [400x1 double]
           supvec: [273x2 double]
      kernel_parm: [1x1 struct]


>> [err , predictions ] = svmclassify(x,y,model);
Warning: could not retrieve lin_weights from the given struct.
>> err

err =

    0.1150

>> 

------------------------------------------------------------------------

	
