%
% The content of this file and the associated package is copyrighted
%  Daniel Fredouille (c) 2005
%
% You can use it and modify it freely as long as you do not use it for 
% commercial purposes.
% For commercial use, please contact the author, coordinates can be found at
%   http://www.comp.rgu.ac.uk/staff/df/
%   http://www.comp.rgu.ac.uk/staff/chb/
%


I- Package description
----------------------
This package contains the code of the dftd parser, together with its interface
to call it from the prolog interpreter Yap. As described in the paper:
 - "A Parser for the Efficient Induction of Biological Grammars"
   Chris H. Bryant, Daniel Fredouille

This package contains the following:

- c : The C source file for the parser and its interface
- pl : Prolog code related to the use of the parser in Yap

And files/directories containing examples of use of the parser
- example_parsing.pl
- example_dftd_cost
- example_yap_cost
- example_dftd
- example_yap        

As help, it contains also a README file (this file), and a html documentation 
of the code (generated using Doxygen (c) with configuration file 
generate_doc.dox) in directory html.

II- Installation instructions
-----------------------------

1)- Download the package, dftdp_in_yap.tar.gz available at: 
http://www.comp.rgu.ac.uk/staff/chb/research/data_sets/ilp05/
2)- uncompress and unarchive it:
      gunzip dftdp_in_yap.tar.gz
      tar xf dftdp_in_yap.tar
    you should have a directory dftdp_in_yap created
3)- go to dftdp_in_yap/c and compile the C files with the commands
      cd dftdp_in_yap/c; build_dftdp_in_Yap
    a file grammar_parser.o should be created at this stage
4)- use the package (see Section III)

III- Using the software for parsing
-----------------------------------

First a html documentation has been generated from the code in directory html.
However, this details the whole code and only a subset of it is useful for 
the user (the rest being useful to the programmer).

To focus on fonctions available to the user, see page:
./html/group__builtin.html

An example of use of the software to parse some sequences is available in file
example_parsing.pl. You can run it by the command:
    cat example_parsing.pl | yap
And see comments inside file example_parsing.pl to understand what is going on.

The expected output is:
>>--------------------------
[ Restoring file /usr/local/lib/Yap/startup ]
[ YAP version Yap-4.4.4 ]
version: Parser in Yap Prolog, Connection v3.5
version: Dftd parser v0.9
{Grammar:
Non terminals: start gap
Terminals:  a b
Start symbol: start
Production rules:
start : gap a a
gap :
gap : a gap
gap : b gap
}
{Gaps: }
{mysequences sequences:
(0) ababa
(1) abaaa
}
:- user:cfgp_parse_seq(1),write(parsing succeeded),nl failed.
parsing succeeded for sequence 2
Number of accepted sequences:1
Number of rejected sequences:1                         
--------------------------<<


Warning:
--------
The software is not "user proof". This means that if the execution of the 
predicates related to parsing are not made in the right order (e.g. if you 
forget to initialise the parser before calling it for parsing a sequence, or 
that you try to access sequences that have not been stored), the software 
will crash. If this happens to you, you can sometimes obtain informations on 
why the software crashed by turning off (i.e., removing) the -DNDEBUG 
compilation option and running your program again. After identifying and 
correcting the problem, you can turn on -DNDEBUG again, since this will enable
a more efficient parsing in term of running times.


IV- Using the software for parsing during an ILP inference process
------------------------------------------------------------------

Examples of such uses are given in directories:
- example_dftd
- example_dftd_cost
Examples of comparable parsing, but using the Yap Prolog interpreter are 
given in:
- example_yap
- example_yap_cost

Each directory corresponds to an example of the 4 implementation described
in the paper (respectively i-dftd, i-dftd-cost, i- yap, i-yap-cost)

Each directory contains 5 files:
- example.b : a background knowledge file in Aleph format
- example.f : a set of positive examples in Aleph format
- example.n : a set of negative examples in Aleph format
- example.pl : a sequence of Prolog instructions to run inference
- res.txt : the result of inference

Here is a more detailed description:

* [A] Directory example_yap: 

This directory contains a classical inference with Aleph (using Yap as parser 
is the normal behaviour of Aleph). 

To run the example:
1)- change the path in the first line of the example.pl file such as to
reflect the location of your Aleph file.
2)- run the command: 
      cat example.pl | yap 

* [B] Directory example_dftd: 

This directory contains a classical inference with Aleph, but Aleph code has 
been modified to call the DFTD parser. (Modified code for aleph is  
./pl/alephgp.pl). 
To ensure Yap knows where to find the parsers, the file example.pl has been
modified from [A] such as to download the DFTD parser before inference.

To run the example:
1)- Ensure you have compiled the parser code (see Section II - Installation)
2)- run the command: 
      cat example.pl | yap 

* [C] Directory example_yap_cost: 

This directory contains a classical inference with Aleph, but the parsing of 
the examples is done in the cost/3 function of Aleph (using Yap).
For a discussion on advantages and inconvenients of this implementation 
compared to [A], please refer to the paper 
   "A Parser for the Efficient Induction of Biological Grammars"

To realise the computation of the coverage in the cost function, the file 
example.b has been modified from [A] such as to add the user defined cost 
function.

To run the example:
1)- change the path in the first line of the example.pl file such as to 
reflect the location of your Aleph file.
2)- run the command: 
      cat example.pl | yap 

* [D] Directory example_dftd_cost: 

This directory contains a classical inference with Aleph, but the parsing of 
the examples is done in the cost/3 function of Aleph, and using our DFTD 
parser.

To run the example:
1)- Change the path in the first line of the example.pl file such as to 
reflect the location of your Aleph file.
1)- Ensure you have compiled the parser code (see Section II - Installation)
2)- Run the command: 
      cat example.pl | yap 
To ensure Yap knows where to find the parsers, the file example.pl has been
modified from [A] such as to download the DFTD parser before inference.
To realise the computation of the coverage in the cost function, the file 
example.b has been modified from [A] such as to add a user defined cost 
function calling the DFTD parser.