Interfaces/R/Rserve/Extensions

(This page is preliminary and comments are solicited.)

Locales

In general, verbs to call specific R commands should be created in locales named "R" followed by the corresponding R library name, for example, Rsplines for the R splines library. These locales should extend the rbase locale.

Names

Verb names should match the corresponding R function name, or near equivalent. Dots in R names should be replaced with an underscore.

Arguments

R functions often have many optional arguments, though not all of these need be supported by the J verb. Here are two ways that the argument list might be handled:

• the argument is a specific list of values that must be given in order
• the argument is a package (table of name;value pairs) that needs only non-default values. In this case, the default values must be previously defined in the verb.

For example, the bs function in the R splines library generates the B-spline basis matrix for a polynomial spline. The R usage is:

bs(x, df = NULL, knots = NULL, degree = 3, intercept = FALSE, Boundary.knots = range(x))
Arguments
 x          the predictor variable. Missing values are allowed.
 df         degrees of freedom...
 knots      the internal breakpoints that define the spline...
 degree     degree of the piecewise polynomial, default 3
 intercept  if TRUE, an intercept is included in the basis; default is FALSE.
...

Corresponding J definitions might be:

NB. bs1 argument is x and df only:
bs1=: 3 : 0
'x df' rdset y
...
)

NB. bs2 argument is a package, which must have at least name x:
bs2=: 3 : 0
df=. 3
degree=. 3
intercept=. 0
({."1 y)=. {:"1 y
...
)

Calling R

A sequence of calls is needed to configure the R environment, and define the required variables. These calls should be wrapped in a try./catcht. block:

bs1=: 3 : 0
try.
  rdcmd 'library(splines)'
  'x df' rdset y
  res=. rdcmdr 'bs(x,df)
catcht.
  wdinfo 'Splines Library';throwtext_rserve_
  res=. _1
end.
res
)

Complete Example

The following script creates the Rsplines locale and defines bs1 and bs2 verbs as above:

NB. example of R extension

coclass 'Rsplines'
coinsert 'rbase'

NB. bs1 - generate the B-spline basis matrix for a polynomial spline.
NB. argument is numeric list and degrees of freedom
NB. returns the matrix
bs1=: 3 : 0
try.
  rdcmd 'library(splines)'
  'x df' rdset y
  res=. rdget 'bs(x,df=df)'
catcht.
  wdinfo 'Splines Library';throwtext_rserve_
  res=. _1
end.
'data' rgetmap res
)

NB. bs2 - generate the B-spline basis matrix for a polynomial spline.
NB. argument is package, where
NB. value x must be given
NB. values df, degree and intercept are optional
bs2=: 3 : 0
df=. 3
degree=. 3
intercept=. 0
({."1 y)=. {:"1 y
arg=. x;df;degree;intercept
try.
  rdcmd 'library(splines)'
  'x df deg int' rdset arg
  res=. rdget 'bs(x,df=df,degree=deg,intercept=int)'
catcht.
  wdinfo 'Splines Library';throwtext_rserve_
  res=. _1
end.
'data' rgetmap res
)

Examples of calling these verbs:

1. Argment is a pair: values;degrees of freedom:

bs1_Rsplines_ (p: i.7);3

2. Argument is a package of non-default values:

x=. p: i. 7
degree=. 4
intercept=. 1
bs2_Rsplines_ pack 'x degree intercept'