R Gateway Support

The R Gateway is an extension of the Java External Server. It incorporates two third-party packages: R-Engine is a Java client for the Rserve TCP/IP server, which connects to an R interpreter. This allows InterSystems IRIS to access the R interpreter via the External Server gateway.

Once the R-Engine Java client is connected to Rserve and the R gateway is running, you can execute R statements just as you can with any other supported External Server language (see Using InterSystems External Servers for more information).

R Gateway System

Diagram: %R_server Gateway<->TCP/IP<->Java R-engine client<->Rserve binary server<->TCP/IP<->R

Note:

Known Limitations

Java differentiates empty string and null string, while the InterSystems IRIS database does not. The Java client maps both Java null and Java empty string to database empty string. InterSystems IRIS empty strings are mapped to Java null. To avoid problems, do not assign different meanings to empty and null strings.

Installing R and RServe

Requirements

Java 8 or higher
InterSystems IRIS 2020.4 or later. The following required resources are included with InterSystems IRIS:
- the InterSystems %R_Server External Server is installed automatically (see “Controlling Connections with the Management Portal” in Using InterSystems External Servers)
- the org.rosuda.REngine package is included in intersystems-rgateway-<version>.jar and used by the External Server.
recent instance of R (https://cloud.r-project.org/)
- RServe (http://www.rforge.net/Rserve) must be installed from the R Console (as described below)

Note:

The R Gateway described in this document connects to RServe via the Java org.rosuda.REngine package and the %R_Server External Server gateway. An older ObjectScript-based RServe interface is also available (https://github.com/intersystems-community/RGateway), but is not officially supported by InterSystems.

Install R interpreter

Download and install the latest version of R: https://cloud.r-project.org/. Be sure to make R accessible to all users.

Install Rserve server

Rserve is a TCP/IP server which allows other programs to use facilities of R (see http://www.rforge.net/Rserve/index.html).

Set environment variable R_LIBS to a directory accessible to all users. This is to make sure Rserve package is available to all users after installation. Details can be found at https://cran.r-project.org/doc/manuals/R-admin.html#Managing-libraries
Start R Console.
Inside R Console, run install.packages(“Rserve”,,"http://rforge.net")
If prompted to install from sources, answer "Yes". Please refer to Rserve documentation for more details.

Running the R Gateway

Launch Rserve

Rserve can be started manually on any host and port. It can also be launched programmatically from InterSystems IRIS on the localhost.

To start Rserve manually, type the following commands in the R Console:

library(Rserve)
Rserve()

If unsuccessful, try Rserve(args="--no-save --slave") . Please refer to Rserve documentation for more details.

To launch Rserve programmatically from IRIS, issue the following command:

Do ##class(%Net.Remote.Object).%ClassMethod(gateway,"com.intersystems.rgateway.Helper","launchLocalServer", port)

Start R Gateway

R Gateway can be started from Management Portal: System->Configuration->Connectivity->External Language Servers. A new R Gateway can also be created from this page.

See the %R Server entry in the Configuration Parameter File Reference for a description of the %R Server parameters found in the [Gateways] section of the CPF.

Create RConnection

RConnection is the interface between Rserve and the R interpreter. Each RConnection corresponds to a R session. Each R session has its own memory space. R sessions are not thread-safe. On UNIX machines, multiple RConnections can be created on a single port. On Windows machines, a single port can only support a single connection. Multiple Windows connections can be established using one port for each connection.

If Rserve is running, RConnection can be created directly:

set c = ##class(%Net.Remote.Object).%New(gateway,"org.rosuda.REngine.Rserve.RConnection")

If you are not sure whether Rserve is running, you can use the helper class to start it automatically. If Rserve is not running, it will try to start it locally and return an instance of RConnection:

set c = ##class(%Net.Remote.Object).%ClassMethod(gateway,"com.intersystems.rgateway.Helper","createRConnection")

Note that the above calls can take additional parameters, such as host name, port number etc.

External Server commands ($SYSTEM.external)

$SYSTEM.external (the ObjectScript External Server interface) supports the R Gateway.

To get the default R Gateway (named "%R Server"): set gateway = $SYSTEM.external.getRGateway()
To get a named R Gateway: set gateway = $SYSTEM.external.getGateway(name)
Type “do gateway.Help()” in an IRIS terminal for the usages.

Note:

See Using InterSystems External Servers for more information about $SYSTEM.external.