0. Intro

    These programs are written in Prolog and were developed and tested
on a Linux architecture. To run on different OS or a different Linux
distribution, you will need to create the src/logamma_{sicstus,yap}.so
(see details in the corresponding .pl file). In the versions of prologs
mentioned, Yap executes the programs much faster than SICStus.
Yap is a fast free system from http://www.ncc.up.pt/~vsc/Yap/
but is fairly unstable so not all version may run our software.
Latest testing verifies that current stable Yap wont run this software,
however the CVS 4.5.2 does (although there is still an unresolved issue
with networked filesystems).
SICStus is a commercial product, http://www.sics.se/isl/sicstus.html
popular in universities (free/evaluation copies possibly available).
Due to its stability, we develop our code in this system. Any
version later than 3.9.0 should run this software.

A.  The Easy Way to Getting Results
    -------------------------------

i. From top directory (%cd mcmcms)

% sicstus   (or % yap)
| ?- compile( run ).
...
| ?- run( [runs_file('runs/simple'),results_dir(test)] ).
...
[Note : Use run( [] ).  or even 'run.' which are
almost equivalent to the above but always create 'test' at the top
directory. run is identical to run( [] ).]

ii.
Assuming the run was successful, there will be a new ResultsDir,
here 'test', created, where all result files can be found.
ResultsDir is created relative to your working directory.
The RunsFile, here 'runs/simple', is similarly searched for, relatively
to the current directory and failing that, to the mcmcms top directory, see
run.pl for details on the format of run files. The particular run file
dictates 5 very simple experiments, and in the call used all
five are run (id/1 can be used to restrict this).
Within ResultsDir the following files are created:
    std_out_n_err            generic progress messages for the runs
   *.blankets    as above but calculated for Markov blankets rather than edges
   *.counts      a percentage count for all possible edges
   *.gz          all models visited and considered
   *.stats       some peripheral output, such as listing and statistics
   *.stays       see bellow
   *.visits      see bellow

Assuming `gnuplot' is somewhere in your path, you should also get
four graphs during execution. These are two sets of two kinds of graphs.
The first kind, is a plot of the '.stays' file corresponding to the 5th
experiment and the second one, a plot of the corresponding '.visits' file.
Stays are the times stayed in each model before "jumping" while visits sums
over the times stayed on each visited model in the whole chain.

B.  Detailed Way to Getting Lost
    -----------------------------

i.  Directory Structure
    ---

auxil/
         All the auxiliary programs such as counts, blankets and visits
         creators and prolog interface for displaying BNs using 
         the `graphviz' drawing package.

data/
         This is where src/ programs try to find the (training) data.
         Name of the file to be used in a particular trial is
         data/jc_asia_data_{Data}.pl where Data is one of the arguments
         in main (supplied by run/8).

obs/
         Obsolete files.

runs/
         Repository of scripts. Example files defining run/8, which
         is used by run.pl .

slp/
          A chaotic collection of slps that generate BNs from a list of Nodes.
          Very fragile; treat gently. The top predicate in most of them should 
          be bn/2 (first argument is a list of Nodes with the second one,
          instantiated to a BN formed from the Nodes).

src/
          The prolog source files that implement the mcmc algorithm.
          Includes a lib/ directory of supporting predicates.

ii.	Displaying BNs with graphviz
		---

   This is not an essential part of MCMCMS but it is pretty nifty
to be able to visualise all those BNs. You need to install `graphviz'
http://www.research.att.com/sw/tools/graphviz/download.html
then either add to TCLLIBPATH the location where Tcldot resides,
or copy/move this file, somewhere where your tcl looks for lib files.
If you using latest graphiviz (currently 1.10) you also need to copy
file $prefix/share/graphviz/demo/doted to a directory in your $PATH.
If you are using older version, such as 1.7 make sure that the
wish command in your (bash) $PATH is version 8.3 or older.

   To display the current BN and the proposed one, use
     display(next_display_at) run/1 option. For example
     run( [display(next_display_at), id(2)] ).
this will display the first pair and then ask for a number.
Pressing return or, 1 and then return, will display next
pair as well. An integer larger than 1, means display nth step from here,
whereas 0 halts prolog.

    To display individual bns, represented as prolog terms use,
      % cd auxil; prolog 
      ?- [disp_bn].
      ?- disp_asia.
    Which should display the ASIA BN. Nodes are colour coded. Red,
for nodes with no parents, green for nodes with no children, but with
parents, and orange for nodes with, both, children and parents.
Other BNs can be displayed with disp_bn( BN ). See 'auxil/disp_bns.pl'
for the term representation of BNs.

    To display bns sampled independently use ?- ['auxil/disp_sampled_bns.pl'].
		for example
			disp_sbns( bn_un_2p, 10, donot_stop, [a,b,c,d,e,f,g,h] ).
displays 10 bns without waiting for user interaction in the between
  1st argument: basename of an slp in ../slps/
  2nd argument: number of bns to generate
  3rd argument: change to stop for user interaction between each bn
  4th argument: the nodes

To compare a learned model against a generator BN (here ASIA is the
assumed default generator) do 
      % cd auxil 
      % prolog 
      ?- [disp_cut_off].
      eg (after you 've done A.i: above)
      ?- disp_cut_off( 0.95, '../test/tr_op0.8_or_3p_i1K_all_s1.counts' ).
The generic use is 
      ?- disp_cut_off( CutOff, File ).
The first argument is in the range 0 =< CutOff =< 1
which means that the "learned" model is constructed by taking an
edge to be in the model iff it has appeared in Time > CutOff point.
The edges in the contrasting BN are coloured as follows
  red       for edges learned correctly
  yellow    for false negative (edges present in original only)
  pink      for false positive (edges present in learned only)
The second argument, File, should point to .counts file.

---
With comments on the theory contact James Cussens, jc@cs.york.ac.uk .
With comments on the programs contact Nicos Angelopoulos, nicos@cs.york.ac.uk .

4th December 2003.
