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

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

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

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

1. Installation
	a) download gpref.tar to your machine (Linux is assumed)
	b) tar -xvf gpref.tar
	c) cd gpref
	e) gcc -o gpref *.c -lm -O2 -Wall
	f) the program using ARD kernel is generated by
	 gcc -o gpref_ard *.c -lm -O2 -Wall -D _GPREF_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 samples is named as mytask_samples.1
	d) the file containing preference relations for training is named as mytask_train.1
	e) the file containing preference relations for test is named as mytask_test.1
	f) each line contains two indices, say i j, that means the sample on the i-th line of mytask_samples.1 is preferred to the sample on the j-th line of mytask_samples.1. 
	h) "mytask" could be any string followed by "_train" and "_test".
	i) see the example files under the folder:
	  toy_train.dat, toy_test.dat and toy_samples.dat. 	
	
3. Input and Output
	a) prepare your data files
		"mytask_train.0"
		"mytask_test.0"
		"mytask_samples.0" 
	b) run the program
		./gpref mytask_train.0 mytask_samples.0
		or try the toy samples
		./gpref toy_train.dat toy_samples.dat
	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_samples.0" "mytask_train.0" "mytask_test.0" ,
	 "mytask_samples.1" "mytask_train.1" "mytask_test.1" ,
	 "mytask_samples.2" "mytask_train.2" "mytask_test.2" ,
	 ... ...
	 the script program "gprefbatch.sh" would make them done one by one.
	 the results of these files are saved in "gpref_lap_batch.log". 
	
4. Options
	a) for help information
		./gpref
	b) specify initial noise variance, say 0.4
		./gpref -S 0.4 mytask_train.0 mytask_samples.0
	c) specify initial kernel parameter, say 0.01
		./gpref -K 0.01 mytask_train.0 mytask_samples.0
	d) specify to use Gaussian kernel (default Linear kernel)
		./gpref -G mytask_train.0 mytask_samples.0 
	e) specify the power level, say 3.0
		./gpref -O 3 mytask_train.0 mytask_samples.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.

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