Differences

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

--- calculate_r_expression [2017/01/24 17:16]
romulo
+++ calculate_r_expression [2018/09/18 14:14] (current)
francisco [R Script Outputs]
@@ Line 1: / Line 1: @@
-======= Calculate R Expression =======
+====== Calculate R Expression ======
-The functor 'Calculate R Expression' allows Dinamica EGO to call R externally and process the script outputs as if they were
-part Dinamica itself.
-====== Setup ======
+===== Description =====
-There are two ways to setup the 'Calculate R Expression' functor:\\
+The functor 'Calculate R Expression' allows Dinamica EGO to call R externally and process the script outputs as if they were part of Dinamica itself. For an overview of how Dinamica and R can be linked together check the documentation about [[reference_book:r_coupling|R Coupling]].
-\\
-=== R Plugin ===
+===== Inputs =====
-There is a plugin that contains everything needed to wrap R scripts inside Dinamica EGO, just extract [[http://csr.ufmg.br/~romulo/R.7z|this file]]
- to your Dinamica EGO installation folder (usually c:\Program Files\Dinamica EGO) and you will be good to go.\\
+^ Name  ^ Type  ^ Description  ^
-\\
+| Expression  | [[String Type]]  | The expression that will run on R.  |
-=== Local R Installation ===
+| Treat Warning As Errors  | [[Boolean Value Type]]  | Warnings on R script will be considered errors.  |
-Users can specify a local R installation to be used for execution, the pre requisites are:\\
-  - R needs to be at least at the **3.3.1** version.
+===== Optional Inputs =====
-  - **Rscript.exe** must be valid and located at the 'installation folder\\bin' sub-folder.
-  - [[external communication|Dinamica package]] for R must be installed and at the latest version.
+None.
+===== Output =====
+^ Name  ^ Type  ^ Description  ^
+| result  | [[Struct Type]]  | A struct containing the output values generated by the expression.  |
+===== Group =====
+[[Functor List#Integration | Integration]]
+===== Notes =====
+There are two ways to setup the 'Calculate R Expression' functor:
+==== Dinamica EGO Enhancement Plugin ====
+Simply download and install the [[plugins_4|Dinamica EGO Enhancement Plugin]]. It contains everything you need to run R scripts inside Dinamica EGO.
+==== Local R Installation ====
+Additionally, users can specify and use their own local R installation for execution. The pre-requisites are:
+  * R needs to be at least at the 3.3.1 version.
+  * ''Rscript.exe'' must be valid and located at the ''<installation folder>/bin'' sub-folder.
+  * [[external communication|Dinamica package]] for R must be installed and at the latest version.
+To specify your custom R installation, go to Tools --> Options --> Integration tab and select //Use alternative R installation for Calculate R Expression//:
-To specify your custom R installation, go to Tools -> Options -> External Comm tab and select 'Use alternative R installation for Calculate R Expression':
 {{:dinamica_options_use_alternative_r_install.png?nolink|}}
-\\
-\\
-====== Usage ======
-The functor is available under the 'External Communication' tab at the library.\\
-\\
-\\
-=== Inputs ===
-To pass input parameters from Dinamica EGO to R, hooks must be placed to collect data. You can use the 'Create a hook' button on
-the selected functor bar or drag the hooks individually.\\
-The valid hook types are:
-  * Number Table
-  * Number Value
-  * Number String
-To access the passed inputs on your R script, follow Dinamica EGO naming conventions and use **t[0-99]**, **v[0-99]**, **s[0-99]** for each type respectively. For example:\\
+----
+===== Usage =====
+The functor is available under the //Integration// tab at the library.
+===== R Script Inputs =====
+To pass input parameters from Dinamica EGO to R, hooks must be placed to collect data. You can use the //Create a hook// button on the selected functor bar or drag the hooks individually. The valid hook types are:
+  * [[Number Table]]
+  * [[Number Value]]
+  * [[Number String]]
+To access the passed inputs on your R script, follow Dinamica EGO naming conventions and use ''t[0-99]'', ''v[0-99]'', ''s[0-99]'' for each type respectively. For example:
 <code rsplus>
-# Will store the 5th key from the passed LookupTable in the variable 'testing'
+# Will store the 5th key from the passed Lookup Table in the variable 'testing'
 testing <- t1$Keys[ 5 ];
@@ Line 44: / Line 75: @@
 tempNumber <- v10;
 </code>
-\\
-\\
+===== R Script Outputs =====
-=== Outputs ===
 To output data back to Dinamica EGO, the user must call a set of functions designed for this functionality:
-^ Function name           ^ Output Data Type                   ^ Usage Example                                       ^
-| outputDouble()          | Real                               | outputDouble( "myDouble", 3.14 )                    |
+^ Function name  ^ Output Data Type  ^ Usage Example  ^
-| outputNumberVector()    | Tuple                              | outputNumberVector( "myTuple", c(1:10) )            |
+| outputDouble()  | Real  | outputDouble( "myDouble", 3.14 )  |
-| outputString()          | String                             | outputString( "myString", "This is a string" )      |
+| outputNumberVector()  | Tuple  | outputNumberVector( "myTuple", c(1:10) )  |
-| outputLookupTable()     | LookupTable                        | outputLookupTable( "myLUT", c(1:10), c(1:10) * 10 ) |
+| outputString()  | String  | outputString( "myString", "This is a string" )  |
-| outputTable()           | Table                              | outputTable( "myTable", anyTable, 4 )               |
+| outputLookupTable()  | LookupTable  | outputLookupTable( "myLUT", c(1:10), c(1:10) * 10 )  |
-In the examples above, data was constructed inside the calling functions. You can also specify variables as parameters.
+| outputTable()  | Table  | outputTable( "myTable", data.frame(State = c("Massachusetts", "Massachusetts"), City = c("Boston", "Chelsea"), Population = c(667137, 39398), stringsAsFactors = FALSE), 2 )  |
-<note important>All output functions require an identifier as the first parameter, that's the name Dinamica uses for retrieving the correct data.</note>
-\\
+In the examples above, data was constructed inside the calling functions. You can also specify variables as parameters.
-Keep in mind:\\
-  * You can pass any kind of numeric value on the outputDouble function.
+<note important>All output functions require an identifier as the first parameter, that's the name Dinamica uses for retrieving the correct data (to put into the struct output).</note>
-  * Collections of numbers are valid Number Vector's.
-  * A LookupTable requires **2** number vectors, one for the Keys and another for the Values. Both vectors must have the same number of elements.
+Keep in mind:
-\\
-\\
+  * You can pass any kind of numeric value on the ''outputDouble'' function.
-====== Tables ======
-**Tables** or **LookupTables** can be transferred to R using the Number Table functor. When dealing with each of these types extra caution must be
+  * Collections of numbers are valid number vector's.
-taken:
-==== Lookup Tables ====
+  * A [[Lookup Table Type|Lookup Table]] requires //2// number vectors, one for the "Key" and another for the "Value". Both vectors must have the same number of elements.
-LookupTables are transferred to R as a **List** with two columns, "Keys" and "Values".\\
-Each column can be individually accessed by using the **$** operator, for example:\\
+  * The ''outputTable'' function requires a table, that can be constructed with [[http://www.r-tutor.com/r-introduction/data-frame | data.frame]] R function. There is another parameter that is optional with default value 1, and it means how many Key columns the table has, from the leftmost column.
-  * t1**$**Keys[ 1 ] will access the first key of the LookupTable **t1**.
+<note important>Notice the use of the stringAsFactors = FALSE flag. This flag prevents R from converting the passed strings to Factors(numbers).</note>
-  * t2**$**Values[ 2 ] will access the second value of the LookupTable **t2**
-==== Tables ====
+==== Tables / Lookup Tables ====
-Tables are transferred to R as a **DataFrame** type variable. Each column can be individually accessed by using the **$** operator, just like LookupTables.\\
-Please check [[external_communication#table|this page]] for more information on how to deal with **Tables**. The rules for them in **Calculate R Expression** are the same as sending and receiving through **External Communication**.\\
+[[Table Type|Tables]] or [[Lookup Table Type|Lookup Tables]] can be transferred to R using the [[Number Table]] functor. When dealing with each of these types extra caution must be taken:
-\\
-\\
+=== Lookup Tables ===
-====== Example Scripts ======
-\\
+Lookup Tables are transferred to R as a List with two columns, "Key" and "Value".
-=== Multiply each value of the passed LookupTable by itself. ===
+Each column can be individually accessed by using the ''$'' operator, for example:
+  * ''t1$Key[ 1 ]'' will access the first key of the Lookup Table ''t1''.
+  * ''t2$Value[ 2 ]'' will access the second value of the Lookup Table ''t2''
+=== Tables ===
+Tables are transferred to R as a [[https://en.wikibooks.org/wiki/R_Programming/Working_with_data_frames|DataFrame]] type variable. Each column can be individually accessed by using the ''$'' operator, just like Lookup Tables. Please check [[external_communication#table|this page]] for more information on how to deal with Tables. The rules for them in [[Calculate R Expression]] are the same as sending and receiving through [[External Communication]].
+===== Example Scripts =====
+==== Multiply each value of the passed Lookup Table by itself ====
 {{ ::ex1_calculate_r.png?nolink |}}
 Expression:
 <code rsplus>
-for ( i in 1:length( t1$Values ) ) {
+for ( i in 1:length( t1$Value ) ) {
-  tempValue <- t1$Values[ i ];
+  tempValue <- t1$Value[ i ];
-  t1$Values[ i ] = tempValue * tempValue;
+  t1$Value[ i ] = tempValue * tempValue;
 }
-outputLookupTable( "poweredTable", t1$Keys, t1$Values );
+outputLookupTable( "poweredTable", t1$Key, t1$Value );
 </code>
-\\
-\\
+==== Extract the mean of passed Lookup Table values ====
-=== Extract the mean of passed LookupTable values. ===
 {{ ::ex2_calculate_r.png?nolink |}}
 Expression:
 <code rsplus>
-tableMean <- mean( t1$Values );
+tableMean <- mean( t1$Value );
 print( paste( "Mean is", tableMean ) );
 outputDouble( "mean", tableMean );
 </code>
-Noticed the **print()** statement? Dinamica EGO's Message Log will show output messages from the R script.
-\\
+Noticed the ''print()'' statement? Dinamica EGO's Message Log will show output messages from the R script (as Result's).<note warning>If the Message Log level is Unconditional, the messages will not be printed.</note>
-\\
-=== Plot passed LookupTable to an image on the path specified by passed String ===
+==== Plot passed Lookup Table to an image on the path specified by passed String ====
 {{ ::ex3_calculate_r.png?nolink |}}
 Expression:
 <code rsplus>
@@ Line 112: / Line 161: @@
 dev.off();
 </code>
+===== Internal Name =====
+CalculateRExpression