pepl.pl -- An implementation of the FAM algorithm.

Pepl is an implemention of the failure adjusted (FAM) algorithm which does parameter estimation (PE) of the probability labels of stochastic logic programs (SLPs).

See documentation fam/1 for details on how to run parameter estimation on SLPs.

Example stochastic programs are in directory slp and example run scripts are in examples.

Licence

This software is distributed under the MIT licence.

Installation and testing ...

Pepl runs on current versions of SWI (7) and Yap (6.3).

... on SWI

pack_install(pepl).
[library(pepl)].
[pack('pepl/examples/main')].
main.

... on Yap

Download latest sources from http://stoics.org.uk/~nicos/sware/pepl <br> or https://github.com/nicos-angelopoulos/pepl

gunzip pepl-*tgz
tar xf pepl-*tar
cd pepl-*
cd examples
yap
[main].
main.

Package information

author

- Nicos Angelopoulos

version

- 2.1, 2017/2/25

- 2.0.6, 2014/01/28

See also

- the user guide at pack('pepl/doc/pepl-user_guide.pdf').

- James Cussens. Parameter estimation in stochastic logic programs. Machine Learning, 44(3):245-271, 2001. ftp://ftp.cs.york.ac.uk/pub/aig/Papers/james.cussens/jcslpmlj.pdf

- Nicos Angelopoulos, Notes on the implementation of FAM, 3rd Probabilistic Logic Programming workshop (a ILP 2016 workshop), 03/09/2016, http://ceur-ws.org/Vol-1661/paper-05.pdf

- pepl website http://stoics.org.uk/~nicos/sware/pepl

license

- This software is distributed under the MIT licence

fam(Opts)

Run the failure adjusted maximisation (FAM) parameter estimation algorithm.

For SLP source file jc_ml_S1.slp

0.5:: s(X,p) :- p(X), p(X).
0.5:: s(X,q) :- q(X).
0.5:: p(a).
0.5:: p(b).
0.5:: q(a).
0.5:: q(b).

and data file jc_ml_S1_data.pl

frequencies([s(a,p)-4,s(a,q)-3,s(b,p)-2,s(b,q)-3]).

the call

   fam( [goal(s(_A,_B)),slp(jc_ml_S1),datafile('jc_ml_S1_data.pl'),final_pps(PPs)] ).

succeeds with

   PPs = [0.6602,0.3398,0.5858,0.4142,0.5,0.5]

Options:

• count(CountMeth), CountMeth in {exact, store, sample};
• times(Tms), default is Tms = 1000 (only relevant with CountMeth=sample);
• termin(TermList), currently TermList knows about the following terms
  • interactive- ask user if another iteration should be run,
  • iter(I)- I is the number of iterations,
  • prm e(ǫ p )- parameter difference between iteration, that renders termination due to convergence of all parameters, between two iterations,
  • ll e(ǫ λ )- likelihood convergence limit;
• goal(Goal), the top goal, defaults to an all vars version of data;
• pregoal(PreGoal), a goal that called only once, before experiments are run. The intuition is that PreGoal will partially instantiate Goal.
• data(Data), the data to use, overrides datafile/1. Data should be

  a list of Yield-Times pairs. (All Yields of Goal should be included in Data, even if that means some get Times = 0.)

• prior(Prior), the distribution to replace the probability labels with.

  Default is that no prior is used, Prior=none, input parameters are used as given in Slp source file. System also knows about uniform and random. Any other distribution should come in Prolog source file named Prior.pl and define Prior/3 predicate. First argument is a list of ranges (Beg-End) for each stochastic predicate in source file. Second argument, is the list of actual probability labels in source file. Finally, third argument should be instantiated to the list of labels according to Prior.

• datafile(DataFile), the data file to use, default is SLP data.pl. DataFile should have either a number of atomic formulae or a single formula of the form : frequencies(Data).
• complement(Complement), one of : none (with PrbSc = PrbT rue,

  the default), success (with PrbSc = 1 − PrbF ail), or quotient ( with PrbSc = PrbT rue/(PrbT rue + PrbF ail)).

• setrand(SetRand), sets random seeds. SetRand = true sets the seeds

  to some random triplet while the default SetRand = false, does not set them. Any other value for SetRand is taken to be of the form rand(S1,S2,S3) as expected by system predicate random of the supported prolog systems.

• eps(Eps), the depth Epsilon. Sets the probability limit under which Pepl considers a path as a failed one.
• write_iterations(Wrt) indicates which set of parameters to output. Values for Wrt are: all, which is the default, last, and none.
• write_ll(Bool) takes a boolean argument, idicating where loglikelihoods should be printed or not. Default is true.
• debug(Dbg) should be set to on or off (later is the default). If on, various information about intermediate calculations will be printed.
• return(RetOpts), a list of return options, default is the empty list.

  The terms RetOpts contain variables. These will be instantiated to the appropriate values signified by the name of each corresponding term. Recognised are, initial pps/1 for the initial parameters, final pps for the final/learned parameters, termin/1 for the terminating reason, ll/1 for the last loglikelyhood calculated, iter/1 for the number of iterations performed, and seeds/1 for the seeds used.

• keep_pl(KeepBool), if true, the temporary Prolog file that contains the translated SLP, is not deleted. Default is false.
• exception(Handle), identifies the action to be taken if an exception

  is raised while running Fam. The default value for Handle is rerun. This means the same Fam call is executed repeatedly. Any other value for Handle will cause execution to abort after printing the ex- ception raised.

pepl_citation(-Atom, -Bibterm)

This predicate succeeds once for each publication related to this library. Atom is the atom representation suitable for printing while Bibterm is a bibtex(Type,Key,Pairs) term of the same publication. Produces all related publications on backtracking.

pepl_version(-Version, Date)

Pepl's current Version (Maj:Min:Fix) and publication date (date(Year,Month,Day)).

pepl_version( 2:0:6, date(2014,1,28) ).

ssave(+File)

Save the stochastic program currently in memory to a file.

sls

Listiing of the stochastic program currently in memory.

sload_pe(Files)

sload_pe(Files, Options)

Load an SLP to memory. If the source file has an slp extension the extension may be omitted. Pepl looks in the following directories and order for the source file(s). ., and ./slp/ while on SWI it also looks in, pack(’pepl/slp/’).

scall(Goal)

Sample Goal.

?- sload_pe( [pack(pepl/slp/coin] ).

scall(Goal, Eps, Meth, Path, Succ, Prb)

This predicate is for people interested in the iternals of pepl. Use at your own peril.

The predicate arguments are as follows.

• The vanilla prolog Goal to call.
• The value of Eps(ilon) at which branches are to be considered as failures.
• The search Method to be used, (all for all solutions or sample for a single solution).
• The Path(s) of the derivation(s).
• A flag idicating a Succ(essful) derivation or otherwise-Succ is bound to the atom fail if this was a failed derivation and remains unbound otherwise. BrPrb the branch probability of the derivation. if this was a failed derivation and remains unbound otherwise.
• BrPrb the branch probability of the derivation.

See predicate main_gen/1, in examples/main_scfg.pl for example usage.

switch_dbg(Switch)

Switch debugging of fam/1 to either on or off.

dbg_pepl(+Goal)

Call Goal iff in (pepl) debugging.