Calculate R Expression

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.

None.

Integration

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. 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 = 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:

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:

Each functor takes two inputs: the Struct returned by Calculate R Expression, 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 Calculate R Expression — 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”.

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.

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

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.

CalculateRExpression