com.jstatcom.engine.rstat
Class RStatEngine

java.lang.Object
  com.jstatcom.engine.rstat.RStatEngine

All Implemented Interfaces:

Engine

public final class RStatEngine
extends java.lang.Object
implements Engine

Engine for calling R via JGR (www.rosuda.de/JGR). Access to the R engine is not synchronized by this class. This class is not thread-save. Synchronization must be managed externally, a convenient and save way to do this is to use the PCall class which provides an executor thread that automatically schedules procedure calls to R.

Using the stop method:
The only save thread-save interaction method with this object is the stop method. This is always called from a thread different from the one invoking load or call. If R is currently blocking, then the current operation is stopped and a runtime exception is thrown, indicating that an operation was stopped. If the stop method is invoked when R is not blocking, nothing happens.

Usage example:

 // call to plot function, no return parameters
 Engine rStat = EngineTypes.RSTAT.getEngine();
 rStat.load("JGR", RStatLoadTypes.RPACKAGE);
 JSCData y = new JSCNArray("y", UMatrix.rndu(7, 1));
 rStat.call("JavaGD", null, null);
 rStat.call("plot", new JSCData[] { y }, null);
 
 // call to lm function with generated nonsense data, getting coeffs back
 JSCData dat = new JSCNArray("dat", UMatrix.rndu(50, 4));
 dat.setJSCProperty(RArgProps.PARAM_NAME, "data");
 dat.setJSCProperty(RArgProps.DFRAME_VARNAMES,
         new String[] { "a", "b", "c", "d" });
 JSCData expr = new JSCString("expr", "a˜b + c + d");
 expr.setJSCProperty(RArgProps.AS_FORMULA, true);
 expr.setJSCProperty(RArgProps.PARAM_NAME, "formula");
 JSCNArray coeff = new JSCNArray("coeff");
 coeff.setJSCProperty(RArgProps.RLIST_KEY, "coefficients");
 rStat.call("lm", new JSCData[] { expr, dat }, new JSCData[] { coeff });
 

Author:

Markus Kraetzig

Method Summary

void	call(java.lang.String procName, JSCData[] args, JSCData[] retData) Invokes an R function with input and return parameters.
static java.lang.String	checkValidRNameThrowEx(java.lang.String name) Throws IllegalArgumentException exception if name is not a valid R symbol.
static RStatEngine	getInstance() Returns an instance of the RStatEngine that is a Singleton.
org.rosuda.JRI.Rengine	getRengine() Gets the underlying instance of Rengine.
boolean	isValid(JSCTypes type) Gets whether type can be handled by this engine.
static java.lang.String	isValidRName(java.lang.String name) Checks whether name conforms to the standards for R symbols as described in the R manual.
void	load(java.lang.String module, LoadTypes loadType, JSCData... args) Loads an R module, two cases are available: 1) loadType == RStatLoadTypes.RPACKAGE calls library(module) in R, the module must be installed for R 2) loadType == RStatLoadTypes.USERCODE expands module to a pathname relative to .
void	shutdown() Terminates this engine and does clean up tasks.
void	stop() Stops a running execution.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static RStatEngine getInstance()

Returns an instance of the RStatEngine that is a Singleton.

Returns:

an engine instance

Throws:

java.lang.RuntimeException - if something goes wrong on init

call

public void call(java.lang.String procName,
                 JSCData[] args,
                 JSCData[] retData)

Invokes an R function with input and return parameters.

Input arguments:
The type and number of input arguments should be valid for the R procedure to be called. Because in R it is possible to use named parameters (e.g. seq(from = 1, to = 1)) these can be specified via setting the RArgProps.PARAM_NAME property via JSCData.setJSCProperty. If this property is not set, only the position of a variable in args is used. A combination of named parameters and positions is possible.

Formulas:
By setting the RArgProps.AS_FORMULA property of a JSCString input argument to true, a string argument will be interpreted as an R formula in this method (as.formula will be called). For all other types of JSCData this property will be ignored. For example, this feature may be used to call the R procedure lm, which takes a formula argument to specify a linear model.

Return arguments:

1. If the R routine returns an R NIL value (not Java null which is an error) value then all elements of retData are cleared. This might indicate a special intended return value.
2. A single non R NIL non R LIST return argument in R must correspond to a return array retData of length one and of compatible type.
3. If an R LIST is returned then the names of the elements of retData are taken to be the list keys by default. This can be changed by using the RArgProps.RLIST_KEY properties on the elements of retData. If non null they are used as list keys instead (recommended). All returned R values must be compatible with the corresponding JSCData types if the elements of retData.

Specified by:

call in interface Engine

Parameters:

procName - name of the R procedure to call

args - input arguments, null if no arguments needed

retData - return arguments, null if nothing is returned or returns not of interest

Throws:

IllegalArgumentException - if procName is not a valid R symbol
if an element of either args or retData is null
RuntimeException if R computation fails

isValid

public boolean isValid(JSCTypes type)

Description copied from interface: Engine

Gets whether type can be handled by this engine.

Specified by:

isValid in interface Engine

Parameters:

type - the data type to be checked

Returns:

true if ok, false if type cannot be handled by this engine

See Also:

Engine.isValid(com.jstatcom.model.JSCTypes)

load

public void load(java.lang.String module,
                 LoadTypes loadType,
                 JSCData... args)

Loads an R module, two cases are available:

1) loadType == RStatLoadTypes.RPACKAGE

calls library(module) in R, the module must be installed for R

2) loadType == RStatLoadTypes.USERCODE

expands module to a pathname relative to ./jrstat, e.g. foo.R is expanded to ./jrstat/foo.R, then the file is loaded to a string which is then evaluated by R. This means that file must only contain a single function definition, typically the function name should be similar to module, but does not have to.

Specified by:

load in interface Engine

Parameters:

module - R package name or filename relative to ./jrstat

loadType - one of RStatLoadTypes

args - currently ignored

Throws:

exception - if something is fishy

stop

public void stop()

Description copied from interface: Engine

Stops a running execution. If there is nothing to do for this engine, this method must throw an UnsupportedOperationException.

Specified by:

stop in interface Engine

See Also:

Engine

shutdown

public void shutdown()

Description copied from interface: Engine

Terminates this engine and does clean up tasks. Whenever a load or execute is called afterwards this engine should be reinitialized.

Specified by:

shutdown in interface Engine

See Also:

Engine.shutdown()

getRengine

public org.rosuda.JRI.Rengine getRengine()

Gets the underlying instance of Rengine. This can be used to invoke additional lower-level R interface methods directly on instances of that class. The status of this engine is not checked when this method is called, it might be null or exitted.

Returns:

JRI Rengine instance

isValidRName

public static java.lang.String isValidRName(java.lang.String name)

Checks whether name conforms to the standards for R symbols as described in the R manual. If there is any violation the error message is returned, otherwise null.

Parameters:

name -

Returns:

null if ok, otherwise error

checkValidRNameThrowEx

public static java.lang.String checkValidRNameThrowEx(java.lang.String name)

Throws IllegalArgumentException exception if name is not a valid R symbol. But if name == null then null is returned.

Parameters:

name -

Returns:

trimmed name

Throws:

java.lang.IllegalArgumentException - with error message if it does not conform