probfoil 2.1.0.1.dev2

Prob2FOIL: rule learner for probabilistic logic

#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 [ref].
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:

```
#!bash

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:

```
#!bash

probfoil 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.:


```
#!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

```
#!prolog

example_mode(auto).

```


##Example##

```
#!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`.