com.jstatcom.engine.rstat
Class RStatEngine

java.lang.Object
  extended by 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