Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
calculate_r_expression [2026/07/19 22:00] hermann |
calculate_r_expression [2026/07/22 18:13] (current) hermann |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Description ===== | ===== Description ===== | ||
| - | This is a **[[ego_script#container_functors|container functor]]** that calls R externally and processes the script's outputs as if they were part of Dinamica EGO itself. Like the other calculator functors, data is connected through hook functors placed inside its ''<nowiki>{{ … }}</nowiki>'' block. | + | This is a **[[ego_script#container_functors|container functor]]** that calls R externally with the user-defined expression. Like the other calculator functors, data is connected through hook functors placed inside its ''<nowiki>{{ … }}</nowiki>'' block. |
| ===== Inputs ===== | ===== Inputs ===== | ||
| Line 24: | Line 24: | ||
| ==== Expression inputs ==== | ==== Expression inputs ==== | ||
| - | Data is passed into the expression through **hook** functors placed inside the container's ''<nowiki>{{ … }}</nowiki>'' block. Hooks can be added using the //Create a hook// button on the functor bar, or by dragging them in individually. | + | Data is passed into the expression through **hook** functors placed inside the container's ''<nowiki>{{ … }}</nowiki>'' block — the same [[ego_script#verbose_form|verbose form]] hook mechanism used by the calculator functors. Hooks can be added using the //Create a hook// button on the functor bar, or by dragging them in individually. |
| * Tables and lookup tables → [[Number Table]] → available in R as ''t1'', ''t2'', …, ''t100'' | * Tables and lookup tables → [[Number Table]] → available in R as ''t1'', ''t2'', …, ''t100'' | ||
| Line 46: | Line 46: | ||
| A **table** is transferred as a [[https://en.wikibooks.org/wiki/R_Programming/Working_with_data_frames|DataFrame]], with each column likewise accessed using ''$''. Two conventions apply to tables in either direction: | A **table** is transferred as a [[https://en.wikibooks.org/wiki/R_Programming/Working_with_data_frames|DataFrame]], with each column likewise accessed using ''$''. Two conventions apply to tables in either direction: | ||
| - | * **Key columns** are marked by an asterisk (''*'') appended to their column name — this is the same convention used throughout Dinamica EGO's table representation (see [[calculate_functors#connecting_data_inputs|Connecting Data Inputs]]). | + | * **Key columns** are marked by an asterisk (''*'') appended to their column name — this is the same convention used throughout Dinamica EGO's table representation (see [[calculate_functors#connecting_data_inputs|Connecting Data Inputs]]). A key column can be Real or String, the same as any other column. |
| - | * R automatically converts string columns to **Factors** inside a ''data.frame'', but Dinamica requires plain **Character Vectors**. Always build tables with ''stringsAsFactors = FALSE'' to prevent this conversion. | + | * Each column's type is inferred from its data, the same rule that applies to any table (see [[ego_script#constants|Constants]]): a numeric vector produces a Real column, a character vector produces a String column. R automatically converts string columns to **Factors** inside a ''data.frame'', and a Factor is neither of those — Dinamica requires plain **Character Vectors** to infer String correctly. Always build tables with ''stringsAsFactors = FALSE'' to prevent this conversion. |
| For further detail on the underlying table representation, see [[external_communication#table|External Communication]]. | For further detail on the underlying table representation, see [[external_communication#table|External Communication]]. | ||
| Line 53: | Line 53: | ||
| ==== Expression outputs ==== | ==== Expression outputs ==== | ||
| - | Values are returned to Dinamica by calling one of the following functions from the R script. Every call requires an identifier as its first parameter — the name Dinamica uses to place the value into the output struct: | + | Values are returned to Dinamica by calling one of the following functions from the R script. Every call requires an identifier as its first parameter — the name Dinamica uses to place the value into the output struct — and the value itself, which can be constructed inline, as in the examples below, or supplied as a variable: |
| - | ^ Function ^ Output type ^ Example ^ | + | ^ Function ^ Output type ^ Notes ^ Example ^ |
| - | | ''outputDouble()'' | Real | ''outputDouble("myDouble", 3.14)'' | | + | | ''outputDouble()'' | Real | Accepts any numeric value. | ''outputDouble("myDouble", 3.14)'' | |
| - | | ''outputNumberVector()'' | Tuple | ''outputNumberVector("myTuple", c(1:10))'' | | + | | ''outputNumberVector()'' | Tuple | Accepts any collection of numbers. | ''outputNumberVector("myTuple", c(1:10))'' | |
| - | | ''outputString()'' | String | ''outputString("myString", "This is a string")'' | | + | | ''outputString()'' | String | Accepts any string value. | ''outputString("myString", "This is a string")'' | |
| - | | ''outputLookupTable()'' | Lookup Table | ''outputLookupTable("myLUT", c(1:10), c(1:10) * 10)'' | | + | | ''outputLookupTable()'' | [[Lookup Table Type|Lookup Table]] | Requires two number vectors of equal length — one for the keys, one for the values. Lookup tables are always Real-typed on both sides; there is no String option. | ''outputLookupTable("myLUT", c(1:10), c(1:10) * 10)'' | |
| - | | ''outputTable()'' | Table | ''outputTable("myTable", data.frame(State = c("Massachusetts", "Massachusetts"), City = c("Boston", "Chelsea"), Population = c(667137, 39398), stringsAsFactors = FALSE), 2)'' | | + | | ''outputTable()'' | Table | Requires a table built with the [[https://www.r-tutor.com/r-introduction/data-frame|data.frame]] function, using ''stringsAsFactors = FALSE'' as described above. Its optional second parameter (default ''1'') sets how many leading columns, from the left, are key columns. | ''outputTable("myTable", data.frame(State = c("Massachusetts", "Massachusetts"), City = c("Boston", "Chelsea"), Population = c(667137, 39398), stringsAsFactors = FALSE), 2)'' | |
| - | + | ||
| - | Values passed to these functions can be constructed inline, as in the examples above, or supplied as variables. | + | |
| - | + | ||
| - | * Any numeric value can be passed to ''outputDouble()''. | + | |
| - | * Collections of numbers are valid number vectors for ''outputNumberVector()''. | + | |
| - | * A [[Lookup Table Type|lookup table]] requires two number vectors of equal length — one for the keys, one for the values. | + | |
| - | * ''outputTable()'' requires a table built with the [[http://www.r-tutor.com/r-introduction/data-frame|data.frame]] function, using ''stringsAsFactors = FALSE'' as described above. Its optional second parameter (default ''1'') sets how many leading columns, from the left, are key columns. | + | |
| ==== Retrieving outputs ==== | ==== Retrieving outputs ==== | ||
| Line 84: | Line 77: | ||
| ==== Installing packages ==== | ==== Installing packages ==== | ||
| - | Packages are installed by calling ''dinamicaPackage("packageName")'' from within the expression — one call per package. Unlike [[Calculate Python Expression]], there is no separate input port for listing packages; ''dinamicaPackage()'' is the only mechanism available. | + | Packages are installed by calling ''dinamicaPackage("packageName")'' from within the expression — one call per package. Unlike [[calculate_python_expression|Calculate Python Expression]], there is no separate input port for listing packages; ''dinamicaPackage()'' is the only mechanism available. |
| ''dinamicaPackage("packageName")'' also acts as R's ''library()'' call: when the package name matches the name of the module to load, calling it both installs the package (if not already present) and loads it, in a single call. | ''dinamicaPackage("packageName")'' also acts as R's ''library()'' call: when the package name matches the name of the module to load, calling it both installs the package (if not already present) and loads it, in a single call. | ||
| Line 178: | Line 171: | ||
| ==== Writing the expression in EGO Script ==== | ==== Writing the expression in EGO Script ==== | ||
| - | Like [[Calculate Python Expression]], the ''Expression'' input is type [[ego_script#constants|Code]], which is represented in the underlying script using base64 encoding — impractical to write or edit directly as a text constant. Instead, connect a ''String'' carrier functor containing the R expression text to the ''Expression'' port; its output is accepted wherever a ''Code'' value is expected. Since only this one output is needed, the carrier can be [[ego_script#inline_syntax|inlined]] directly into the call. | + | Like [[calculate_python_expression|Calculate Python Expression]], the ''Expression'' input is type [[ego_script#constants|Code]], which is represented in the underlying script using base64 encoding — impractical to write or edit directly as a text constant. Instead, connect a ''String'' carrier functor containing the R expression text to the ''Expression'' port; its output is accepted wherever a ''Code'' value is expected. Since only this one output is needed, the carrier can be [[ego_script#inline_syntax|inlined]] directly into the call. |
| This limitation is specific to hand-written EGO Script. In the Dinamica EGO GUI, the ''Expression'' port has a dedicated code editor that edits the ''Code'' value directly — the ''String'' carrier workaround is only necessary when writing or editing the ''.ego'' file as text. | This limitation is specific to hand-written EGO Script. In the Dinamica EGO GUI, the ''Expression'' port has a dedicated code editor that edits the ''Code'' value directly — the ''String'' carrier workaround is only necessary when writing or editing the ''.ego'' file as text. | ||
| Line 200: | Line 193: | ||
| CalculateRExpression | CalculateRExpression | ||
| - | |||
| - | ===== See Also ===== | ||
| - | |||
| - | * [[r_coupling|R Coupling]] | ||
| - | * [[Calculate Python Expression]] | ||
| - | * [[External Communication]] | ||
| - | * [[ego_script#container_functors|EGO Script — Container Functors]] | ||
| - | * [[ego_script#verbose_form|EGO Script — Verbose Form (Hooks)]] | ||
| - | * [[calculate_functors|Calculate Functors — Complete Operator Documentation]] | ||
| - | |||
| - | |||