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

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

[[Functor List#Integration | Integration]]

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

<code rsplus>
# Access the third key and its corresponding value in lookup table t1
patchId <- t1$Key[3];
patchArea <- t1$Value[3];
</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:

  * 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]].

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

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

<code rsplus>
dinamicaPackage("moments");
</code>

==== Setup ====

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

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

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.

==== Examples ====

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:

<code rsplus>
patchMean <- mean(t1$Value);
patchTotal <- sum(t1$Value);
print(paste("Processed", length(t1$Value), "patches"));

outputDouble("meanArea", patchMean);
outputDouble("totalArea", patchTotal);
</code>

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:

<code rsplus>
aboveThreshold <- t1$Value >= v1;
filteredKeys <- t1$Key[aboveThreshold];
filteredValues <- t1$Value[aboveThreshold];

outputLookupTable("filteredPatches", filteredKeys, filteredValues);
</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:

<code rsplus>
patchFlags <- data.frame(
    PatchId = t1$Key,
    Area = t1$Value,
    MeetsThreshold = t1$Value >= v1,
    stringsAsFactors = FALSE
);
names(patchFlags)[3] <- s1;

outputTable("patchSummary", patchFlags, 1);
</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:

<code rsplus>
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);
</code>

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

<code>
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";
</code>

Here .no is the value of Treat Warning As Errors.

===== Internal Name =====

CalculateRExpression