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. 


(For a primer on what it's like working with R in the Exaptive Studio, check out the R article in our Working with Your Favorite Technology section. To learn more about using dependencies and the spec file visit this section)



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.

 

// spec
"input": [
  { "name": "sum", "valueType": "entity<integer x, integer y>", "description": "Computes the sum of x and y." }
],
"output": [
  { "name": "result", "valueType": "integer", "description": "The sum value" }
]

   

# script 
sum <- function(self) { 
  state <- v_export(self$api$inputstate) 
  self$api$log("Hello") 
  self$api$output("result", v_integer(state$sum$x + state$sum$y)) 
}

 

 

Here are the most commonly used API functions for building R components.


inputstate          self$api$inputstate          Type: Value

This represents the component's current input values. 
 

# Suppose there are inputs x and y.
state <- v_export(self$api$inputstate)
x <- state$x
y <- state$y

 


imports          self$api$imports          Type: list

The access point to the component's dependencies such as user files and data, if any.


// Suppose these dependencies are defined in the spec.
"dependencies": {
  "file": [
    {"type": "url", "name": "myfile", "asset": "5ec33c94-2df2-11e6-b67b-9e71128cae77" },
    {"type": "data", "name": "mydata", "asset": "6b82df02-2df2-11e6-b67b-9e71128cae77" },
  ]
}

 

# 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.


myInput <- function(self) {
  v <- v_integer(1)
  v <- v_transform(v, "_ + 2")
  result <- v_export(v)
}

 


v_import          v_import( x, format )          Type: Function
This 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.



# Both are the same.
v <- v_import(1)
v <- v_import("1", format = "json")



scalar          scalar( x )          Type: Function

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 <- v_import(1)# Imported as [1]
v <- v_import(scalar(1))# Imported as 1

 

Below are various factory methods to instantiate new Value objects. These are all wrappers of the v_import function. All examples except for v_null require an argument x representing  

the value being imported. These functions will return the Value object for the imported value.


v_boolean( x )
v_string( x )
v_integer( x )
v_float( x )
v_list( x )
v_set( x )
v_multiset( x )
v_entity( x )
v_null() 


v1 <- v_integer(1)
v1 == v_export(v1)  # TRUE
v1 <- v_import(scalar(1))# Equivalent
 
v2 <- v_string("Hello")
v2 == v_export(v2)  # TRUE

 

 

v_transform          v_transform( vobj, expr )          Type: Function
This 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_export          v_export( vobj, format )          Type: Function
This 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.


v <- v_integer(1)
v_export(v)     # 1
v_export(v, "native")   # 1
v_export(v, "json")     # "1"
v_export(v, "duffle/json") 

 



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.


library(jsonlite)

# Equivalent.
val <- v_import(1)
val <- v_import(jsonlite::toJSON(1), format = "json")

# Equivalent.
x <- v_export(val)
x <- jsonlite::fromJSON(v_export(val, format = "json"))