Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | |||
|
calculate_r_expression [2026/08/18 02:29] hermann |
calculate_r_expression [2026/08/28 03:14] (current) hermann Sync from local documentation review |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Description ===== | ===== Description ===== | ||
| - | 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. | + | This is a container functor that calls R externally with a user-defined expression. Like the other calculator functors, data is connected through hook functors placed inside its block. |
| ===== Inputs ===== | ===== Inputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ | + | ^ Name ^ Type ^ Description ^ |
| - | | Expression | [[code_type|Code]] | The expression that will run on R. Written directly as a Code constant using its own raw string syntax — see [[#writing_the_expression_in_ego_script|Writing the expression in EGO Script]] below. | | + | | Expression | [[Code Type]] | The expression to run on R. Written directly as a Code constant using its own raw string syntax — see [[#writing_the_expression_in_ego_script|Writing the expression in EGO Script]] below. | |
| - | | Treat Warning As Errors | [[Boolean Value Type]] | Warnings raised by the R script will be treated as errors. | | + | | Treat Warning As Errors | [[Boolean Value Type]] | If true, warnings raised by the R script are treated as errors. | |
| ===== Optional Inputs ===== | ===== Optional Inputs ===== | ||
| Line 17: | Line 17: | ||
| ===== Outputs ===== | ===== Outputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ | + | ^ Name ^ Type ^ Description ^ |
| - | | result | [[struct_type|Struct]] | A struct containing the output values generated by the expression. | | + | | Result | [[Struct Type]] | Struct containing the output values generated by the expression, one entry per call to an output function in the R script. | |
| + | |||
| + | ===== Group ===== | ||
| + | |||
| + | [[Functor List#Integration | Integration]] | ||
| ===== Notes ===== | ===== Notes ===== | ||
| Line 24: | Line 28: | ||
| ==== Expression inputs ==== | ==== Expression inputs ==== | ||
| - | 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. | + | Data is passed into the expression through hook functors placed inside the container's block — the same 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 |
| - | * Scalar values → [[Number Value]] → available as ''v1'', ''v2'', …, ''v100'' | + | * Scalar values → [[Number Value]] → available as v1, v2, …, v100 |
| - | * Strings → [[Number String]] → available as ''s1'', ''s2'', …, ''s100'' | + | * Strings → [[Number String]] → available as s1, s2, …, s100 |
| - | Maps cannot be connected — this functor has no cell context. There is no shorthand notation; see [[calculate_functors|Calculate Functors — Complete Operator Documentation]] for the general hook mechanism and syntax. | + | Maps cannot be connected — this functor has no cell context. There is no shorthand notation; see [[Calculate Functors|Calculate Functors — Complete Operator Documentation]] for the general hook mechanism and syntax. |
| === Tables and lookup tables === | === Tables and lookup tables === | ||
| Line 36: | Line 40: | ||
| Lookup tables and tables require extra care, since each is transferred to R using a different representation. | Lookup tables and tables require extra care, since each is transferred to R using a different representation. | ||
| - | A **lookup table** is transferred as a list with two columns, ''Key'' and ''Value''. Each column is accessed with the ''$'' operator: | + | A lookup table is transferred as a list with two columns, Key and Value. Each column is accessed with the $ operator: |
| <code rsplus> | <code rsplus> | ||
| Line 44: | Line 48: | ||
| </code> | </code> | ||
| - | 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]]). A key column can be Real or String, the same as any other column. | + | * Key columns are marked by an asterisk (*) appended to their column name — this is the same convention used throughout Dinamica EGO's table representation. A key column can be Real or String, the same as any other column. |
| - | * 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. | + | * Each column's type is inferred from its data, the same rule that applies to any table: 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]]. |
| ==== Expression outputs ==== | ==== Expression outputs ==== | ||
| Line 55: | Line 59: | ||
| 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: | 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 ^ Notes ^ Example ^ | + | ^ Function ^ Output type ^ Notes ^ Example ^ |
| - | | ''outputDouble()'' | Real | Accepts any numeric value. | ''outputDouble("myDouble", 3.14)'' | | + | | outputDouble() | Real | Accepts any numeric value. | outputDouble("myDouble", 3.14) | |
| - | | ''outputNumberVector()'' | Tuple | Accepts any collection of numbers. | ''outputNumberVector("myTuple", c(1:10))'' | | + | | outputNumberVector() | Tuple | Accepts any collection of numbers. | outputNumberVector("myTuple", c(1:10)) | |
| - | | ''outputString()'' | String | Accepts any string value. | ''outputString("myString", "This is a string")'' | | + | | outputString() | String | Accepts any string value. | outputString("myString", "This is a string") | |
| - | | ''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)'' | | + | | 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 | 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)'' | | + | | 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) | |
| ==== Retrieving outputs ==== | ==== Retrieving outputs ==== | ||
| - | ''CalculateRExpression'' returns a single [[struct_type|Struct]] value (via its ''result'' output port) containing every value passed to an ''output*()'' function. To retrieve individual values from that struct, use the corresponding functor from the //Integration// group: | + | Calculate R Expression returns a single [[Struct Type]] value (via its Result output port) containing every value passed to an output*() function. To retrieve individual values from that struct, use the corresponding functor from the Integration group: |
| - | ^ Functor ^ Retrieves ^ | + | ^ Functor ^ Retrieves ^ |
| - | | [[Extract Struct Number]] | A value passed to ''outputDouble()'' | | + | | [[Extract Struct Number]] | A value passed to outputDouble() | |
| - | | [[Extract Struct Tuple]] | A value passed to ''outputNumberVector()'' | | + | | [[Extract Struct Tuple]] | A value passed to outputNumberVector() | |
| - | | [[Extract Struct String]] | A value passed to ''outputString()'' | | + | | [[Extract Struct String]] | A value passed to outputString() | |
| - | | [[Extract Struct Lookup Table]] | A value passed to ''outputLookupTable()'' | | + | | [[Extract Struct Lookup Table]] | A value passed to outputLookupTable() | |
| - | | [[Extract Struct Table]] | A value passed to ''outputTable()'' | | + | | [[Extract Struct Table]] | A value passed to outputTable() | |
| - | Each functor takes two inputs: the ''Struct'' returned by ''CalculateRExpression'', and the name of the entry to extract as a string constant. | + | Each functor takes two inputs: the Struct returned by Calculate R Expression, and the name of the entry to extract as a string constant. |
| ==== Installing packages ==== | ==== Installing packages ==== | ||
| - | 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. | + | 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. |
| - | ''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. |
| <code rsplus> | <code rsplus> | ||
| Line 87: | Line 91: | ||
| ==== Setup ==== | ==== Setup ==== | ||
| - | There are two ways to run R scripts from ''CalculateRExpression'' — though only the local installation is available on Linux. | + | There are two ways to run R scripts from Calculate R Expression — though only the local installation is available on Linux. |
| === Dinamica EGO Enhancement Plugin === | === Dinamica EGO Enhancement Plugin === | ||
| - | Windows only. Download and install the [[plugins_4|Dinamica EGO Enhancement Plugin]]. It contains everything needed to run R scripts inside Dinamica EGO, with no further configuration. | + | Windows only. Download and install the [[Dinamica EGO Enhancement Plugin]]. It contains everything needed to run R scripts inside Dinamica EGO, with no further configuration. |
| === Local R installation === | === Local R installation === | ||
| Line 97: | Line 101: | ||
| On Linux, this is the only option — Dinamica EGO always uses the R installation already present on the system. On Windows, it can be used as an alternative to the plugin. Either way, it requires: | On Linux, this is the only option — Dinamica EGO always uses the R installation already present on the system. On Windows, it can be used as an alternative to the plugin. Either way, it requires: | ||
| - | * R installed on the machine, with the ''Rscript'' executable (''Rscript.exe'' on Windows) present in its ''bin'' sub-folder. | + | * R installed on the machine, with the Rscript executable (Rscript.exe on Windows) present in its bin sub-folder. |
| - | * The [[external_communication|Dinamica package]] for R installed and at its latest version. | + | * The Dinamica package for R installed and at its latest version. |
| - | On Windows, this alternative installation is selected in the Dinamica EGO GUI by going to //Tools// → //Options// → //Integration// tab and enabling //Use alternative R installation for Calculate R Expression//. | + | On Windows, this alternative installation is selected in the Dinamica EGO GUI by going to Tools → Options → Integration tab and enabling "Use alternative R installation for Calculate R Expression". |
| - | ==== Examples ==== | + | Reports an error if this functor is used without either the Enhancement Plugin or a working local R installation configured. |
| - | The following examples use a consistent set of inputs: | + | Raises an error if the number of Number Table hooks nested inside this container exceeds the capacity of the external communication message queue. |
| + | |||
| + | ==== Examples ==== | ||
| - | * ''t1'' — a lookup table of land cover patches, mapping ''Key'' (patch identifier) to ''Value'' (patch area) | + | The following examples use a consistent set of inputs: t1 is a lookup table of land cover patches mapping Key (patch identifier) to Value (patch area); v1 is a scalar minimum area threshold; and s1 is a string giving the name to use for a threshold-flag column. |
| - | * ''v1'' — a scalar minimum area threshold | + | |
| - | * ''s1'' — a string giving the name to use for the threshold flag column | + | |
| Compute the mean and total area across all patches, and report progress to the Message Log: | Compute the mean and total area across all patches, and report progress to the Message Log: | ||
| Line 121: | Line 125: | ||
| </code> | </code> | ||
| - | > **Note:** The ''print()'' call is visible in Dinamica EGO's Message Log, shown as a Result-level message. Log levels are ordered Unconditional, Error, Warning, Result, Info, Info2, Debug, Debug2 — messages printed from R are only shown when the Message Log level is set to Result or a more verbose level; at Unconditional, Error, or Warning they are suppressed. | + | The print() call is visible in Dinamica EGO's Message Log, shown as a Result-level message. Log levels are ordered Unconditional, Error, Warning, Result, Info, Info2, Debug, Debug2 — messages printed from R are only shown when the Message Log level is set to Result or a more verbose level; at Unconditional, Error, or Warning they are suppressed. |
| Filter the lookup table down to patches whose area meets the threshold, and return the filtered lookup table: | Filter the lookup table down to patches whose area meets the threshold, and return the filtered lookup table: | ||
| Line 133: | Line 137: | ||
| </code> | </code> | ||
| - | Build and return a table with one row per patch, including a column that flags whether each patch meets the threshold. The column's name is taken from the passed string ''s1'' rather than being hard-coded: | + | Build and return a table with one row per patch, including a column that flags whether each patch meets the threshold. The column's name is taken from the passed string s1 rather than being hard-coded: |
| <code rsplus> | <code rsplus> | ||
| Line 147: | Line 151: | ||
| </code> | </code> | ||
| - | Install the ''moments'' package and use it to compute the skewness of the patch area distribution — a statistic not available in base R — then flag patches whose area is a statistical outlier: | + | Install the moments package and use it to compute the skewness of the patch area distribution -- a statistic not available in base R -- then flag patches whose area is a statistical outlier: |
| <code rsplus> | <code rsplus> | ||
| Line 171: | Line 175: | ||
| ==== Writing the expression in EGO Script ==== | ==== Writing the expression in EGO Script ==== | ||
| - | Like [[calculate_python_expression|Calculate Python Expression]], the ''Expression'' input is type [[code_type|Code]]. It can be filled in directly as a text constant, using Code Type's own raw string syntax — the same ''$"<delimiter>( raw_characters )<delimiter>"'' form used by String constants. This is also the form the Dinamica EGO GUI's dedicated code editor generates when it writes the ''Expression'' port's value, so a hand-written script and one produced by the GUI take the same shape. See [[code_type|Code Type]] for the full grammar, including the base64 alternative form. | + | Like [[Calculate Python Expression]], the Expression input is type [[Code Type]]. It can be filled in directly as a text constant, using Code Type's own raw string syntax -- the same ''$"<delimiter>( raw_characters )<delimiter>"'' form used by String constants. This is also the form the Dinamica EGO GUI's dedicated code editor generates when it writes the Expression port's value, so a hand-written script and one produced by the GUI take the same shape. See [[Code Type]] for the full grammar, including the base64 alternative form. |
| <code> | <code> | ||
| Line 184: | Line 188: | ||
| </code> | </code> | ||
| - | ===== Group ===== | + | Here .no is the value of Treat Warning As Errors. |
| - | + | ||
| - | [[Functor List#Integration|Integration]] | + | |
| ===== Internal Name ===== | ===== Internal Name ===== | ||