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

Run the BN learning algorithm gobnilp.

Assumes gobnlip is in your path. Currently only tested on *nix based systems.

?- 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-20.09.27'
% 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.

author

- nicos angelopoulos

See also

- 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

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

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

To be done

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

 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_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=_12604)

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

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:

cellwidth(Cw=1)

cell width

cellheight(Ch=12)

cell height

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)

x11(X11B)

defaults to false if SSH_TTY is defined OS variable, and true otherwise; passed to mtx_mut_hmap/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_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

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

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) ?

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 gbn(Arg1)

 gbn_prefix_directed_constraints(Arg1, Arg2, Arg3, Arg4)

 gbn