/***********************************************************************/
/*                                                                     */
/* THIS SOURCE CODE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND,  */
/* AND ITS AUTHOR AND THE JOURNAL OF ARTIFICIAL INTELLIGENCE RESEARCH  */
/* (JAIR) AND JAIR'S PUBLISHERS AND DISTRIBUTORS, DISCLAIM ANY AND ALL */
/* WARRANTIES, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF  */
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ANY       */
/* WARRANTIES OR NON INFRINGEMENT. THE USER ASSUMES ALL LIABILITY AND  */
/* RESPONSIBILITY FOR USE OF THIS SOURCE CODE, AND NEITHER THE AUTHOR  */
/* NOR JAIR, NOR JAIR'S PUBLISHERS AND DISTRIBUTORS, WILL BE LIABLE    */
/* FOR DAMAGES OF ANY KIND RESULTING FROM ITS USE. Without limiting    */
/* the generality of the foregoing, neither the author, nor JAIR, nor  */
/* JAIR's publishers and distributors, warrant that the Source Code    */
/* will be error-free, will operate without interruption, or will meet */
/* the needs of the user.                                              */
/*                                                                     */
/***********************************************************************/


                     INSTRUCTIONS FOR USING FLARE
                  ----------------------------------


1. Creating the Executable

To construct the executable version, simply run 'make' against the 
makefile provided in this directory.

The makefile assumes that the C++ compiler used is 'gcc'. If you are
using a different compiler, amend the makefile accordingly.


2. Format of the Files

FLARE uses 5 kinds of files. All have the same name but a different
extension. The extensions and their meaning as to the contents of
the files are as follows:

   - .hdr:   The header file, which is made up of 3 lines. The first
             line lists the number of attributes, the number of 
             training vectors, the number of test vectors, the number
             of precepts and the number of commonsense rules (used 
             to generate precepts). The second line lists the number
             of possible values or range of each attribute. The third
             line encodes the type (nominal=0, linear=1) of each 
             attribute.

   - .raw:   The training set. Vectors are listed one per line. All
             attributes' values are listed followed by the position 
             of the target attribute, the value of the vector's static
             priority and the definition flag.

   - .tst:   The test file if one exists. Same format as the training
             file.

   - .pr:    The pre-encoded precept file. Same format as the training
             and test files.

   - .pr.cs: The file containing the "commonsense" rules from which
             precepts are generated automatically. Same format as 
             training and test files.

   - .pr.pr: The file containing the vector that instantiates the 
             rules of '.pr.cs' to the current domain to generate the
             specific precept(s). Same format as training and test 
             files.

FLARE selects which files to use based on arguments given at the 
command line when it is executed.


3. Running the Program

The executable file is called 'flare'. It is invoked as follows:

           >flare b|c|i filename [p|g]

The arguments have the following semantics:

   - b|c|i:    Compulsory argument. Selects the way learning and 
               generalisation take place. 'b' is for batch mode which
               uses one half of the dataset at random for learning
               and the remaining half for reasoning. 'c' is for 
               10-way cross validation applied to the complete
               dataset. 'i' is for learning the training set 
               'filename.raw' and generalising on the test set
               'filename.tst'.

   - filename: Compulsory argument. The name of the file to run
               against FLARE without any extension (e.g., 'zoo').

   - [p|g]:    Optional argument. Selects a file of precepts when 
               precepts are available. 'p' uses the file with extension
               '.pr' which must contain pre-encoded precepts. 'g' uses
               the files '.pr.cs' and '.pr.pr' to automatically 
               generate domain-specific precepts.

There are three data files from the UCI Repository to serve as examples 
in this directory:

   - lenses database (including precept file and files for automatic 
     generation of precepts)

   - zoo database (including precept file)

   - hepatitis database (including precept file)

To run FLARE against, say the zoo database (using cross-validation), 
simply type at the prompt:

           >flare c zoo

If you wish to incorporate the pre-encoded precepts, then type:

           >flare c zoo p


4. Interpreting the Results

The results provided consist of a line with the following values 
reported:

   - batch mode:            predictive accuracy on test set, number 
                            of training vectors, average size of final
                            knowledge base and execution time.

   - cross-validation mode: predictive accuracy on test set, average 
                            number of training vectors and average 
                            size of final knowledge base.

   - interactive mode:      predictive accuracy on test set, number 
                            of training vectors, average size of final
                            knowledge base and number of test vectors.

5. Comments

For a complete description of FLARE, please refer to:

  "An Integrated Framework for Learning and Reasoning"
  by Christophe Giraud-Carrier and Tony Martinez
  in Journal of Artificial Intelligence Research, Vol. 3, 147-185, 1995

Any bug, comments or suggestions on FLARE should be sent to:

  email: 'cgc@compsci.bristol.ac.uk'

  snailmail: Christophe Giraud-Carrier
             Department of Computer Science
             University of Bristol
             BRISTOL, BS8 1TR
             United Kingdom
