Differences

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

--- lesson_20 [2019/08/31 00:01]
argemiro
+++ lesson_20 [2022/12/31 21:20]
admin [Selecting the R Interpreter to Use]
@@ Line 1: / Line 1: @@
 {{ :logo_logo.png?400 |}}
 \\
-=====LESSON 20: Dinamica EGO and R Coupling=====
+=====Dinamica EGO and R Coupling=====
 \\
 \\
 ==== What will you learn? ====
+  * Couple R to Dinamica EGO
-  * Calculate R Expression on Dinamica EGO
+  * Calculate R Expression
+  * Select the R Interpreter to Use
-\\
 \\
 ====== R Coupling ======
@@ Line 17: / Line 17: @@
 ===== Exchanging Data between R and Dinamica =====
-Dinamica EGO 4 changes the game when it comes to exchanging data with R. Now Dinamica can use a specialized set of functors to send and receive data to and from R. R can use an special package (called "[[:external_communication|Dinamica]]") to send and receive data to and from Dinamica. This allows both tools to run simultaneously and none of them needs be in charge of controlling the simulation. Those specialized functors and package functions not only take care of data exchange between both tools, but also ensure that the calls are kept synchronized by blocking a receiver when the corresponding data is not yet available or the sender has not yet finished baking all the information.
+Dinamica EGO 4 changes the game when it comes to exchanging data with R. Now Dinamica can use a specialized set of functors to send and receive data to and from R. R can use an special package (called "[[:external_communication|Dinamica]]") to send and receive data to and from Dinamica. This allows both tools to run simultaneously without the need of one controlling the simulation. Those specialized functors and package functions not only take care of data exchange between both tools, but also ensure that the calls are kept synchronized by blocking a receiver when the shared data are not yet available or the sender has not yet finished processing all the information.
-{{ reference_book:rcoupling4.png?direct&600 |}}
+{{ :rcoupling4.png?600 |}}
 Under the hood, the data exchange works by creating a "shared session" between an instance of Dinamica and an instance of a R interpreter. Each "shared session" creates a special entity used to store all pending messages exchanged between the applications. The messages can be divided in two different groups with short messages being exchanged via a shared queue and long messages also being placed in temporary storage while the transfer is being processed. Typically, numbers and strings are handled as short messages while lookup tables and tables are handled as long messages.
-{{ reference_book:rcoupling5.png?direct&600 |}}
+{{ :rcoupling5.png?600 |}}
 A "shared session" uses an unique name as identifier. It is possible to have more than one instance of Dinamica and R talking to each other, but each pair of instances must use an unique identifier, called an "active session name" to identifier their corresponding sessions and isolate their communication from the other pairs. The "active session name" can be configured in the "Tools -> Options | Integration | Communication Session" options. The session name is also visible in the status bar. Double clicking that label is another way of editing the corresponding definition.
-{{ reference_book:rcoupling7.png?direct&600 |}}
+{{ :rcoupling6.png?600 |}}
 Dinamica EGO is responsible for creating the communication session when the application starts, and it happens automatically when the application starts. Functors related to sending and receiving data will always use the current session to exchange information. On the other hand, R does not have to create a session for talking to Dinamica, and in fact it does not have the tools for that, but it has to explicitly connect to the "shared session" created by Dinamica. This should be done by calling ''Dinamica::openSession()''. See the help about [[:external communication]] for additional information about how to set up a session.
@@ Line 35: / Line 35: @@
 The following figure shows a pseudo-example where a Dinamica model and a R script are exchanging data.
-{{ reference_book:rcoupling6.png?direct&600 |}}
+{{ :rcoupling7.png?600 |}}
 ===== Calculate R Expression =====
@@ Line 45: / Line 45: @@
 Returning data from the R script back to the Dinamica model is done using the commands such as ''outputDouble()'', ''outputTable()'', ''outputString()'' etc. All results returned by the script are bundled in a special type called Struct. [[:Struct Type|Struct's]] are basically collections of unrelated data where each one of their components can be accessed using a corresponding key. The use of the Struct as a data return mechanism ensures that, despite the [[:Calculate R Expression]] having only one output port, the R script can return as many results as necessary.  Struct's can be disassembled in the Dinamica model using the "Extract Struct" family of functors.
-{{ reference_book:rcoupling8.png?direct&600 |}}
+{{ :rcoupling8.png?600 |}}
 The following figure shows a model where R is being used to calculate the mean of both columns of a [[:Lookup Table Type|Lookup Table]]. The R script returns its results in Struct two real value as fields, named "meanForKeys" and "meanForValues". A couple of functors [[:Extract Struct Number]] is used to extract the value of the fields from the resulting Struct.
-{{ :reference_book:rcoupling9.png?direct&600 |}}
+{{ :rcoupling9.png?600 |}}
 The next figure shows a more complicated example where the R script is being used to list all files from a given folder with a particular filename extension. The particular example shows how to return a table as a result. [[:Table Type|Tables]] are always passed and returned to and from R scripts as data frames. The documentation of the [[:Calculate R Expression]] explains some of the pitfalls of dealing with data frames to pass and receive data, specially when a table contains strings.
@@ Line 55: / Line 55: @@
 In the example, the single table represented the list of files is returned as a field called "files" in the resulting [[:Struct Type|Struct]] produced by the [[:Calculate R Expression]].
-{{ reference_book:rcoupling10.png?direct&600 |}}
+{{ :rcoupling10.png?600 |}}
-<note>Some very simple examples showing how to use an R script as part of a Dinamica EGO model are provided as part of the dataset distributed with the Dinamica EGO application. Check the content of ''Dataset\Examples\various_applications\calculate r expression''.</note>
+<note>Some very simple examples showing how to use an R script as part of a Dinamica EGO model are provided as part of the dataset distributed with the Dinamica EGO application. Check the content of ''\Guidebook_Dinamica_5\Models\calculate_r_expression''.</note>
 ==== Selecting the R Interpreter to Use ====
@@ Line 63: / Line 63: @@
 When using the [[:Calculate R Expression]], Dinamica automatically invokes and stops the selected R interpreter to evaluate the expression as necessary. The user can control which R interpreter will be used by selecting appropriate options in "Tools -> Options | Integration | Calculate R Expression / R Integration". It is possible to choose between the default R interpreter provided with the [[:plugins_4|Enhancement Plugin]] or an alternative R installation installed independently.
-{{ reference_book:rcoupling11.png?direct&600 |}}
+{{ :rcoupling11.png?600 |}}
-Any R interpreter can be used as an alternative (and external) R installation provided that a compatible [[https://cran.r-project.org/bin/windows/Rtools/|RTools]] and the [[:external_communication|"Dinamica"]] package are installed. The biggest advantage of using a alternative version of R is that the user will be free to install and import any packages he wants. When using the default R interpreter from the [[:plugins_4|Enhancement Plugin]], the user is limited to the packages that come pre-installed with the platform.
+Any R interpreter can be used as an alternative (and external) R installation provided that a compatible [[https://cran.r-project.org/bin/windows/Rtools/|RTools]] and the [[:external_communication|"Dinamica"]] package are installed. The biggest advantage of using a alternative version of R is that the user will be free to install and import any packages he wants.
 For more information about how to set an external R interpreter, see the documentation about the [[:Calculate R Expression]] and [[:external communication]].
@@ Line 79: / Line 79: @@
 Preserving a state across invocations of the same R scripts would require R to save and reload the relevant parts of its model for each iteration, since the [[:Run External Process]] would be simply spawning and terminating an instance of the R interpreter every time step.
-{{ reference_book:rcoupling2.png?direct&600 |}}
+{{ :rcoupling12.png?600 |}}
 ==== Legacy way of calling Dinamica EGO from R ====
@@ Line 87: / Line 87: @@
 Exchanging data would work in a similar way with R saving the data to disc to pass the data to Dinamica with Dinamica loading the data again as part of its own model. As expected, sending the result back would required the opposite.
-{{ reference_book:rcoupling3.png?direct&600 |}}
+{{ :rcoupling13.png?600 |}}
 \\
 \\
-Congratulations, you have successfully completed this lesson! Now let’s move to the **next lesson:** [[lesson_21|LESSON 21: Dinamica EGO script language and console launcher]]
+\\
+☞[[lesson_21|Next: Dinamica EGO script language and console launcher]]
+\\
+☞[[:guidebook_start| Back to Guidebook Start]]