gbn.pl -- Running and managing runs of gobnilp.

Run a GOBNILP, Bayesian networks (BNs) learning task and/or post-run routines on learning output.

Post processing includes the generation of Fisher based visualisation and family heatmaps.
Assumes gobnlip is in your path. Currently only tested on *nix based systems.

Installation

To install

?- pack_install(gbn).

to load

?- use_module(library(gbn)).

Predicates

Main predicate for both running the BN experiment and post-processing is:

• gbn/1

Examples

?- gbn.
true.

?- ls.
% asia-24.07.13/
true.

?- gbn(debug(true)).
% Turning debugging on for predicate handle: gbn(gbn)
% Options: [$restore(gbn,debug,false),copy(false),data(pack(gbn/data/asia.dat)),display_dot(svg),odir(_33202),std_output(std_file)]
% Output directory: 'asia-24.07.13'
% Settings on: asia.set
true.

A more complex example

?- [cancer(aml)].

?- absolute_file_name( pack('gbn/run/gbns_in_cancer'), Abs ),
|    ls( Abs ).
% aml.pl    coa.pl    data/     gbm.pl    mpn.pl    mye.pl    plots/
Abs = '/home/nicos/.local/share/swi-prolog/pack/gbn/run/gbns_in_cancer'.

?- aml.
% Starting: aml
% Starting: fisher_nets
% Starting: fam_hmaps
% Starting: gates_nets
% Starting: svg_legend
% Finished: aml
true.

Info

author

- nicos angelopoulos

version

- 0.0.1 2014/4/8

- 0.1.0 2021/1/19

- 0.2.0 2021/1/23

See also

- https://doi.org/10.1038/s42003-022-03243-w

- https://stoics.org.uk/~nicos/sware/gbn

- https://www.cs.york.ac.uk/aig/sw/gobnilp/

- gbn/1

- gbn_version/2

 gbn_version(-Vers, -Date)

Get the current version and publication date.

?- gbn_version( Vers, Date ).
V = 0:2:0,
D = date(2021, 1, 23).

author

- nicos angelopoulos

version

- 0.0.1 2014/4/8

- 0.1.0 2021/1/19

- 0.2.0 2021/1/23

See also

- https://stoics.org.uk/~nicos/sware/gbn

- https://bitbucket.org/jamescussens/gobnilp

To be done

- control replacement of dot (and other specials?) in Bn var names via options

 gbn

 gbn(Options)

Run a GOBNILP, Bayesian networks (BNs) learning task and/or post-run routines on learning output.

Options is a term or list of:

copy(Copy=false)

if set to anything else than false the local file Copy is copied into Dir- multiple are allowed

dir(Dir)

output directory for runs, it should not exist (default: *<Pbname>-<date>*). When a variable, the name is returned

display_dot(DispDot=svg)

display dot filin format DispDot. false for not displaying.

data(Dfile)

The datafile on which gobnilp will be ran (pack(gbn/data/asia_100.dat)).

debug(Dbg)

can be false (also true_=_gbn or all).

multiple(Setting, Vals)

run multiple experiments where setting is given each Val-ue in turn

probname(Pbname)

used as stem for output files. Defaults is the stem of Dfile (so for Dfile =../data/asia.dat the stem is asia).

std_ouput(StdO)

what to do with gobnilp output ?, (std_file,output,<file>). Where std_file is <Pbname>_std_output.txt

setting(Key, Val)

set Gobnilp setting Key to value Val

author

- nicos angelopoulos

version

- 0.1 2014/4/8

- 0.2 2021/1/23

To be done

- subdirs option (ie non flat run dirs)

- bootstraps

- hook on to the c-code (see pack(gob))

 gbn_module

Documentation predicate to give anchor to the overall module documentation.

 gbn_term(+BnF, -Bn, -Adorned)

Parse a .bn gobnilp file into a Bn term of the form [Ch-Pas|_] and Adorned BN that also includes the overall score and a score for each Ch-Pas entry [Ch-Pas-Score|_]-BnScore.

?- absolute_file_name( pack(gbn/examples/crc.bn), Crc ),
   gbn_term( Crc, Bn, Adorned ).

Crc = '/home/na11/lib/swipl/pack/gnb/examples/crc.bn'.
Bn = ['ACVR2A'-['ARID1A', 'FBXW7', 'PTEN'], 'AMER1'-[], 'APC'-['ACVR2A', 'AMER1'], 'ARID1A'-[], 'ATM'-['ACVR2A'], 'BRAF'-['APC'], 'FBXW7'-[], 'KRAS'-[...], ... - ...|...],
Adorned = ['ACVR2A'-['ARID1A', 'FBXW7', 'PTEN']- -60.029495, 'AMER1'-[]- -79.527071, 'APC'-['ACVR2A', 'AMER1']- -131.057359, 'ARID1A'-[]- -84.299473, 'ATM'-['ACVR2A']- -43.772266, 'BRAF'-[...]- -110.700005, ... - ... - -86.616242, ... - ...|...]- -1567.186608.

 gbn_fisher_net(+DatF, +BnF, -FisheredF)

 gbn_fisher_net(+DatF, +BnF, -FisheredF, +Opts)

Colour Gobnilp BNs with co-occurance / mutual exclusivity scores according to Fisher test.

Options Opts are also passed to disp_bn/2.

Opts

adjust(Adj=BH)

either false, or a method recognised by R's p.adjust() function

bground(ClrBg = #D3D3D3)

background colour

clr_co(ClrCo)

colour for co-occurance (non significant level), default depends on Theme

clr_co_signif(ClrCoSgn)

colour for co-occurance (for significant values), default depends on Theme

clr_ex(ClrEx)

colour for mutual exclusivity (non significant level), default depends on Theme

clr_ex_signif(ClrExSgn)

colour for mutual exclusivity (for significant values), default depends on Theme

clr_neutral(ClrNeu)

colour for neutral directions (ie when non binary data are analysed)

clr_theme(Theme=bic)

defines default colour values. org theme is:

ClrCo = #4B5320

(green)

ClrCoSgn = #35978F

(bluegreen)

ClrEx = #CC0000

(red)

ClrExSgn = #BF812D

(golden)

Dash=solid

and

Ew=fix

bic theme is:

• ClrCoClrCoSgn"#35978F" (bluegreen)
• ClrExClrExSgn"#BF812D" (golden)
• Dash=dashed
• Ew=prop and
• Nw=rel_prop

dashed(Dash=dashed)

defines the edge style for edges with pval >= 0.05 (alt: solid)

directed(Dir=false)

default removes direction from BN

edge_metrics(Emetrs=_75242)

if present, returns the edge metrics used, in a list of X-Y-po(Pval,Odds)

edge_width(Ew=prop)

defines the edge width for edges (prop or fix)

node_pen_width(Nw=rel_prop)

defines the edge width for edges (rel_prop or fix)

postfix(Psfx=)

postfix for the output file (postfixing input). Defaults to '' if Theme == org and to the Theme otherwise

sim_pv(SimPv=false)

whether to use Monte Carlo to simulate p value (see fisher.test())

Requires pack(real) with RcolorBrewer installed.

author

- nicos angelopoulos

version

- 0.1 2015/11/23

- 0.2 2018/2/16, better themes support, and better bic theme

See also

- fisher.test() in R

 gbn_fisher_nets

 gbn_fisher_nets(+Opts)

Run a number of gbn_fisher_net/4 on files in current directory (version 2, as version 1 got lost).

For now it assumes a single .dat file in current directory and runs this against all .bn files creating os_postfix/3 results files with postfix=fish.

pupsh gbn_fisher_nets postfix=wb graphbgcolorwhite

Options are passed to gbn_fisher_net/4 except for dir(Dir).

Opts dir(Dir='.') directory to change to

rec(Rec=false) allow recursive descend call

%  pupsh gbn_fisher_nets bground=white clr_theme=bic

Creates an undirected version of the above:

% pupsh gbn_fisher_nets bground=white clr_theme=bic type=graph postfix=biu

author

- nicos angelopoulos

version

- 0.1 2016/6/16

 gbn_mtx_dat(+CsvF, ?DatF)

Convert csv input file Csv to a space separated value file which contains as a second line the counts of distinct values for each column. If DatF is a variable it is instantiatiated to file indicator which is produced by replacing the extension in CsvF with '.dat' . These .dat files are input data files to gobnilp.

Requires pack(mtx) and pack(os) to work. pack(os) is only required if DatF is a variable. Loading does not complain if this lib does not load properly (this is to avoid annoying message for user that do not require this modality of the predicate).

author

- nicos angelopoulos

version

- 0.1 2016/1/27

See also

- mtx/2 CsvF can be any recognised matrix input to mtx/2

- suggests/1 (pack(requires))

 gbn_mtx_subs(+Mtx, +Pred, +Opts)

Run gbn on a number of subsets of Mtx as defined by Pred/+2 Pred should be defined with additional 2 arguments, first for the name/identifier of the subset and second for list of pairs of the form: Column-Condition which be passed as 2nd and 3rd args of mtx_subset/4.

 gbn_fam_hmaps(+Opts)

Create family heatmaps for all families and all Bns in directory Dir (default is the current directory).

Every file ending in .bn is taken to a (Gobnilp generated) BN. There should be a single .dat file in the directory,
that is taken to hold the data used to create all BNs (Gobnilp default format).

Opts:

as_mutational(Bin=true)

whether the data contains mutations (when false arbitary integer values are assumed)

cellwidth(Cw=1)

cell width

cellheight(Ch=12)

cell height

col_hmap(ClrH=[])

list of value-"Colour" for each value in mtx (can contain non mtx values). If this is given it overrides ClrM and ClrW.

col_mut(ClrM = #CB181D)

colour of mutation

col_wt(ClrW = #08519C)

colour of wild type

dir(Dir=(.))

working directory

outputs(Outs=png)

output format(s) - propagates to multi_cow_plot/2 as ext()

x11(X11B)

defaults to false if SSH_TTY is defined OS variable, and true otherwise; passed to mtx_mut_hmap/2 and multi_cow_plot/2

Options are also passed to gbn_family_gates/5 and multi_cow_plot/2.

author

- nicos angelopoulos

version

- 0.2 2018/02/21

To be done

- add a simple example in examples/

 gbn_mtx_paired(+Mtx, +Cid1, +Cid2, -PAMtx)

Create a presence/absence matrix from two colums in Mtx.

For each value of Cid1 a row is created in PAMtx. For each value in Cid2 a column is created in PAMtx.

Values in PAMtx are binary and show presence (1) or absence of the particular Cid1/Cid2 values in Mtx.

PAMtx contains a header (all the Cid2 values, ordered) but now row names.

?- Mtx = [r(a,b,c),r(1,2,1),r(2,2,2)],
   gbn_mtx_paired( Mtx, a, c, PA ).

PA = [row(1, 2), row(1, 0), row(0, 1)].

?- Mtx = [r(ps,xs,ys),r(p1,x1,y1),r(p2,x2,y2),r(p1,x2,y3),r(p3,x3,y3)],
   gbn_mtx_paired( Mtx, ps, xs, PA ).

PA = [row(x1, x2, x3), row(1, 1, 0), row(0, 1, 0), row(0, 0, 1)].

?- Mtx = [r(ps,xs,ys),r(p1,x1,y1),r(p2,x2,y2),r(p1,x2,y3),r(p3,x3,y3),r(p1,x1,y1)],
   gbn_mtx_paired( Mtx, ps, xs, PA ).

Mtx = [r(ps, xs, ys), r(p1, x1, y1), r(p2, x2, y2), r(p1, x2, y3), r(p3, x3, y3), r(p1, x1, y1)],
PA = [row(x1, x2, x3), row(1, 1, 0), row(0, 1, 0), row(0, 0, 1)].

 gbn_family_gates(+Child, +Parents, +Mtx, -Gatrix, +Opts)

For a Child and list of Parents variables that are columns in Mtx,
Gatrix is the matrix formed of the columns described below.
Note that values in the Child and Parents columns should be binary for the predicate to work.<br>

Opts

not(Not=false)

whether to include not gates

simplify(Sify)

defines the type of simplication on the gates term (aox default, else no simplification)

xor(Xor=true)

whether to include xor gates

Gatrix

test_statistic

the result of Fisher test on the logic formula

complexity

integer- number of logic gates in formula

direction

mut_excl, or co_occur

odds

value on which the direction of relation between the formula and Child was derived

pval

pvalue

formula

logical gates formula

The first row holds the Child and the Parents consecutively.
Gatrix is passed through mtx/2 before being returned. Mtx is similarly treated as mtx/2 input.

author

- nicos angelopoulos

version

- 0.2 added options and ability to exclude not (currently false is the default)

 gbn_prefix_directed_constraints(+BnVars, +PfxPrs, +OutFile, +Opts)

For every pair of prefixes in PfxPrs:E-L, write all constrainsts that ban late BnVars (L prefixed) from be the parents of early ones (E prefixed).

BnVars is a list of atomic Bn variables. OutFile is an open/3 compatible file for writing.

Opts

bar_contra_self(Bar=true)

whether to bar the early -> late edge for each BnVar. These variables will invariably be connected in cases where each variable nearly always exists in either early or late stage

author

- nicos angelopoulos

version

- 0.1 2017/5/22

 gbn_gates_net(DotF)

 gbn_gates_net(+DotF, +Opts)

From a BN DotF(ile) create a logic gates BN dot file, that inscribes the logic gates of the BN in DotF with those found in the associated GatesF (see options below). All fitted gates are already in the per-family gate files, GatesF, here we simply chose the "best" gate from each family.

Currently, this is the gate with smallest p.value. Ignoring direction seems the best default.

If no output file is given, it is constructed from DotF by postfixing (os_postfix/3) gates_best to the filename.

Opts

directed(Dir=false)

whether to include edge directions

edge_theme(Etheme=jyoti)

edge theme (the original can be found at four_clrs)

format(Fmt=svg)

any value other than false, attempts to run upsh dot format=Fmt <lgBN.dot> on the generated dot file

gates(GatesF)

when GatesF is missing, it is guessed from DotF. First, a missing GatesF <DotStem>_gates_best.csv and if that does not exist as <DotStemMinus_fclr>_gates_best.csv. If a variable is used as input, the used file is returned.

out(Out)

can be used to either set the output, logic-gated, dot file, or to return the created filename (var(Dot))

author

- nicos angelopoulos

version

- 0.1 2017/08/16

- 0.2 2017/10/02 lib(options)

 gbn_gates_nets

 gbn_gates_nets(+Opts)

Run gbn_gates_net/1 on all dot files in Dir (default is '.').

Opts

dir(Dir=(.))

set working directory

author

- nicos angelopoulos

version

- 0.1 2017/09/22

 gbn_svg_legend(Opts)

A simple gbn shell to svg_legend/1.

Opts See svg_legend/1.

?-

author

- nicos angelopoulos

version

- 0.1 2018/2/26

See also

- svg_legend/1

 gbn_mtx_mins(+MtxF, -Files, +Opts)

Create a number of matrix Files, curved out of input file MtxF. A file is generate for each integer in Mins. The file in corresponding Min value is that which only contains columns with at least Min number of 1s.

Files can be partially instantiated, to dictate the number of returned files.

Use debug(mtx_mins) to display the Min cutoffs, and the size of each matrix.

Opts mins(Mins=[_,_,_,_,_]) If ground, a list of the Mins to consider. if non-ground, returns those that were generated (can be a vars list to pass the implied Len) from(From=5) starting point for Mins, when generating them by(By=5) step length(Len=5) if Mins is a variable, use this to determine length of Mins

?-

author

- nicos angelopoulos

version

- 0:1 2019/3/24

To be done

- debug() option in options_append/4 understands gbn(mtx_mins) ?