External Communication

Dinamica EGO can communicate with external applications by exposing a communication session. By default, an opened session will be created and its name is displayed on the status bar:

To send and receive data, the functors under the 'External Communication' folder in the Library can be used.

If the status bar shows 'External communication: off', check the Message Log for more information.

Pre Requisites

The following packages are necessary for sending and receiving data using R. To install the packages, do:

install.packages(c("Rcpp", "RcppProgress", "rbenchmark", "inline"))
if you are using Microsoft Windows, make sure your R installation path does not contain spaces.
On Microsoft Windows, R Tools is required (default installation path [c:\rtools] is mandatory). Make sure you also select the option to add RTools to system PATH.

Command Line

Download Dinamica Package for R and install it:

install.packages("PATH_TO_DOWNLOADED_FILE", repos=NULL, type="source")

where PATH_TO_DOWNLOADED_FILE should match the downloaded file path, e.g. “/home/csr/Downloads/dinamica_1.0.4.tar.gz” on Linux or “c:/Users/CSR/Downloads/dinamica_1.0.4.tar.gz” on Windows.

Using the example path “/home/csr/Downloads/dinamica_1.0.4.tar.gz”:

install.packages("/home/csr/Downloads/dinamica_1.0.4.tar.gz", repos=NULL, type="source")

R Studio


Download Dinamica Package for R and install it (using RStudio):

Tools -> Install Packages...


Documentation

The Dinamica R package contains all the documentation available on this page, including examples and R Studio references.

Session

To connect to an existing session:

Dinamica::openSession("DinamicaEGO") # "DinamicaEGO" is the session name.


Send and Receive Data

Real value

To send a Real value (e.g. 3.141592, the PI constant):

Dinamica::sendNumber(3.141592);


To receive a Real value:

myNumber <- Dinamica::receiveNumber(); 

In the above example, the received Real value will be stored in the myNumber variable.

List / Vector of Real values

To send a list of Real values (e.g. 1, 2, 3, 4, 5):

myList <- c(1, 5);
Dinamica::sendNumberVector(myList);

In the above example, the user created myList will be sent.

To receive a list of Real values:

receivedList <- Dinamica::receiveNumberVector();

In the above example, the variable receivedList will store the contents of the received List of Real values.

Lookup Table

Consider the following LookupTable stored on the variable myLUT:

myLUT <- list( Keys = c(1:5), Values = c(1:5) * 2 )
Keys Values
1 2
2 4
3 6
4 8
5 10

To send the myLUT LookupTable:

Dinamica::sendLookupTable(myLUT$Keys, myLUT$Values);


To receive a lookup table:

receivedLUT <- Dinamica::receiveLookupTable();

In the above example, the variable receivedLUT will store the contents of the received LookupTable. The columns 'Keys' (receivedLUT$Keys) and 'Values' (receivedLUT$Values) will contain the transferred Data.

Table

When transferring Tables, extra caution must be taken (refer to this page for auxiliar tools.)

  1. Factor columns must be converted to Character Vectors
  2. Key columns can contain the '*' character on their names (to indicate they represent unique values).
  3. From R to Dinamica, the Table variable must have the DataFrame type (or compatible).


Consider the following Table:

Product Price Stock Quantity
Rice 2.50 1e6
Pasta 1.50 500
Corn 0.50 1000
myTable <- data.frame(Product = c("Rice", "Pasta", "Corn"), Price = c(2.5, 1.5, 0.5), Quantity = c(1e6, 500, 1000), stringsAsFactors = FALSE)
Notice the use of the stringAsFactors = FALSE flag. This flag prevents R from converting the passed strings to Factors.


To send the myTable Table:

Dinamica::sendTable(myTable);
We never specified which column is the Key column. By default, the first column will be converted to the Key column.



Suppose you want to send the following Table instead:

State City Population
Massachusetts Boston 667137
Massachusetts Chelsea 39398
myTable <- data.frame(State = c("Massachusetts", "Massachusetts"), City = c("Boston", "Chelsea"), Population = c(667137, 39398), stringsAsFactors = FALSE)

To send the new version of myTable:

Dinamica::sendTable(myTable, 2);
Notice the extra parameter 2? This optional parameter tells Dinamica, how many Key columns are being sent, from the leftmost column.


To receive a table:

receivedTable <- Dinamica::receiveTable();

In the above example, the variable receivedTable will store the contents of the received Table.

String

To send a string (e.g. “testing!”):

Dinamica::sendString("testing!");


To receive a string:

receivedString <- Dinamica::receiveString();

In the above example, the variable receivedString will contain the received String value.