ProbFOIL v2.1
=============

ProbFOIL is a probabilistic extension of FOIL that is capable of learning probabilistic rules from
probabilistic data.

ProbFOIL 2.1 is a redesign of the Prob2FOIL algorithm that was introduced in https://lirias.kuleuven.be/handle/123456789/499989.
It works on top of ProbLog 2.1.

If you are looking for the version used in the paper, you should check out the tag ``paper_version``.

Installation
------------

ProbFOIL 2.1 requires ProbLog 2.1.
You can install ProbLog by using the command:
    
.. code-block:: python

    pip install problog

ProbFOIL does not require any further installation.

Usage
-----

The input of ProbFOIL consists of two parts: settings and data.
These are both specified in Prolog (or ProbLog) files, and they can be combined into one.

The data consists of (probabilistic) facts.
The settings define

* target: the predicate we want to learn
* modes: which predicates can be added to the rules
* types: type information for the predicates
* other settings related to the data

To use:

.. code-block:: bash

    probfoil data.pl

or, in the repository version

.. code-block:: bash

    python probfoil/probfoil.py data.pl

Multiple files can be specified and the information in them is concatenated.
(For example, it is advisable to separate settings from data).

Several command line arguments are available. Use ``--help`` to get more information.

Settings format
---------------

Target
++++++

The target should be specified by adding a fact ``learn(predicate/arity)``.

Modes
+++++

The modes should be specified by adding facts of the form ``mode(predicate(mode1, mode2, ...)``,
where ``modeX`` is the mode specifier for argument X.
Possible mode specifiers are:

   * ``+``: the variable at this position must already exist when the literal is added
   * ``-``: the variable at this position does not exist yet in the rule (note that this is stricter than usual)
   * ``c``: a constant should be introduced here; possible value are derived automatically from the data

Types
+++++

For each relevant predicate (target and modes) there should be a type specifier.
This specifier is of the form ``base(predicate(type1, type2, ...)``, where ``typeX`` is a type identifier.
Type can be identified by arbitrary Prolog atoms (e.g. ``person``, ``a``, etc.)

Example generation
++++++++++++++++++

By default, examples are generated by quering the data for the target predicate.
Negative examples can be specified by adding zero-probability facts, e.g.:

.. code-block:: prolog

    0.0::grandmother(john, mary).

Alternatively, ProbFOIL can derive negative examples automatically by taking combinations of possible
values for the target arguments. Note that this can lead to a combinatorial explosion.
To enable this behavior, you can specify the fact

.. code-block:: prolog

    example_mode(auto).


Example
-------

.. code-block:: prolog

    % Modes
    mode(male(+)).
    mode(parent(+,+)).
    mode(parent(+,-)).
    mode(parent(-,+)).

    % Type definitions
    base(parent(person,person)).
    base(male(person)).
    base(female(person)).
    base(mother(person,person)).
    base(grandmother(person,person)).
    base(father(person,person)).
    base(male_ancestor(person,person)).
    base(female_ancestor(person,person)).

    % Target
    learn(grandmother/2).

    % How to generate negative examples
    example_mode(auto).

Further examples can be found in the directory ``examples``.