########################################################################

Gaussian Processes for Preference Learning over Labels v1.0
			--- MAP and Laplace Approximation 

Chu Wei (C)Copyright 2002-2004 at Gatsby Unit.

########################################################################

1. Installation
	a) download gplabels.tar to your machine (Linux is assumed)
	b) tar -xvf gplabels.tar
	c) cd gplabels
	d) gcc -o gplabels *.c -lg2c -lm -O2 -Wall
	e) the program using ARD kernel is generated by
	 gcc -o gplabels_ard *.c -lg2c -lm -O2 -Wall -D _GPLABELS_ARD
 
2. Data Format
	a) a space delimited plain text file with a new-line character 
	 at the end of each line
	b) each line contains one sample.
	c) the file containing training samples is named as mytask_train.0
	d) the corresponding label preferences should be saved in mytask_labels.0
	e) each line contains the label preferences for the samples accordingly.
	f) say 1 2 1 3, that means label 1 is preferred to label 2 while label 1 is preferred to label 3 too. 
	g) mytask_labels.0 should have the same lines as the mytask_train.0 has. 
	h) samples for test should be saved in mytask_test.1
	i) the corresponding label preferences should be saved in mytask_targets.1 accordingly
	j) "mytask" could be any string followed by "_train" and "_test".
	k) see the example files under the folder:
	  toy_train.dat, toy_test.dat and toy_targets.dat. 	
	
3. Input and Output
	a) prepare your data files
		"mytask_train.0"
		"mytask_test.0"
		"mytask_targets.0" (optional)
	b) run the program
		./gplabels mytask_train.0
	c) Laplace Approx will be done for model selection as default.
	d) output files
		1) "mytask_test.0.guess" to save predictive ordinal scales
		 for test data, integers from 1 to R.
		2) "mytask_test.0.conf" to save the variance of predictive
		 distribution of test data.
		3) "mytask_test.0.func" to save the mean of predictive
		 distribution of test data.
		4) "mytask_test.0.prob" to save the predictive probability
		 of ordinal scales of test data.
		5) "mytask_train.0.log" to save the optimal settings of 
		 the Gaussian process model, including kernel parameters, 
		 noise level and thresholds.
		6) "mytask_train.0.ard" to save the optimal ARD parameters
		 if ARD kernel was used.
		7) "gpref_lap_batch.log" to save results
		 for batch tasks, including zero-one error, absolute error,
		 mean absolute error and CPU time consumed in seconds.
	
	e) if you have a BATCH of tasks, prepare your data files as
	 "mytask_train.0" "mytask_test.0" "mytask_targets.0"(optional),
	 "mytask_train.1" "mytask_test.1" "mytask_targets.1"(optional),
	 "mytask_train.2" "mytask_test.2" "mytask_targets.2"(optional),
	 ... ...
	 the script program "gplabelsbatch.sh" would make them done one by one.
	 the results of these files are saved in "gplabels_lap_batch.log".
	
4. Options
	a) for help information
		./gplabels
	b) specify initial noise variance, say 0.4
		./gplabels -S 0.4 mytask_train.0
	c) specify initial kernel parameter, say 0.01
		./gplabels -K 0.01 mytask_train.0
	d) specify to use Gaussian kernel (default Linear kernel)
		./gplabels -G mytask_train.0 
	e) specify the power level, say 3.0
		./gplabels -O 3 mytask_train.0

5. Reference
	"Preference Learning with Gaussian processes",
	Chu, W and Z. Ghahramani, Technical Report, 2005
	http://www.gatsby.ucl.ac.uk/~chuwei/paper/gppl.pdf

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~