+--------------------------------------------------------+
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 for more information.  

**Author's Note: if you are using this software, I would really appreciate
hearing from you. It would be really great if you cite this in your
bibliography.  If you do, please do not forget to include a citation to 
the original work by Thorsten Joachims.  Without his work, this extension
would not exist.  


INSTALLATION REQUIREMENTS:
	* MATLAB (tested with R13)
	* A working C compiler (or the built-in LCC compiler)
	* A working `patch` and `install` command 

INSTALLATION:


1. Extract the files from the SVM-mex archive to a working directory,
   such as your MATLAB "work" directory:
  
   tar xvfz svm-mex601.tar.gz

   This will create the directories  "svm-lite" and "svm-lite/src"

2. Extract Thorsten Joachim's svm-lite archive into the "src" directory, -or-
   if the files are already available on your system, the install script will
   ask for the location and copy them into the proper place.

   cd svm-lite/src
   tar xvfz ~/svm-lite.tar.gz

3. Change to the "dist" directory:

   cd ../dist

4. Run the install.sh script to copy and patch the SVM files 

    ./install.sh

   * Note, this will patch the svm-lite distribution files with the
   necessary changes needed for MATLAB - it does not build them.


5. Run MATLAB on your local system


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

	File->Set Path->Add With Subfolders
	Browse to the directory in step 1
	Click on the "Save" button

7. Make the "svm-lite" directory be the current workspace location

	>> cd work/svm-lite

8. Compile the source files
	
	>> compilemex

	*Note: If MEX has not be setup before, then execute "mex -setup" 
	prior to this step.

9. If there were no errors, the package is compiled.  This has been tested
   with the following compilers:

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

>> 

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

	
