# 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'