Calculate R Expression

This is a 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 {{ … }} block.

None.

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.

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 (see Connecting Data Inputs). 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 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.

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:

CalculateRExpression returns a single 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:

Each functor takes two inputs: the Struct returned by CalculateRExpression, and the name of the entry to extract as a string constant.

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");

There are two ways to run R scripts from CalculateRExpression — though only the local installation is available on Linux.

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.

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.
• 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.

The following examples use a consistent set of inputs:

• t1 — a lookup table of land cover patches, mapping Key (patch identifier) to Value (patch area)
• 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:

patchMean <- mean(t1$Value);
patchTotal <- sum(t1$Value);
print(paste("Processed", length(t1$Value), "patches"));
 
outputDouble("meanArea", patchMean);
outputDouble("totalArea", patchTotal);

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.

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);

Like Calculate Python Expression, the Expression input is type 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 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.

result := CalculateRExpression (String $"(
aboveThreshold <- t1$Value >= v1;
outputLookupTable("filteredPatches", t1$Key[aboveThreshold], t1$Value[aboveThreshold]);
)") .no {{
    NumberTable landCoverAreas 1;
    NumberValue minimumArea    1;
}};
filteredPatches := ExtractStructLookupTable result "filteredPatches";

Integration

CalculateRExpression