b_real.pl -- Interface predicates to commonly used R functions.

Interface predicates to commonly used R functions. This library allows Prolog users to do same simple tasks in R with out writing any R code or call any R functions explicitly.

Dependancies

pack(real)
obviously
aheatmap/2
depends on R library "NMF"
pack(mtx)
some side predicates depend on private pack mtx which should become public soon
author
- nicos angelopoulos
version
- 0.1.0 2015/6/17
- 0.1.1 2015/7/24, added gg_bar_plot/2, then on 12/16 added pl_plot_on/2.
- 0.2 2016/1/23
- 0.3 2017/3/11, works with lib 2.0 and stoics_lib
- 0.4 2017/4/25, fixes + r_hist/2.
b_real
Documentation predicate. Anchor reference to the package to this predicate.
b_real_version(-Version, -Date)
Version (Mj:Mn:Fx) and date and of publication (date(Y,M,D))>
?- version( Vers, Date ).
Vers = 0:4:0,
Date = date(2017, 4, 25).
aheatmap(+Csv)
aheatmap(+Csv, +Opts)
Generic aheatmap plots with aheatmap.2 from NMF. Csv can be a mtx/1 recognised matrix or an R variable.

note that standard version of aaheatmap() has a bug when breaks and colours are given: https://github.com/renozao/NMF/issues/12 2014/08/12

Opts

centre(Centre=false)
1.0 or 0.0, or non number for not centering
cellheight(32)
height of the cell
cellwidth(8)
width of the cell
rvar(hm_data)
the R variable on which to load the data (if Csv is not an R var itself
hp_token(pastel_ryg)
hmap([])
aheatmap() call additional parameters given in Name(Value) syntax
scale(true)
should we scale ?
rowV(RowV=true)
do not use a rows dendrogram
colV(ColV=true)
do not use a columns dendrogram

?- Mpg <- mtcars$mpg, aheatmap( Mpg, [rowV(false),colV(false)]  ).
?- Mpg <- mtcars$mpg, x <- [Mpg], colnames(x) <- rownames(mtcars),
    aheatmap( x, [cellheight=32,scale(false),rowV(false)]  ).
author
- nicos angelopoulos
version
- 0.1 2014/5/18
lm_plot(+Vect1, +Vect2, +Opts)
Create a scatter plot for vectors Vect1 and Vect2 (pl_vector/2) along with fitting a linear model.

Pval is the anova p.value of Clm2 ~ Clm1, Coef is the coefficient of the regression, R2 is R squared (coefficient of determination). See options.

Opts

Ropt = Rval
pairs are passed to the plot call (via r_call/2) (defaults for main, xlab, ylab and col provided)
coef(Coef)
return value of the coefficient
max_frac(MxFrac=4)
maximum number of fractional part
mtx(Mtx)
used if Vect1,2 are not lists, see pl_vector/2
outputs(Outs)
outputs to produce, see r_call/2
pval(Pval)
return value of the p value
r2(R2)
return value of the R2
stem(Stem)
stem for any output files (see r_call/2)
RcallOpts
options supported by r_call/2
  ?- mtx_data( mtcars, Mt ),
     lm_plot( mpg, disp, mtx(Mt) ).
  
  ?- assert( lm_mtx( [row(a,b,c),row(1,2,3),row(2,3,4),row(3,4,5)] ) ).
  ?- lm_mtx( Mtx ), lm_plot( a, b, C, R2, P, mtx(Mtx) ).
  C = 1.0,
  P = 0.0.
  
  ?- lm_mtx(Mtx),
     lm_plot(Mtx,a,b,C,R2,P,true,).

  C = 1.0,
  P = 0.0.
 
  ?- ls.
  what.png
  ?- use_module( library(by_unix) ).
  ?- @ eog(what.png).
author
- nicos angelopoulos
version
- 0.1 2014/6/30
- 0.1 2014/1/23, mtx updates + R2
gg_bar_plot(+Pairs, +Opts)
Plot a bar plot of population Pairs (Name-Populations).
Opts is a combination of options controlling the predicate as per normal Prolog convention, and term structures thmove( false, _Df ). gg_bar_plot_rvar_remove( true, Df ) :- <- remove( Df )at translate to '+' ggplot2 terms.

Originally this only supported lists at the value part of Pairs. Now single values make the predicate plot a non-grouped barplot.

Opts

bar_draw_colour(Bdc=white)
draw colour for bars
debug(Dbg=false)
true turns debugging on
df_rvar(Df=gbp_df)
data frame R variable
df_rvar_rmv(DfR=true)
remove Df after call
extra_legend(XtLeg=false)
adds extra legend
extra_legend_position(Xn, Xx, Yn, Yx)
position for extra legend
fill_colours(Clrs=true)
false removes scale_fill_manual() term, true use def. colours, else give list of colours
flip(Flip=true)
flip coordinates
geom_bar(Gb=true)
false removes removes geom_bar() term
geom_bar_draw_colour(Gc=white)
colour for bar outlines
geom_bar_position(Gp=dodge)
or stack; positions bars
gg_terms([])
arbitrary terms to add to the plot
labels(X, Y, Main)
X='',Y='',Main='', if Flip==true then you should also swap X with Y here
legend_reverse(Lrv=true)
reverse legend order (Lrv=false when Flip=false)
legend_title(Lt)
legend title ([] for default ggplot2() one). only works for Clrs \== false
legend_labels(Ll=[])
labels for legend (only valid if colours are given)
keep_order(Kord=true)
display x axis according to given order (else, passes through sort)
output(Outp=false)
else send a R command such as pdf("myfile.pdf")
?- Pairs = [a-[1,2,3],b-[2,4,6]], gg_bar_plot( Pairs, true ).

?- FClrs = ["gold1", "#E31A1C", "blue1"],
BoldTitle = theme(plot.title(element_text(face(+"bold")))),
Pairs = [a-[1,2,3],b-[2,4,6]],
gg_bar_plot( Pairs, [debug(true), geom_bar_draw_colour(black), labels(x,y,main), fill_colours(FClrs), gg_terms(BoldTitle),legend_title(leeg)] ).

?- Pairs = [a-1,b-2,c-3,d-4], gg_bar_plot( Pairs, [flip(false),geom_bar(empty)] ).
?-  FClrs = ["gold1", "#E31A1C"], Pairs = [a-1,b-2,c-3,d-4],
gg_bar_plot( Pairs, [flip(false),geom_bar(empty),fill_colours(FClrs)] ).
author
- nicos angelopoulos
version
- 0.1 2014/10/21
- 0.2 2016/01/23
- 0.3 2016/08/31, added singleton groups as normal barplots
vectors_subed_gg_bar_plot(+Vectors, +Val, +Vect2, +Opts)
Plot frequencies of a value in Vectors with subdivisions for each of the values apppearing in Vect2. All vectors are defined relative to Mtx.

Opts

sort(Sort=false)
else true (lexicographical), or totals for total counts
mtx(Mtx)
matrix to extract the vectors from
Mtx = [  row(v,x,y,z),
         row(1,0,0,a),
         row(0,0,1,a),
            row(0,1,1,b),
            row(1,1,1,b),
            row(0,1,0,c)
      ],
assert( ex1(Mtx) ).

?- ex1(Mtx), vectors_subed_gg_bar_plot( [v,x,y], 1, z, mtx(Mtx) ).
[[1,1,0],[0,2,1],[1,2,0]]
author
- nicos angelopoulos
version
- 0.1 2015/11/25
See also
- pl_vector/3
- vector_factor_indices/3
mtx_pheatmap(+Mtx, +OptS)
Plots the data in Mtx using pheatmap() from omonymous package. See mtx_column_pheatmap/3. Here we print vertically though.

Opts

Ropt = Rarg
pass Ropt=Rarg to the pheatmap() R call
rvar(Rvar=mtx_heatmap)
R variable to use
names(Names=[])
list of names or column id

Predicate uses r_call/2 which takes its own options.

Dependencies

 ?- pack_install( real ).
 ?- use_module( library(real) ).
 ?- install.packages( "pheatmap" ).

Examples

 ?- use_module( library(real) ).
 ?- <- write.csv( mtcars, "mtcars.csv" ).  % mtcars is an example dataset in R
 ?- <- csv_read_file( Mt, 'mtcars.csv' ), assert( mt(Mt) ).
 ?- mt(Mt), mtx_pheatmap( Mt, [names(1),scale="column"] ).
 ?- mt(Mt), mtx_pheatmap( Mt, [names(1),scale="column",debug(true)] ).
author
- nicos angelopoulos
version
- 0.1 2015/1/13
See also
- http://cran.r-project.org/web/packages/pheatmap/pheatmap.pdf
To be done
- centre around value (balanced and unbalanced // interval)
mtx_column_pheatmap(+Mtx, +Cid, +Opts)
Plot pheatmap of column Cid (mtx_column/4) of matrix Mtx (mtx/2).

This is mainly constructed as a demonstration of using R's pheatmap function from the omonymous library (http://cran.r-project.org/web/packages/pheatmap/pheatmap.pdf).

Opts

 ?- use_module( library(real) ).
 ?- <- write.csv( mtcars, "mtcars.csv" ).  % mtcars is an example dataset in R
 ?- csv_read_file( 'mtcars.csv', Mt ), mtx_column_pheatmap( Mt, 2, [] ).
 ?- csv_read_file( 'mtcars.csv', Mt ), mtx_column_pheatmap( Mt, 2, [names(1)] ).
 ?- csv_read_file( 'mtcars.csv', Mt ), mtx_column_pheatmap( Mt, 2, [names(1),legend='TRUE'] ).
 ?- csv_read_file( 'mtcars.csv', Mt ), mtx_column_pheatmap( Mt, 2, [names(1),outputs(pdf),stem(mtcars_c2)] ).
 ?- shell( 'ls -l mtcars_c2.pdf' ).
 -rw------- 1 user user 4212 Jan 13 13:56 mtcars_c2.pdf
author
- nicos angelopoulos
version
- 0.1 2014/1/7
See also
- http://cran.r-project.org/web/packages/pheatmap/pheatmap.pdf
- mtx_column/3
- mtx/2
To be done
- remove NAs, with reprecations to names()
options_rvar_rmv(+Rvar, +Opts)
r_remove/1 R variable Rvar iff rvar_rmv(true) is in Opts.

The rationale is to make rvar_rmv(_) a commonly occured option in b_real predicates.

 ?- x <- 1.
 ?- <- x.
 [1] 1
 true.
 ?- options_rvar_rmv( x, [rvar_rmv(true)] ).
 ?- <- x.
 Error in print(x) : object 'x' not found
 ERROR: R was unable to digest your statement, either syntax or existance error
 ?- x <- 1.
 ?- options_rvar_rmv( x, [rvar_rmv(false),debug(true)] ).
 % Keeping R variable: x
 true.
author
- nicos angelopoulos
version
- 0.1 2015/1/15
To be done
- debug messages via options_debug/3 library(options_debug)
pl_vector(+VectSpec, -Vect, +Opts)
True iff VectSpec is a regognisable representation of a vector whose canonical representation (a list) is Vect. Through Options you can also control max and min values.

Recognisable represenation are:

list
which is also the canonical representation
Cid
when memberchk(mtx(MTx),Opts) and mtx_column( Mtx, Cid, Vect )

Opts

 ?- pl_vector( [1,2,3], V, true ).
 V = [1, 2, 3].
 
 ?- mtx_data( mtcars, Mc ),
    pl_vector( 1, Vect, [mtx(Mc),cnm(Cnm)] ),
    max_list( Vect, Max ).

 Mc = [row(mpg, cyl, disp, hp, drat, wt, qsec, vs, am, gear, carb), row(21.0, 6.0|...],
 Vect = [21.0, 21.0, 22.8, 21.4, 18.7, 18.1, 14.3, 24.4, 22.8|...],
 Cnm = mpg,
 Max = 33.9.
 
 ?- mtx_data( mtcars, Mc ),
    pl_vector( 1, Vect, [mtx(Mc),cnm(Cnm),max(30)] ),
    max_list( Vect, Max ).
 
 Mc = [row(mpg, cyl, disp, hp, drat, wt, qsec, vs, am, gear, carb), row(21.0, 6.0|...],
 Vect = [21.0, 21.0, 22.8, 21.4, 18.7, 18.1, 14.3, 24.4, 22.8|...],
 Cnm = mpg,
 Max = 30.
author
- nicos angelopoulos
version
- 0.2 2016/6/7, added where() and k(),v() pairs
See also
- pl_vector_curtail/3,4
To be done
- add to real ? but it needs mtx ...
vector_scale(+VectSpec, -Scaled, +Opts)
This is a funnel predicate that can be used to scale a vector (VectSpec) through options. Scaled should be something Real (pack(real)) understands as a LHS to <- assignment. That is, if it is a Prolog variable, it will be instantiated to the vector as a list, or a ground term, will translate that to an R expression (typically an R variable) to which the scaled vector is assigned to.

For details on VectSpec, see pl_vector/3 and options affecting this.

Opts

See R's scale().

?- Mtc <- as.vector( mtcars[*,3] ), Mean <- mean(Mtc), vector_scale( Mtc, Sca, [scale(true)] ),
   ScaMean <- mean(Sca), ScaVrc <- var(Sca).

Mtc = ...
Mean = 230.721875,
Sca = ...
ScaMean = -9.084936579070724e-17,
ScaVrc = [[1.0]].

?- Mtc <- as.vector( mtcars[*,3] ), Mean <- mean(Mtc), vector_scale( Mtc, Sca, [scale(centre)] ),
   ScaMean <- mean(Sca), ScaVrc <- var(Sca).

Mtc = ...
Mean = 230.721875,
Sca = ...
ScaMean = -1.199040866595169e-14,
ScaVrc = [[15360.799828629033]].
author
- nicos angelopoulos
version
- 0.1 2015/7/17
pl_plot_on(+Goal, +On)
Call Goal while recording (R) output to On. On should be wrappend in plot_on/1, else it is ignored silently. As per order, this execution allows maplisting options through this predicate. Goal is called once for plot_on, in that scenario. If On's term/atom name is x11, or its == open, then the device is left open otherwise r_devoff/0 is called.
 ?- pl_plot_on( <- plot(c(1,2,3)), plot_on(x11()) ).
 ?- pl_plot_on( <- plot(c(1,2,3)), plot_on(pdf(+ex.pdf)) ).
 ?- shell( 'evince ex.pdf' ).
 ?- pl_plot_on( <- plot(c(1,2,3)), plot_on(x11(width=14)) ).
author
- nicos angelopoulos
version
- 0.1 2015/12/16
To be done
- move this to Real ?
r_mtx(+Rvar, ?Mtx)
r_mtx(+Rvar, ?Mtx, +Opts)
Load Mtx onto Rvar and vice versa. Mtx is passed through mtx/2 and also can be of Real matrix form, which is a list of lists. Rows in mtx/2 are of the form of a list of n-ary compounds (as in csv/3).

Opts

rownames(Rnames=integer)
number indicates column position, list for given names and integer for auto naming 1...n .
header(Hdr=true)
whether the file incorporates a header
colnames(Cnames=header)
or list for given names or integer for 1...n. If Cnames is header and Hdr is false, integer column names are used.
debug(Dbg=false)
or true for self debugging call. Note that false turns off, not just ignore and that in both cases original debugging status is re-instated at end of call.
 ?- mtx_data( mtcars, Mt ), r_mtx( rv, Mt, [debug(true),rownames(1)] ).
 ...
author
- nicos angelopoulos
version
- 0.1 2014/8/20
To be done
- add generic selection predicate(s) rows + columns with/out renames for columns and rows).
- add reading through R's read.csv()/read.table()
- the Rvar -> Mtx mode !
r_data_frame(+DfIn, +Df)
Convert DfIn to an R data frame.

If DfIn, is an R variable, and Df is atomic it is assumed to be a data frame and Df <- DfIn, is called (this can be elaborated upon later), whereas if Df is variable then Df = DfIn is called.

If DfIn is not an R variable, it is passed through mtx/2 and the result is passed through mtx_df/2. When Df is a variable in this context, a unique variable is generated that looks like tmp.df.N where N is an integer.

@ see mtx/2 @ see mtx_df/2 @ see r_mtx/3

r_unique(+Stem, -Unique)
Create a Unique R variable of the form Stem.N where N is an integer. The value 'NA' is passed to the variable.
?- r_unique( df.data, Uniq ).
Uniq = df.data.1.

?- r_unique( df.data, Uniq ).
Uniq = df.data.2.
r_hist(+VectSpec, +Opts)
Plots a histogram or density of an arithmetic vector.

VectSpec should be as that recognised by the 1st argument of pl_vector/3. A list is the simplest representation of a vector.

Displaying is via r_call/2, so Opts can influence that call.

Opts

as_density(AsDense=false)
when true it plots the density instead of the histogram
name(Name)
set Name (string or +atom) default value for x-axis and main labels
transparency_colour(TransClr="lightblue")
colour for the density, transparency colour
transparent(Trans=true)
use transparent colour to highlight density (currently only with AsDens=true)
?- lib(real).
?- Mtc <- as.matrix(mtcars), r_hist( 2, mtx(Mtc) ).
?- rns <- rnorm(1000).
?- Rns <- rns, r_hist( Rns, name("rnorm") ).
?- Rns <- rns, r_hist( Rns, [name("rnorm"),main="Main Title",outputs(svg),stem(rh1)] ).

Produces file: rh1.svg

?- rnsm <- rnorm(10000), r_hist( rnsm, true ).
?- r_hist( rnsm, as_density(true) ).
?- pl_vector( rnsm, Rnsm, if_rvar(prolog) ), r_hist( Rnsm, name(+true) ).
?- r_hist( rnsm, [as_density(true),transparent(false)] ).
?- r_hist( rnsm, [as_density(true),transparency_colour("lightgreen"),outputs(svg),stem(rh2)] ).

Produces file: rh2.svg

author
- nicos angelopoulos
version
- 0.1 2017/4/25
columns_fisher_test(+Data, +Inters, +Odds, -Lods, +Opts)
Perform pairwise Fisher tests on the columns of Data (mtx/1).

Opts

plot(Plot=false)
whether to plot the test results
plot_on(PlotOns)
see pl_plot_on/2, multiple allowed- but Plot needs to be true for them to fire
?- cd( '/usr/local/users/nicos/work/2015/15.11.04-hmrn/Exploristics/data' ).
?- columns_fisher_test( hmrn_muts_t10.csv, inters, odds, Lods, [plot(true),plot_on(x11()),plot_on(pdf())] ).
author
- nicos angelopoulos
version
- 0.1 2015/12/16
dot(+StemS, +ExtS, -Dotted)
Create a dotted amalgamation (atom_concat-enation) of StemS and ExtS. Both can be atomic or lists.
Note that at_con/3 is used so '' is handled differently to atomic_list_concat/3.
?- dot( tmp, rv, Dot ).
Dot = tmp.rv.

?- dot( [tmp,rv], phase1, Dot ).
Dot = tmp.rv.phase1.

?- dot( '', x, Dot ).
Dot = x.

?- dot( x, ['',x], Dot ).
Dot = x.x.
author
- nicos angelopoulos
version
- 0.1 2015/12/16
mtx_df(-Mtx, +Df, +Opts)
mtx_df(+Mtx, +Df)
Mtx is the csv representation of R data frame Df.

Opts

check_names(ChNames=true)
in R the default is also true
?- mtx_df( [row(a,b,c),row(1,2,3),row(4,5,6)], df1 ),
   <- df1,
   csv_df( Csv1, df1 ).
 
$a
[1] 1 4
 
$b
[1] 2 5
  
$c
[1] 3 6

Csv1 = [row(a, b, c), row(1, 2, 3), row(4, 5, 6)].
  

This seems to get stuck for very large matrices, (>130,000). See implementation in r_sqlite_load.pl .

author
- nicos angelopoulos
version
- 0.1 2014/6/19
- 0.2 2015/12/14, added options (check_names/1)