Differences

This shows you the differences between two versions of the page.

--- external_communication [2016/12/20 00:26]
admin created
+++ external_communication [2019/04/02 21:00] (current)
romulo
@@ Line 11: / Line 11: @@
 <note important>If the status bar shows 'External communication: off', check the Message Log for more information.</note>
+==== Pre Requisites ====
-==== R Studio ====
 The following packages are necessary for sending and receiving data using R. To install the packages, do:
 <code>
 install.packages(c("Rcpp", "RcppProgress", "rbenchmark", "inline"))
 </code>
+<note important> if you are using Microsoft Windows, make sure your R installation path does not contain spaces.</note>
+<note important> On Microsoft Windows, [[https://cran.r-project.org/bin/windows/Rtools/|R Tools]] is required (default installation path [c:\rtools] is **mandatory**). Make sure you also select the option to add RTools to system PATH.  </note>
+==== Command Line ===
+Download {{::dinamica_1.0.4.tar.gz|Dinamica Package for R}} and install it:
+<code>
+install.packages("PATH_TO_DOWNLOADED_FILE", repos=NULL, type="source")
+</code>
+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.\\
 \\
-Then, install R Tools from [[https://cran.r-project.org/bin/windows/Rtools/]] \\
+Using the example path "/home/csr/Downloads/dinamica_1.0.4.tar.gz":
+<code>
+install.packages("/home/csr/Downloads/dinamica_1.0.4.tar.gz", repos=NULL, type="source")
+</code>
+==== R Studio ====
 \\
-Download {{::dinamica_1.0.tar.gz|Dinamica Package for R}} and install it (using RStudio):
+Download {{::dinamica_1.0.4.tar.gz|Dinamica Package for R}} and install it (using RStudio):
 <code>
 Tools -> Install Packages...
@@ Line 34: / Line 48: @@
 </code>
 \\
-=== To Send and Receive Data ===
+====== Send and Receive Data ======
-To send a number (e.g. 3.14):
+===== Real value =====
-<code>
+To send a Real value (e.g. 3.141592, the PI constant):
-Dinamica::sendNumber(3.14);
+<code rsplus>
+Dinamica::sendNumber(3.141592);
 </code>
 \\
-To receive a number:
+To receive a Real value:
-<code>
+<code rsplus>
-myNumber <- Dinamica::receiveNumber(); # Will receive a number in myNumber variable
+myNumber <- Dinamica::receiveNumber();
 </code>
+In the above example, the received Real value will be stored in the **myNumber** variable.
 \\
-To send a list of numbers (e.g. [1,10]):
+\\
-<code>
+===== List / Vector of Real values =====
-Dinamica::sendNumberVector(c(1,10)); # Sends 1,2,3,4,5,6,7,8,9,10
+To send a list of Real values (e.g. 1, 2, 3, 4, 5):
+<code rsplus>
+myList <- c(1, 5);
+Dinamica::sendNumberVector(myList);
 </code>
+In the above example, the user created **myList** will be sent.
 \\
-To receive a list of numbers:
+\\
-<code>
+To receive a list of Real values:
-myList <- Dinamica::receiveNumberVector(); # Will receive a list of numbers in myList variable.
+<code rsplus>
+receivedList <- Dinamica::receiveNumberVector();
 </code>
+In the above example, the variable **receivedList** will store the contents of the received List of Real values.
 \\
-To send a lookup table (e.g. 1 -> 2; 2 -> 3; 3 -> 4):
+\\
-<code>
+===== Lookup Table =====
-lookupTable <- list(keys = c(1,3), values = c(2,4));
+Consider the following **LookupTable** stored on the variable **myLUT**:
-Dinamica::sendLookupTable(lookupTable$keys, lookupTable$values); # Send 1 -> 2; 2-> 3; 3->4
+<code rsplus>
+myLUT <- list( Keys = c(1:5), Values = c(1:5) * 2 )
+</code>
+^ Keys ^ Values  ^
+|1     | 2       |
+|2     | 4       |
+|3     | 6       |
+|4     | 8       |
+|5     | 10      |
+To send the **myLUT** **LookupTable**:
+<code rsplus>
+Dinamica::sendLookupTable(myLUT$Keys, myLUT$Values);
 </code>
 \\
 To receive a lookup table:
-<code>
+<code rsplus>
-myLUT <- Dinamica::receiveLookupTable(); # Will receive a lookup table in myLUT variable.
+receivedLUT <- Dinamica::receiveLookupTable();
 </code>
+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 [[r_communication_utilities|this page]] for auxiliar tools.)
+  - **Factor** columns must be converted to **Character Vectors**
+  - Key columns can contain the '*' character on their names (to indicate they represent unique values).
+  - 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           |
+<code rsplus>
+myTable <- data.frame(Product = c("Rice", "Pasta", "Corn"), Price = c(2.5, 1.5, 0.5), Quantity = c(1e6, 500, 1000), stringsAsFactors = FALSE)
+</code>
+<note important>Notice the use of the **stringAsFactors = FALSE** flag. This flag prevents R from converting the passed strings to Factors.</note>
+\\
+To send the **myTable** **Table**:
+<code rsplus>
+Dinamica::sendTable(myTable);
+</code>
+<note important>We never specified which column is the **Key** column. By default, the first column will be converted to the Key column.</note>
+\\
+\\
+Suppose you want to send the following Table instead:
+^ State         ^ City    ^ Population ^
+| Massachusetts | Boston  | 667137     |
+| Massachusetts | Chelsea | 39398      |
+<code rsplus>
+myTable <- data.frame(State = c("Massachusetts", "Massachusetts"), City = c("Boston", "Chelsea"), Population = c(667137, 39398), stringsAsFactors = FALSE)
+</code>
+To send the new version of **myTable**:
+<code rsplus>
+Dinamica::sendTable(myTable, 2);
+</code>
+<note important>Notice the extra parameter **2**? This optional parameter tells Dinamica, how many Key columns are being sent, from the leftmost column.</note>
+\\
+To receive a table:
+<code rsplus>
+receivedTable <- Dinamica::receiveTable();
+</code>
+In the above example, the variable **receivedTable** will store the contents of the received Table.
+\\
 \\
+===== String =====
 To send a string (e.g. "testing!"):
-<code>
+<code rsplus>
-Dinamica::sendString("testing!"); # Send "testing!"
+Dinamica::sendString("testing!");
 </code>
 \\
 To receive a string:
-<code>
+<code rsplus>
-myString <- Dinamica::receiveString(); # Will receive a string in myString variable.
+receivedString <- Dinamica::receiveString();
 </code>
+In the above example, the variable **receivedString** will contain the received String value.
+\\
 \\