Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
OpenCPU API wrapper gem
Ruby
branch: master
Failed to load latest commit information.
lib
spec
.gitignore [master] added httmultiparty
.travis.yml
CHANGELOG.md
Gemfile added code climate test coverage
Guardfile
LICENSE.txt
README.md updated maintainers
Rakefile Travis didn't need rake
circle.yml
opencpu.gemspec [master] added httmultiparty

README.md

OpenCPU gem

Build Status Build Status Code Climate Dependency Status

Roqua wrapper for the OpenCPU REST API.

Installation

Add this line to your application's Gemfile:

gem 'opencpu'

And then execute:

$ bundle

Or install it yourself as:

$ gem install opencpu

Configuration

OpenCPU.configure do |config|
  config.endpoint_url = 'https://public.opencpu.org/ocpu'
  config.timeout      = 30 # Timeout in seconds
  config.verify_ssl   = true # set to false for opencpu server with self-signed certificates.
end

Usage

client = OpenCPU.client

Formats

By default we send data using the json format. This format is efficient and safe, but only supports strings and numeric parameters (see opencpu page)

If you want to send R code argument, you'll need to specify format: :urlencoded in your request. Note that you need to enclose your string parameters in quotes in that case, since they will be seen as variables otherwise:

client.execute :digest, :hmac, data: { key: "'foo'", object: "'bar'" }, format: :urlencoded

One-step call

One-step call always returns a JSON result from OpenCPU. This is a preferred way to use this gem, but keep in mind that not every R-package supports one-step responses. On OpenCPU server, packages can be installed under the system, but also under a particular user. This gem also provides a way to access both of them.

Access System Libraries

To get a response from the package installed under the system libraries just pass the package name, function and input data to the function. In the following example :digest is an R-package name, :hmac is a function and { key: 'foo', object: 'bar' } is the input data, where key and object are parameters of hmac function:

client.execute :digest, :hmac, data: { key: 'foo', object: 'bar' }
# => ['0c7a250281315ab863549f66cd8a3a53']

Above example is the same as the following (note the user parameter):

client.execute :digest, :hmac, user: :system, data: { key: 'foo', object: 'bar' }
# => ['0c7a250281315ab863549f66cd8a3a53']

Access User Libraries

To access a package installed under a particular user, just pass user parameter with the name of the existing user.

client.execute :digest, :hmac, user: :johndoe, data: { key: 'foo', object: 'bar' }
# => ['0c7a250281315ab863549f66cd8a3a53']

Two-steps way

To prepare the calculations on OpenCPU execute the #prepare method. It accepts the same arguments as #execute, thus: package, function, user and data.

calculations = client.prepare :animation, 'flip.coin'

calculations variable now holds the reference URL's to the calculations made by OpenCPU. These URL are available through one of the following methods. Which of them are available depends on the package and possible response it can generate.

#graphics(obj, type)

calculations.graphics
# => Returns the first SVG created by OpenCPU.
calculations.graphics(1)
# => Returns the second SVG created by OpenCPU.
calculations.graphics(1, :png)
# => Returns the second PNG created by OpenCPU.

#value

calculations.value
# => Returns the raw output of the R-function.

#stdout

calculations.stdout
# => Returns the raw output of stdout being written at the runtime.

#warnings

calculations.warnings
# => Returns the warnings returned by the script.

#source

calculations.source
# => Returns the source of the script.

#console

calculations.console
# => Returns the output from R-console.

#info

calculations.info
# => Returns information about R-environment of the script.

Additional features

Multipart requests with files

If you want to send one or more files along, you can pass in a File object as data, but only when using the urlencoded format.

client.execute :foo, :bar, user: :johndoe, data: {file: File.new('/tmp/test.foo')}, format: :urlencoded

Testing

NOTE: Test mode is only supported in combination with #execute and the first step (#prepare) in two-step call.

OpenCPU gem provides a test mode. It basically disables all HTTP interactions with provided OpenCPU server. It is very handy when testing your software for example. You can easily turn it on:

OpenCPU.enable_test_mode!

After that you can set fake responses per package/script combination:

OpenCPU.set_fake_response! :digest, :hmac, 'foo'

This will allways return 'foo' when calling function hmac in package digest.

Maintainers

Contributing

  1. Fork it ( http://github.com/roqua/opencpu/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
Something went wrong with that request. Please try again.