Calculate R Expression
Description
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.
This is the preferred way of coupling Dinamica EGO and R. See Coupling with R for the other ways, which exchange data with an R session running alongside the model.
Inputs
| Name | Type | Description |
|---|---|---|
| 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 below. |
| Treat Warning As Errors | Boolean Value Type | If true, warnings raised by the R script are treated as errors. |
Optional Inputs
None.
Outputs
| Name | Type | Description |
|---|---|---|
| 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
Notes
Expression inputs
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 - Scalar values → Number Value → available as
v1,v2, …,v100 - 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 — Complete Operator Documentation for the general hook mechanism and syntax.
Tables and lookup tables
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:
# Access the third key and its corresponding value in lookup table t1
patchId <- t1$Key[3];
patchArea <- t1$Value[3];
A table is transferred as a 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. 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: 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 = FALSEto prevent this conversion.
The same conventions apply when tables are exchanged through a communication session; see Coupling with R.
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 — and the value itself, which can be constructed inline, as in the examples below, or supplied as a variable:
| Function | Output type | Notes | Example |
|---|---|---|---|
| outputDouble() | Real | Accepts any numeric value. | outputDouble(“myDouble”, 3.14) |
| outputNumberVector() | Tuple | Accepts any collection of numbers. | outputNumberVector(“myTuple”, c(1:10)) |
| outputString() | String | Accepts any string value. | outputString(“myString”, “This is a string”) |
| outputLookupTable() | 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 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
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 |
|---|---|
| Extract Struct Number | A value passed to outputDouble() |
| Extract Struct Tuple | A value passed to outputNumberVector() |
| Extract Struct String | A value passed to outputString() |
| Extract Struct Lookup Table | A value passed to outputLookupTable() |
| Extract Struct Table | A value passed to outputTable() |
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
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("moments");
Setup
Dinamica EGO starts and stops the R interpreter automatically whenever the functor runs. There are two ways to provide the interpreter — though only the local installation is available on Linux.
Dinamica EGO Enhancement Plugin
Windows only. Download and install the Dinamica EGO Enhancement Plugin. It contains a custom R interpreter with several pre-installed packages, and needs no further configuration. Only the pre-installed packages can be used; to install other packages, use a local R installation.
Local R installation
On Linux, this is the only option. On Windows, it can be used as an alternative to the plugin, with the advantage that any package can be installed with dinamicaPackage(). Either way, it requires:
- R installed on the machine, with the Rscript executable (Rscript.exe on Windows) present in its bin sub-folder.
- On Windows, a compatible Rtools.
- The Dinamica package for R installed and at its latest version. See Installing the Dinamica Package for R.
To select the local installation, go to Tools → Options → Integration tab → R, check “Use alternative R installation”, enter the path to Rscript, and click “Integrate with Alternative R”.
The path to Rscript can also be set with the environment variable DINAMICA_EGO_X_ALTERNATIVE_PATH_FOR_R, and the CRAN mirror used to install packages with DINAMICA_EGO_X_R_CRAN_MIRROR; see Environment Variables. On Linux, when no path is configured, /usr/bin/Rscript is used.
Setting up R on Linux
The following steps were written for Ubuntu 22.04 LTS:
-
Install the build tools:
sudo apt install build-essential -
Install R, version 4.3 or higher. For other ways of installing R on Ubuntu, see CRAN’s instructions.
sudo apt install r-base - Install the Dinamica package for R.
- Select the local installation in Dinamica EGO, as described above. The path to Rscript is usually
/usr/bin/Rscript.
Reports an error if this functor is used without either the Enhancement Plugin or a working local R installation configured.
Raises an error if the number of Number Table hooks nested inside this container exceeds the capacity of the external communication message queue.
Examples
The Guidebook dataset includes simple example models in guidebook dinamica\extras\examples\various applications\calculate r expression.
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.
Compute the mean and total area across all patches, and report progress to the Message Log:
patchMean <- mean(t1$Value);
patchTotal <- sum(t1$Value);
print(paste("Processed", length(t1$Value), "patches"));
outputDouble("meanArea", patchMean);
outputDouble("totalArea", patchTotal);
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:
aboveThreshold <- t1$Value >= v1;
filteredKeys <- t1$Key[aboveThreshold];
filteredValues <- t1$Value[aboveThreshold];
outputLookupTable("filteredPatches", filteredKeys, filteredValues);
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:
patchFlags <- data.frame(
PatchId = t1$Key,
Area = t1$Value,
MeetsThreshold = t1$Value >= v1,
stringsAsFactors = FALSE
);
names(patchFlags)[3] <- s1;
outputTable("patchSummary", patchFlags, 1);
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:
dinamicaPackage("moments");
patchMean <- mean(t1$Value);
patchStdDev <- sd(t1$Value);
patchSkewness <- skewness(t1$Value);
isOutlier <- abs(t1$Value - patchMean) > 2 * patchStdDev;
outlierPatches <- data.frame(
PatchId = t1$Key[isOutlier],
Area = t1$Value[isOutlier],
stringsAsFactors = FALSE
);
outputDouble("meanArea", patchMean);
outputDouble("stdDevArea", patchStdDev);
outputDouble("skewnessArea", patchSkewness);
outputTable("outlierPatches", outlierPatches, 1);
Writing the expression in EGO Script
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.
result := CalculateRExpression $"(
aboveThreshold <- t1$Value >= v1;
outputLookupTable("filteredPatches", t1$Key[aboveThreshold], t1$Value[aboveThreshold]);
)" .no {{
NumberTable landCoverAreas 1;
NumberValue minimumArea 1;
}};
filteredPatches := ExtractStructLookupTable result "filteredPatches";
Here .no is the value of Treat Warning As Errors.
Internal Name
CalculateRExpression