Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
calculate_r_expression [2017/01/24 17:16] romulo |
calculate_r_expression [2018/09/18 13:07] francisco [Extract the mean of passed Lookup Table values] |
||
---|---|---|---|
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|}} | {{: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> | <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 ]; | testing <- t1$Keys[ 5 ]; | ||
Line 44: | Line 75: | ||
tempNumber <- v10; | tempNumber <- v10; | ||
</code> | </code> | ||
- | \\ | + | |
- | \\ | + | ===== R Script Outputs ===== |
- | === Outputs === | + | |
To output data back to Dinamica EGO, the user must call a set of functions designed for this functionality: | 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 "Keys" and another for the "Values". 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, "Keys" and "Values". |
- | === Multiply each value of the passed LookupTable by itself. === | + | |
+ | Each column can be individually accessed by using the ''$'' operator, for example: | ||
+ | |||
+ | * ''t1$Keys[ 1 ]'' will access the first key of the Lookup Table ''t1''. | ||
+ | |||
+ | * ''t2$Values[ 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 |}} | {{ ::ex1_calculate_r.png?nolink |}} | ||
+ | |||
Expression: | Expression: | ||
<code rsplus> | <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> | </code> | ||
- | \\ | + | |
- | \\ | + | ==== Extract the mean of passed Lookup Table values ==== |
- | === Extract the mean of passed LookupTable values. === | + | |
{{ ::ex2_calculate_r.png?nolink |}} | {{ ::ex2_calculate_r.png?nolink |}} | ||
+ | |||
Expression: | Expression: | ||
<code rsplus> | <code rsplus> | ||
- | tableMean <- mean( t1$Values ); | + | tableMean <- mean( t1$Value ); |
print( paste( "Mean is", tableMean ) ); | print( paste( "Mean is", tableMean ) ); | ||
outputDouble( "mean", tableMean ); | outputDouble( "mean", tableMean ); | ||
</code> | </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 |}} | {{ ::ex3_calculate_r.png?nolink |}} | ||
+ | |||
Expression: | Expression: | ||
<code rsplus> | <code rsplus> | ||
Line 112: | Line 161: | ||
dev.off(); | dev.off(); | ||
</code> | </code> | ||
+ | |||
+ | ===== Internal Name ===== | ||
+ | |||
+ | CalculateRExpression | ||
+ |