README
¶
Roger
Roger is a Go RServe client, allowing the capabilities of R to be used from Go applications.
The communication between Go and R is via TCP. It is thread safe and supports long running R operations synchronously or asynchronously (using channels).
package main
import (
"fmt"
"github.com/senseyeio/roger"
)
func main() {
rClient, err := roger.NewRClient("127.0.0.1", 6311)
if err != nil {
fmt.Println("Failed to connect")
return
}
value, err := rClient.Eval("pi")
if err != nil {
fmt.Println("Command failed: " + err.Error())
} else {
fmt.Println(value) // 3.141592653589793
}
helloWorld, _ := rClient.Eval("as.character('Hello World')")
fmt.Println(helloWorld) // Hello World
arrChan := rClient.Evaluate("Sys.sleep(5); c(1,1)")
arrResponse := <-arrChan
arr, _ := arrResponse.GetResultObject()
fmt.Println(arr) // [1, 1]
}
Response Type Support
Roger currently supports the following response types from R:
- string and string arrays
- booleans and boolean arrays
- doubles and double arrays
- ints and int arrays
- complex and complex arrays
- lists
- raw byte arrays
With the use of JSON, this capability can be used to transfer any serializable object. For examples see sexp_parsing_test.go.
Assignment Support
Roger allows variables to be defined within an R session from Go. Currently the following types are supported for variable assignment:
- string and string arrays
- byte arrays
- doubles and double arrays
- ints and int arrays
For examples see assignment_test.go.
Setup
Rserve should be installed and started from R:
install.packages("Rserve")
require('Rserve')
Rserve()
More information is available on RServe's website.
If you would like to exploit the current R environment from go, start RServe using the following command:
install.packages("Rserve")
require('Rserve')
run.Rserve()
Install Roger using:
go get github.com/senseyeio/roger
Testing
To ensure the library functions correctly, the end to end functionality must be tested. This is achieved using Docker and Docker Compose. To run tests, ensure you have both Docker and Docker Compose installed, then run docker-compose build && docker-compose up -d from within the test directory. This command will build and start a docker container containing multiple RServe servers. These servers will be utilized when running go test from the project's base directory. To stop the docker container call docker-compose stop from the test directory.
Contributing
Issues, pull requests and questions are welcomed. If required, assistance can be found in the project's gitter chat room.
Pull Requests
- Fork the repository
- Make changes
- Ensure tests pass
- Raise pull request
Documentation
¶
Overview ¶
Package roger implements a RServe client, allowing R commands to be evaluted and the resulting data made available to Go applications.
Connect:
rClient, err := roger.NewRClient("127.0.0.1", 6311)
Evaluation:
value, err := rClient.Eval("pi")
fmt.Println(value) // 3.141592653589793
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Packet ¶
type Packet interface {
// GetResultObject will parse the packet's contents, returning a go interface{}.
// If the Packet contains an error this will be returned.
// If conversion fails, an error will be returned.
GetResultObject() (interface{}, error)
// IsError returns a boolean defining whether the Packet contains an error.
IsError() bool
// Returns the packet's error or nil if there is none.
GetError() error
// IsOk returns a boolean defining whether Packet was success
IsOk() bool
}
Packet is the interface satisfied by objects returned from a R command. It contains either the resulting object or an error.
type RClient ¶
type RClient interface {
// Eval evaluates an R command synchronously returning the resulting object and any possible error. Creates a new session per command.
Eval(command string) (interface{}, error)
// Evaluate evaluates an R command asynchronously. The returned channel will resolve to a Packet once the command has completed. Creates a new session per command.
Evaluate(command string) <-chan Packet
// EvaluateSync evaluates an R command synchronously, resulting in a Packet. Creates a new session per command.
EvaluateSync(command string) Packet
// GetSession gets a session object which can be used to perform multiple commands in the same Rserve session.
GetSession() (Session, error)
}
RClient is the main Roger interface allowing interaction with R.
func NewRClient ¶
NewRClient creates a RClient which will run commands on the RServe server located at the provided host and port
type Session ¶
type Session interface {
// Sends a command to RServe which is evaluated synchronously resulting in a Packet.
SendCommand(command string) Packet
// Eval evaluates an R command synchronously returning the resulting object and any possible error. Unlike client.Eval, this does not start a new session.
Eval(cmd string) (interface{}, error)
// Assign value to a variable within the R session.
Assign(symbol string, cont interface{}) error
// Close closes a RServe session. Sessions must be closed after use.
Close()
}
Session is an interface to send commands to an RServe session. Sessions must be closed after use.
Source Files
Directories