How can we help you today?

R Component API

Modified on: Wed, 20 Sep, 2017 at 10:36 AM

When you're coding the SCRIPT for a component, you'll need to know syntax specific to the domain you're working in (Javascript, R, or Python). This article covers some of the API functions for building R components.

You'll need this stuff for creating the functions that process data coming in and going out of your component. You'll also need it for debugging - creating warnings, errors, and logs.

The R component API is accessible through the API property of the component context passed to an input handler. It is denoted by here as self$api. It need not be denoted as self, however. You could use state, for instance.

# The dependencies can be accessed as follows
self$api$imports$myfile # path to the file.
self$api$imports$mydata# the content of the file.

log self$api$log( msg, value ) Type: Function

Log messages are displayed in the dataflow console and can be viewed within the log messages tab. This function takes two arguments, msg and value. The msg argument must be a string. Consider msg to be the title of the message that is logged to the console. The value argument accepts various types including strings, json and lists.

warning self$api$warning( msg, value ) Type: Function

Warning messages are highlighted yellow in the dataflow console and can be viewed within the warning messages tab. This function takes two arguments, msg and value. The msg argument must be a string. Consider msg to be the title of the message that is logged to the console. The value argument accepts various types including strings, json and lists.

error self$api$error( msg, value ) Type: Function

Error messages are highlighted red in the dataflow console and can be viewed within the error messages tab.

output self$api$output( name, value ) Type: Function

This sends a value to a component output port with the given name. This function is used to return data from a component. It takes two arguments, name and value. The name must match the corresponding output port. The value must match the value that is required by the output port.

The value API is used to instantiate Exaptive Value objects and manipulate them [note: the interface is currently still minimal]. The functions are accessible from within anywhere in the script.

v_import v_import( x, format ) Type: FunctionThis creates a Value object from the given value. This function takes two arguments, x and format. The first argument x represents the value that is being imported and supports various types. The format argument is an optional argument of types json or duffle/json, and it defines how to interpret the imported value. This function returns a value object for the imported value.

This requests that the value be treated as a scalar value when imported into a Value object. This is important, since R has no notion of scalars. This function requires the argument x, representing the value that will be treated as a scalar.

Note:This function is actually just an alias to jsonlite::unbox(), since the Exaptive language is JSON based. You may also want to take a look at the jsonlite section below.

v_transform v_transform( vobj, expr ) Type: FunctionThis performs a transform on the value. This function takes two arguments, vobj and expr. The argument vobj represented the value to transform and requires type of value. The second argument, expr ,represents the transform expression. This function returns a value object with the transform applied.

v <- v_import(1)
v <- v_transform(v, "_ + 1")
v_export(v) # 2

v_exportv_export( vobj, format ) Type: FunctionThis exports the Value object to a R value. This function takes two arguments, vobj and expr. The argument vobj represented the value to transform and requires type of value. The second argument, expr, is an optional argument representing the transform expression. The supported types for expr are native, json, and duffle/json. This function will return the exported R value.

The Exaptive system is JSON based. Hence, a JSON <-> R conversion system is required in order to connect the two systems.

The Exaptive R connector uses the jsonlite package under the hood for this purpose wherever a conversion is required. For example, v_export() often requires a conversion from JSON to R, and v_import() requires a conversion from R to JSON.

However, there may be cases where you want more control over the conversion. You can use jsonlite to perform the conversion yourself.