EGO Script is a simple, text-based language for creating and editing Dinamica EGO models. A model written in this format is stored in a file with the .ego extension. An .ego file is just another way of describing a model — it is equivalent to the XML form Dinamica EGO uses internally. Because the two are interchangeable, you can write a model as an EGO script, open it in the graphical interface, edit it there, and save it again, moving freely between the textual and visual representations. See Basic Data Flow for the execution model shared by both representations; this tutorial covers the textual notation specifically.

Caution: When you round-trip a model through the graphical interface, the interface can rewrite a model's layout and the format of its inputs and outputs according to the options currently in effect, so a script reopened and saved from the GUI may not come back byte-for-byte identical to what you wrote. This is normal, and the resulting model is equivalent.

Tip: There are two practical ways to move between the visual and textual representations. First, a whole model can be saved as a .ego file from the GUI via File → Save Model, and reopened via File → Open Model. Second, any selection of functors in the GUI sketch — or the entire model — can be copied to the clipboard and pasted directly into an external text editor as an EGO Script fragment; conversely, any EGO Script fragment copied from a text editor can be pasted straight into the GUI sketch.

This tutorial introduces the language from the ground up: the structure of a model, how functors are called and wired together, how containers and properties work, and the shorthand used to write expressions.

A complete EGO script model can be as short as the example below. It loads a raster map and saves a copy of it in a different format:

Script {{
  // Loads a GeoTiff map.
  x := LoadMap "c:/map.tif";
  // Saves an ERMapper map.
  SaveMap x "c:/map-copy.ers";
}};

Even this small example shows every essential element of the language.

The Script {{ }} block delimits the script text. A single file can carry several script elements, and the Script block is what groups them together. For backward compatibility with earlier versions, this declaration may be omitted.

Tip: Omitting the Script block is discouraged — always wrap a model in an explicit Script block.

Each statement inside the block calls a functor — a processing unit that consumes inputs and produces outputs. The second line of the example calls a Load Map to load the GeoTiff file “map.tif”, and binds the resulting map to the variable x. Two conventions are worth noting right away. First, a functor's name is written without spaces (LoadMap, not Load Map). Second, a variable is always defined and bound with the := operator. The third line calls Save Map to write the map held by x to an ERMapper file named “c:/map-copy.ers”. The position of a value relative to the functor name determines whether it is an input or an output:

• Values and variables written after the functor name are bound to its input ports.
• Variables written before the := operator are bound to its output ports.

So in x := LoadMap “c:/map.tif”, the string “c:/map.tif” is an input and x receives the output; in SaveMap x “c:/map-copy.ers”, both x and the filename are inputs, and the call produces no output that the script needs to keep.

A variable name must begin with an underscore or a letter, and may be followed by any combination of underscores, letters, and digits ([_a-zA-Z][_a-zA-Z0-9]*). Variable names are case-sensitive.

Variables are the primary mechanism by which functors pass data to one another, and data dependencies are the main source of execution ordering. A variable must be bound by the functor that produces it before any functor that reads it can run — this is what creates a dependency between the two. Functors that do not share a variable, directly or through a chain of intermediate variables, have no dependency on each other and may execute in any order or at the same time. Container functors, described in the Container functors section of the reference, impose a second ordering constraint on top of this. This is a property of the underlying functor graph, not of EGO Script specifically — see Basic Data Flow.

Note: The position of a functor definition in the script file does not determine when it runs. Unless two functors are connected by a data dependency — directly or through a chain of variables — never assume anything about their relative execution order. The only exception is containers, covered later in this section.

The sequence // begins a comment, which continues to the end of the line. The two comment lines in the example document what each step does. Comments are more than annotations — they attach to the functor that follows them and are preserved with the model; the Comments section of the reference describes this in detail.

This section describes how a functor call is written in EGO Script, the three interchangeable styles for supplying its inputs, how container functors hold and communicate with the functors nested inside them, the shorthand notation used to write the calculator functors that evaluate expressions, and how comments and properties annotate a model.

A functor call binds outputs — the variables written before := — and consumes inputs — the values, variables, and constants written after the functor name. Every functor defines a fixed set of typed ports for its inputs and outputs:

areaTable := CalcAreas landscape .no;

Here Calc Areas reads two inputs (landscape and the constant .no) and produces one output, bound to the variable areaTable. Constants are written with a leading dot (.no, .default, .int32, .none) — see Constants below.

Inputs can be supplied in three interchangeable styles — positional, nominal, and inline. The styles may be mixed freely between calls, and even within a single call.

Constants supply a fixed value directly to an input port, without connecting a functor. Despite often looking similar in syntax, every constant is interpreted and validated according to the type of the port it is supplied to — a value that is valid for one port type may be rejected by another. They come in four forms.

Numeric literals — integer or real values written directly: 0, 250, 3.14.

Text constants — text enclosed in double quotes. Despite looking identical in syntax, text constants are interpreted and validated according to the port's type. The types that accept the basic "text" form include String, MapFilename, TableFilename, LookupTableFilename, WeightsFilename, GenericFilename, Folder, and Name — but each imposes its own validation:

• Filename ports (MapFilename, TableFilename, etc.) typically verify that the file extension is appropriate for that type. For example, “test.tif” is accepted by a MapFilename port but rejected by a TableFilename port, since .tif is not a valid table file extension.
• Name ports only accept identifiers that follow the same naming rules as variables — starting with a letter or underscore, followed only by letters, digits, and underscores. “distance_to_roads” is valid; “Distance To Roads” is not.

// used as a MapFilename
"c:/data/landscape.tif"
// used as a Name
"distanceToRoads"

For String ports that contain line breaks or double-quote characters, use the extended form $“DELIMITER(content)DELIMITER”. The content is everything between the opening ( and the closing ), and the DELIMITER — any sequence of characters placed between the " and the (, including empty — makes the closing )“ unambiguous. The delimiter must be identical on both sides. This extended form is only accepted by String ports:

// basic form — line break inside the content
$"(Hello
world)"

// X as delimiter — content contains )" which would otherwise terminate the basic form early
$"X(some )" text)X"

Dot constants — a leading dot followed by a keyword: .yes, .no, .int32, .default. Each data type defines its own set of dot constants and the constants accepted by a port depend entirely on its type. Two dot constants are predefined and available for any input port regardless of type:

• .UNBOUND — the port is not connected, or its connection is deliberately being ignored. This appears in particular when a script fragment is copied from the GUI to a text editor and some of the original connections are not part of the copied selection.
• .none — the port is intentionally left without a value. Valid only for optional nullable input ports.

Structured constants — complex values enclosed in square brackets [ … ], specific to individual functors and can be multi-line: [ 2→1 0.05 ], [ “Key” “Value” ].

A call can mix all forms with variable references in a single argument list:

landscape := LoadCategoricalMap "c:/data/landscape.tif" .none .default 0;

Here “c:/data/landscape.tif” is a map filename constant (the filename port is type MapFilename), .none leaves the nullable nullValue port without a value, .default is a storage mode dot constant, and 0 is a numeric literal.

changes := CalcChangeMatrix landscape [ 2->1 0.05 ];

Here [ 2→1 0.05 ] is a structured constant representing a transition matrix with a 5% rate from class 2 to class 1.

Note: Code — the type used for expression inputs such as the Python code in Calculate Python Expression — is not a text constant. Code values are stored as base64 in the underlying script, making them impractical to write directly. When a port expects a Code value, supply a String carrier functor containing the expression text; the automatic String → Code conversion handles the rest.

In positional syntax, arguments fill the input ports in order: the first argument fills the first port, the second fills the second, and so on.

landscape := LoadCategoricalMap "c:/landscape.tif";
areaTable := CalcAreas landscape .no;

Omitting optional inputs. A functor's optional input ports always come after its required ones. In positional syntax you may stop supplying arguments early, but you cannot skip an optional input and then supply a later one — once you omit a port, every port after it is omitted too. To leave a gap, use nominal syntax (described below) for that call.

Load Categorical Map, for example, takes a required filename followed by several optional inputs; this call supplies the first few of them positionally and omits the rest:

landscape := LoadCategoricalMap "c:/landscape.ers" .no .no 0 0 .none .none;

Discarding outputs. A functor may return several outputs. Write an underscore (_) in any output position to discard that output. When you want only one output from the middle of the list, underscores act as placeholders for the positions you skip:

// GetProjectionInfo returns nine outputs; keep only the seventh (the coordinate type):
_ _ _ _ _ _ coordinateType _ _ := GetProjectionInfo landscape;

// GetElevationGraphInfo returns three outputs; keep only the first:
patchInfo _ _ := GetElevationGraphInfo elevationGraph .no .no;

In nominal syntax (also referred to as named parameters in the Dinamica EGO GUI options), inputs are enclosed in a pair of single curly braces { } and bound by port name: each entry is written as portName = value, with entries separated by commas. Order does not matter, and any optional port may be omitted regardless of position. See ports for a full description of port properties including types, nullability, and default values. This is the clearest style for functors with many optional inputs:

patchMap := CalcPatchLabelMap {
    source = elevationMap,
    initialPatchLabel = 1,
    onlyOrthogonalsAreAllowed = .no,
    windowLines = 3,
    windowColumns = 3,
    cellType = .int32,
    nullValue = .default,
    patchLabelsAreSparse = .no,
    useSequentialPatchLabels = .no
};

Note: Port names in the script use camelCase with a lowercase first letter (e.g. cellType, resultIsSparse). In the GUI the same ports are displayed with spaces between words and all words capitalised (e.g. “Cell Type”, “Result Is Sparse”). The same conversion rules that govern functor aliases and variable names apply here — see Alias and variable name conversion.

Note: The single braces { } used here for nominal syntax are distinct from the double braces {{ }} used to delimit a container functor's block of contained functors.

Outputs follow the opposite rule. An output is bound by name as variable = portName — the variable you choose on the left, the functor's output port name on the right — also inside single braces { }, placed before :=:

{ areaTable = areas } := CalcAreas { source = landscape };

When a functor produces multiple outputs, all of them can be bound in a single braces block, separated by commas:

{ woeCoefficients = weights, woeReport = report } := DetermineWeightsOfEvidenceCoefficients initialLandscape finalLandscape ranges;

Any output can be replaced with _ to discard it when only some outputs are needed.

So inputs read portName = value while outputs read variable = portName. The two directions are summarized below:

Styles may be combined. A call can take positional inputs but bind a named output, or vice versa:

landscape := LoadCategoricalMap { filename = "c:/landscape.tif" };
{ areaTable = areas } := CalcAreas landscape;
SaveTable { table = areaTable, filename = "c:/areas.csv" };

The port names used in nominal syntax are the input and output names defined by each functor (for instance, Calc Patch Label Map defines the inputs source, initialPatchLabel, windowLines, and so on). Names are case-sensitive.

Inline syntax nests one call directly inside another instead of binding an intermediate variable. The nested call is wrapped in parentheses, and its single output is passed straight into the enclosing input port — the same idea as nesting function calls in conventional programming languages.

These two fragments are equivalent. The first names an intermediate variable:

landscape := LoadCategoricalMap { filename = "c:/landscape.tif" };
{ areaTable = areas } := CalcAreas landscape;

The second inlines the LoadCategoricalMap call into the CalcAreas call:

{ areaTable = areas } := CalcAreas (LoadCategoricalMap { filename = "c:/landscape.tif" });

Inline calls nest to any depth and combine with the other styles. This call computes a column with one functor and feeds it straight into another that adds the column to a table, which is in turn fed into a third functor:

spatialIndex := CreateSpatialIndexFor2DPoints (AddTableColumn {
    table = yCoordinateTable,
    columnName = "X_Coordinate",
    columnType = .real,
    columnIndex = 0,
    columnShouldBeKey = .no,
    columnValues = xCoordinateTable,
    defaultValue = .none
});

Inlining is convenient only when you need a single output from the nested call. If you need more than one of its outputs, bind it to variables instead.

Setting the @inline property on a functor prevents it from being inlined when the script is written. The same effect also applies automatically whenever any other property is defined for the functor — such as a comment, a custom alias, or any other annotation — because an inlined functor carries no separate node to attach that information to, so it would be lost. See Properties for the full list of functor properties.

A container functor is a functor that holds other functors inside it. The contained functors execute within the container's scope.

Containers are the second source of execution ordering in Dinamica EGO, alongside data dependencies. All functors inside a container execute as part of that container's execution. This means that if container B depends on container A — for example, B consumes a value produced by something inside A — then B will only start after A has fully completed. As a consequence, every functor inside B is guaranteed to run after every functor inside A, and the contents of the two containers will never execute simultaneously. See Basic Data Flow for how this fits into the broader, notation-independent execution model — including how containers also control whether and how many times their contents run.

Containers fall into a few families:

• Sequencing. Group runs its contents as a unit, with no repetition or condition. It exists to organize a model and to give a block a shared property such as a label or color.
• Conditional. If Then runs its contents only when a condition is true; If Not Then runs them only when a condition is false.
• Loops. Several containers repeat their contents. Repeat runs them a fixed number of times; For iterates over a numeric range; For Each iterates over the rows of a table; For Each Category iterates over the categories of a map; For Each Region iterates over the regions of a map; and While and Do While repeat for as long as a condition holds.
• Region management. Region Manager establishes a region context and runs its contents once for that context, exposing the region to the functors inside it.
• Error handling. Skip On Error and Skip All On Error execute their contained functors while capturing and ignoring any error that occurs. Both accept a trapAndIgnoreErrors boolean input — when set to false, they behave as a plain Group and errors are not suppressed. Both also produce an executionCompletedSuccessfully output that can be tested by subsequent functors. The two differ in what happens to results already produced when an error is raised: Skip On Error preserves the outputs of any functors that completed successfully before the error; Skip All On Error discards all of them. They are typically paired with a junction outside the container to react to the outcome — see Error-handling pattern below.

The calculator functors described later in this section are also containers: each holds the expression it evaluates, and in its verbose form holds a block of operand definitions.

The contained functors are written inside a double-brace block {{ … }} that follows the container call:

_ := Group .none {{
    attributeTable := ExtractCategoricalMapAttributes landscape regions .yes;
    cellCounts := GetTableFromKey attributeTable [ 9 ];
    countLookup := LookupTable cellCounts;
}};

Containers nest to any depth, and like any functor they may carry properties such as a label or color (see Functor properties, below).

A container exchanges data with the functors inside it through internal ports: internal output ports carry values from the container into the block, and internal input ports carry values from the block back to the container.

Not all containers are about control flow. Some functors are implemented as containers specifically to exploit the execution ordering guarantee that containers provide. In a dataflow language, two functors with no data dependency between them may execute in any order. Making a functor a container means its contents execute as part of that functor's own execution — the container starts, its contents run, then it finishes. This makes it possible to bracket a computation with side effects that are guaranteed to happen before and after it.

Print is the clearest example. It prints an initialMessage before its contents run and a finalMessage after they complete. Because the calculation lives inside the container, the ordering is guaranteed:

_ := Print "Beginning execution" "Finished execution" {{
    // Perform some complicated computation that produces a numeric result...
    result := ...;
}};

Either message can be omitted with .none. If the final message needs to include a value produced by the computation, a nested Print can be placed at the end of the body. The inner Print only runs after result is computed, since it depends on it — and Create String with Number Value is used to embed the computed value in the message string:

_ := Print "Beginning execution" .none {{
    // Perform some complicated computation that produces a numeric result...
    result := ...;

    message := CreateString "Finished execution. Result: <v1>" {{
        NumberValue result 1;
    }};
    _ := Print message .none {{ }};
}};

This would be impossible to guarantee with plain functors in a dataflow language — without the container, nothing would prevent the calculation from running before or after either print, since there is no data dependency between them.

Most container functors expose two optional sequencing ports alongside their regular inputs and outputs:

• sequenceInput — a value connected here has no effect on the computation, but forces the functor that produced that value to complete before this container starts.
• sequenceOutput — connecting this output to another container's sequenceInput forces this container to complete before the other one starts.

These ports carry no data of their own; their only purpose is to impose execution ordering. Because any data type can be connected to a sequenceInput port, the output of one container can feed directly into the next container's sequencing slot:

// ForEachCategory completes before Group starts.
sequenceOut := ForEachCategory finalLandscape .none {{
    // ...
}};
_ := Group sequenceOut {{
    // ...
}};

Note: Sequence ports are only needed when two containers have no natural data dependency between them — if one container already produces a value that the other consumes, the ordering is already established and no sequencing port is required. Before sequence ports were available, models used a forced-dependency pattern — creating a dummy data value inside one container and consuming it inside another to manufacture an artificial data dependency. This idiom still appears in older scripts but is now a last resort, used only for functors that do not expose sequenceInput and sequenceOutput ports (such as Skip On Error and Skip All On Error, which instead expose an executionCompletedSuccessfully boolean output that can serve the same purpose).

An internal output port carries a value from the container into the functors nested inside it. The container produces the value; the contained functors consume it. A loop's current iteration value and a manager object made available to a block are typical internal outputs.

An internal output port is read at the top of the block with the same variable = portName form used for ordinary outputs — your variable on the left, the port name on the right. If present, these bindings must be the first declarations inside the container block, before any functor calls. A loop, for example, exposes its current element through an internal output port named step:

ForEachCategory categorization {{
    currentCategory = step;             // read the internal output port `step`
    categoryId := Step currentCategory;
    // ...
}};

Here step is the port the loop provides, and currentCategory is the variable that receives it for use inside the block.

RegionManager provides another example. It creates a region context and exposes it to the functors inside its block through an internal output port:

RegionManager regionMap 0 {{
    manager = regionManager;            // read the internal output port `regionManager`
    allRegions := GetAllRegionsInfo manager;
}};

manager = regionManager; reads the container's internal output port regionManager into the variable manager, which Get All Regions Info then consumes. The name on the right is always the port; the name on the left is your variable.

An internal input port carries a value the other way: from the functors inside the block back to the container. The contained functors produce the value; the container consumes it. The condition that decides whether a loop repeats is the clearest example.

A While or DoWhile loop has an internal input port for its repeat condition. It is fed by placing a Set While Condition functor inside the loop body — the condition output port of SetWhileCondition is auto-bound to the loop's condition internal input, so no explicit connection is needed:

_ := DoWhile .none {{
    // ... contained functors compute `keepGoing`, a non-zero value to continue ...
    _ := SetWhileCondition keepGoing;   // condition output auto-binds to the loop
}};

The SetWhileCondition auto-binding works in both directions: the output is automatically wired to whichever enclosing While or DoWhile contains it, and the loop evaluates it before each iteration to decide whether to run the body again.

A container may also expose a sequencing-only internal port (carrying no data) used to force one container to finish before another begins — see Sequence ports.

Two families of functors are commonly used together with loops and manage how a value flows from one place, or one iteration, to the next.

A mux carries a value across the iterations of a loop. On the first iteration it emits its initial input. On every later iteration it emits its feedback input — the value produced by the previous pass — so the loop can build on its own prior result. Muxes are typed: Mux Map, Mux Categorical Map, Mux Table, Mux Lookup Table, Mux Value, Mux Tuple, and so on. A mux at the top of a loop body, paired with a variable assigned at the bottom, forms the loop's running state. This loop counts from 0 and stops once the counter reaches 10:

_ := DoWhile .none {{
    // First pass: 0. Later passes: `nextCount` from the previous pass.
    count := MuxValue 0 nextCount;

    nextCount := $ [ $count + 1 ];

    // A boolean converts to a real (true -> 1, false -> 0), so a value calculator turns a
    // stop test into the numeric flag the loop expects: non-zero continues, zero stops.
    keepGoing := $ [ $nextCount < 10 ];

    _ := SetWhileCondition keepGoing;
}};

Note: A mux's feedback input is the one exception to the dependency rule in Functors, variables, and binding — the mux does not wait for the functor that produces its feedback value to run before it runs; it emits the value that functor produced on the previous iteration instead. This is also why, in the example above, nextCount is passed into MuxValue on a line above the line that assigns nextCount: the mux and the calculator each depend on the other's output, so no matter which one is written first in the script, the other's variable is necessarily used before it is assigned.

A junction selects between two dataflows. It reads its first input; if that input carries data, the junction passes it through. If the first input is empty, it passes the second input through instead. If both are empty, the junction reports an error. Junctions are typed, with one per data kind — Map Junction, Categorical Map Junction, Table Junction, Lookup Table Junction, Value Junction, String Junction, and so on:

// `primary` if it has data, otherwise `fallback`:
chosen := MapJunction primary fallback;

The error-handling containers are most useful when combined with a junction outside the block. The sentinel and the risky functor inside the container have no data dependency on each other, so they execute independently. The pattern works as follows:

1. If the risky functor raises an error, Skip All On Error captures it and discards all results produced by functors inside the container — including the sentinel, even though it completed successfully on its own.
2. Outside the container, a junction tests whether anything propagated out. If the sentinel was discarded (error case), the container produced nothing and the junction falls back to its default value. If no error occurred, the sentinel propagates normally and the junction forwards it.

This example tests whether a map file can be loaded successfully:

_ := SkipAllOnError .yes {{
    // The sentinel has no dependency on LoadMap — both execute independently.
    // If LoadMap raises an error, SkipAllOnError discards all results inside,
    // including this sentinel.
    booleanValue0 := BooleanValue .yes;
    _ := LoadMap inputMapFilename;
}};
// If the sentinel was discarded (error), the junction falls back to false (0).
// If no error occurred, the sentinel propagates and the junction returns true.
result := ValueJunction booleanValue0 0;

Skip On Error behaves differently: instead of discarding all results, it preserves the outputs of any functors that had already completed when the error was raised. In the pattern above this means the sentinel would always propagate — making Skip On Error suitable for cases where partial results from a failed block are still useful, not for a simple success/failure test.

A family of calculator functors evaluates an expression and returns a result of a given type:

See also: This section covers only the EGO Script syntax used to call these functors. For the full semantics of each one — inputs, parameters, the expression language, and null handling — see Calculate Functors — Complete Operator Documentation.

Each of these functors can be written in two syntactic forms: the verbose form, which uses the functor's full name and explicit hook functors to connect data, or the abbreviated syntax (also called shorthand), which replaces the functor name with a compact symbol and references operands directly by variable name. The abbreviated symbol for each functor is:

Note: The shorthand is the symbol alone — the [ … ] that usually appears next is simply the functor's first argument (the expression to evaluate), not part of the symbol itself. Whatever follows the bracket (.int8 .default .no .none, or a base table and column names) are the functor's remaining inputs, supplied in positional order.

In the verbose form, data is connected through hook functors — Number Map, Number Table, and Number Value — which supply maps, tables, and scalar values to the expression respectively. Each hook is assigned a number, and the expression references it by a type-specific numbered prefix: i1, i2… for maps; t1, t2… for tables and lookup tables; v1, v2… for values. Each type is numbered independently:

proximityMap := CalculateCategoricalMap {
    expression = [
        if t1[?i1] then 1 else null
    ],
    cellType = .int8,
    nullValue = .default,
    resultIsSparse = .no,
    resultFormat = .none
} {{
    // i1
    NumberMap   regions      1;
    // t1
    NumberTable regionCounts 1;
}};

The following uses two table hooks and two value hooks at once, keeping every top whose height and slope both clear a threshold:

hilltops := CalculateLookupTableValues [
    if t1[line] >= v1 and t2[line] >= v2 then 1 else null
] "Top_Id" "Is_Hilltop" .none {{
    // t1
    NumberTable saddleHeights     1;
    // t2
    NumberTable saddleAngles      2;
    // v1
    NumberValue minimumHeight     1;
    // v2
    NumberValue minimumSlopeAngle 2;
}};

In the abbreviated syntax, the hook block is omitted entirely. The expression references connected data directly by variable name, prefixed by a sigil that identifies the type:

The same two calculations from the verbose section above, written in abbreviated syntax:

proximityMap := ## [
    if %regionCounts[?#regions] then 1 else null
] .int8 .default .no .none;

hilltops := % [
    if %saddleHeights[line] >= $minimumHeight and %saddleAngles[line] >= $minimumSlopeAngle then 1 else null
] "Top_Id" "Is_Hilltop" .none;

The operands are named directly and the hook block disappears entirely. A lookup by key is written %table[key]; ? tests whether a key is present, as in %regionCounts[?#regions].

Converting abbreviated syntax to verbose is always lossless. Converting verbose to abbreviated is only possible when all hooks are free of comments, properties, and identifiers that do not appear in the expression.

A common situation where this matters: if you connect a map or lookup table purely to define the output format — not because it is referenced in the expression — connecting it via a NumberMap or NumberTable hook will block abbreviated syntax, since the hook defines an identifier absent from the expression. Use the dedicated port instead: the Result Format input port for map calculators, or the Base Lookup Table input port for lookup table calculators. These connections do not create hooks and do not affect the availability of abbreviated syntax.

Note: This constraint applies specifically when the GUI saves a script or generates a fragment in abbreviated syntax. When writing a script by hand in a text editor, the situation does not arise — you simply write the appropriate form directly.

Tip: You can control which form Dinamica EGO uses when saving a script via the Use abbreviated syntax for Calculate family functors option, found under Tools → Options | EGO Script — see Script generation options for the full list of generation options.

CalculateLookupTableValues (%) computes only the values of a lookup table; the keys are taken from a base table supplied as an argument. The example below marks each row whose key equals its own value:

// Shorthand
dominantTops := % [
    if %dominanceLookup[line] = line then 1 else null
] "Top_Id" "Is_Dominant" dominanceLookup;

// Verbose equivalent
dominantTops := CalculateLookupTableValues [
    if t1[line] = line then 1 else null
] "Top_Id" "Is_Dominant" dominanceLookup {{
    // t1
    NumberTable dominanceLookup 1;
}};

CalculateLookupTableKeysAndValues (%%) computes both the keys and the values, using a separate expression for each. In the verbose form the two expressions are the functor's first two positional arguments:

// Shorthand
nearestDistances := %% {
    keyColumnExpression   = [ %nearestPoints[[line]["Point_Id"]] ],
    valueColumnExpression = [ %nearestPoints[[line]["Nearest_Distance"]] ],
    keyColumnName   = "Point_Id",
    valueColumnName = "Nearest_Distance",
    baseLookupTable = pointKeys
};

// Verbose equivalent
nearestDistances := CalculateLookupTableKeysAndValues [
    t1[[line]["Point_Id"]]
] [
    t1[[line]["Nearest_Distance"]]
] "Point_Id" "Nearest_Distance" pointKeys {{
    // t1
    NumberTable nearestPoints 1;
}};

The following example illustrates how the two forms look on a realistic expression involving multiple map operands, a value operand, a neighbourhood function, and the ? error-catch operator.

Verbose form:

// Restore the noisy cells marked for restoration. The replacement value is
// derived from a window that grows with the current time step.
updatedRestoredImage := CalculateMap [
    if i1 = 2 then
        nbMedian(i2, v1, v1) ? i3
    else
        i3
] cellType nullValue .no .none {{
    NumberMap  arePixelsOriginalOrNoisyWithCategories 1;
    NumberMap  originalPixelsOnlyInRestoredImage     2;
    NumberMap  currentRestoredImage                  3;
    NumberValue lK                                   1;
}};

Shorthand form:

// Restore the noisy cells marked for restoration. The replacement value is
// derived from a window that grows with the current time step.
updatedRestoredImage := # [
    if #arePixelsOriginalOrNoisyWithCategories = 2 then
        nbMedian(#originalPixelsOnlyInRestoredImage, $lK, $lK) ? #currentRestoredImage
    else
        #currentRestoredImage
] cellType nullValue .no .none;

In the verbose form the three maps arrive as i1, i2, i3 and the value as v1, each supplied by a hook in the trailing block. In the abbreviated form the same operands are referenced directly by their variable names — #arePixelsOriginalOrNoisyWithCategories, #originalPixelsOnlyInRestoredImage, #currentRestoredImage, and $lK — with the trailing block omitted entirely.

A single-line comment begins with // and runs to the end of the line:

// This is a single-line comment.

A multi-line comment is surrounded by /:

/* This is a multi-line
comment */

The two styles differ in one important way:

Note: Multi-line comments are not preserved when a model is opened in the graphical interface, but single-line comments are. Because of this, a multi-line comment is usually better written as consecutive // lines:

// This is a multi-line
// comment

A comment placed immediately before a functor becomes that functor's comment property (see Properties). A comment placed before the Script keyword becomes the model's title (metadata.title).

When a // comment is parsed, the line === splits it into two separate properties: the text before === becomes the functor's comment (the brief comment), and the text after it becomes its extendedcomment (the extended comment):

// Generate the initial seed.
//
// ===
// Living cells are represented by 1 and dead cells by 0.

Here Generate the initial seed. is stored as the comment property and Living cells are represented by 1 and dead cells by 0. as the extendedcomment property. In the graphical interface, the comment is displayed directly on the functor's visual node; the extendedcomment appears only in the tooltip shown when hovering over the node.

A property annotates a functor (or the model as a whole) with metadata. Properties do not change what a model computes; they affect how it is labeled, displayed, and organized in the visual editor, and they carry documentation.

A property is written immediately before the functor it applies to. There are two equivalent syntaxes — the @ form and the comment form:

@name = value

/** name = value */

A property name must start with a letter or _, followed by letters, _, and .. A value may contain any characters, including blanks; a value that spans line breaks must be surrounded by double quotes. If the value itself contains a double-quote character, it must be escaped as \”:

@alias = Largest Patch Area
@collapsed = yes
@notes = "The model input is a map where the non-null values identify the patches.

The output is a table containing the largest patch index per category."
@description = "The input map must have values in the range [0, 1].
Use \"null\" to mark cells that should be excluded from the analysis."

Internally each property has a fully qualified name (such as dff.functor.alias), but many are read and written in a short form that drops the qualified prefix. Writing the @shortName = value form forces the short name to expand to its full property name.

The per-functor properties you will see most often are:

Note: A few per-functor properties exist only while a model is open in the editor and are never written to the saved model: dff.functor.text, dff.functor.file, dff.functor.line, and dff.functor.column.

A light enum turns an integer-valued port into a named dropdown in the GUI, replacing the free-form numeric field with a set of labelled choices. The underlying value stored and passed is still an integer; the dropdown is a presentation layer only.

Any port belonging to the integer family of types (IntegerValue, NonNegativeIntegerValue, PositiveIntegerValue) can be annotated as a light enum, in any model — not just submodels. The annotation applies to carrier functors of those types that expose an editor.

The annotation is written immediately before the carrier functor using the @lightenum.<portName> property, where <portName> is the actual name of the port being annotated. The value is a JSON object with two fields:

• enabled — true to activate the dropdown, false to disable it.
• values — a mapping from integer values (as quoted strings) to human-readable labels.

@lightenum.constant = {"enabled":true,"values":{"1":"Mean","2":"Median","3":"Bounding Box"}}
centroidType := PositiveIntegerValue 1;

Here the GUI presents a dropdown with options “Mean”, “Median”, and “Bounding Box” instead of a numeric field. Selecting “Mean” passes the value 1 to any functor that receives centroidType; selecting “Bounding Box” passes 3.

For its use alongside submodel port declarations, see Submodels.

The GUI and the script use two directions of conversion between an alias and a variable name.

Saving (alias → variable name): When the GUI writes a script, it derives the variable name from the alias by splitting the alias into words — using spaces, underscores, and lowercase-to-uppercase transitions (CamelCase) as word boundaries — then recombining them as a valid identifier. Leading and trailing spaces or underscores are ignored. Non-alphanumeric characters other than underscores are ignored entirely. The result starts with a lowercase letter.

If two or more functors produce the same variable name from their aliases, a number is appended to disambiguate: the first functor keeps the base name, subsequent ones become name2, name3, and so on.

If the conversion alias → variable → alias does not round-trip back to the same original alias — for example because non-alphanumeric characters were discarded — the GUI explicitly writes the @alias property in the saved script to preserve the original alias without loss of information. In such cases you will see an explicit @alias = … annotation even though the functor's variable name is present.

Loading (variable name → alias): When a script is read back into the GUI and a functor has no explicit @alias property, the alias is reconstructed from the variable name using the following rules:

• The first letter is converted to uppercase.
• A space is inserted at every lowercase-to-uppercase transition.
• A space is inserted at every letter-to-digit and digit-to-letter transition.
• Sequences of consecutive uppercase letters are treated as a single word — no space is inserted within them.
• Leading and trailing underscores are discarded.
• Internal underscores (and sequences of multiple underscores) are converted to a single space.

One case is excluded from this reconstruction: a variable name that is just the functor's own name, lowercased at the front, with a trailing number — for example lookupTable0 for a LookupTable functor. This pattern is recognized as an auto-generated name: one the GUI assigned on its own because no alias was ever set, rather than a name a person chose. Such names are not reconstructed into an alias like Lookup Table 0; the functor is simply shown with no alias.

A separate group of properties describes the model as a whole rather than any single functor. These also use a short form, dropping the metadata. (or dff.) prefix:

Note: description is model-level metadata; it is not a property of an individual functor.

Submodels expose their own inputs and outputs to callers through a further set of properties, such as @submodel.in.constant.name and @submodel.out.result.name. These are described in the Submodels section below.

A submodel is an EGO Script file that exposes some of its functor ports as named inputs and outputs, so it can be used as a self-contained, reusable functor in other models. From a scripting perspective, what makes a file a submodel is a set of model-level and functor-level properties that declare its interface. For information about submodel types, storage, the GUI workflow, and the Submodel Store, see Submodels.

A submodel input port is declared by placing @submodel.in.<portName>.* properties before the functor whose port is being exported. The <portName> part of the key is the actual name of that functor's input port. The @submodel.in.<portName>.name sub-property defines the port's name in the submodel interface. Any functor port can be exported as a submodel input, and multiple port declarations can precede a single functor.

Integer-valued ports can also be annotated with @lightenum to present them as a named dropdown in the GUI — see Light enum for details. The annotation is placed before the @submodel.in.* block:

@lightenum.constant = {"enabled":true,"values":{"1":"Mean","2":"Median","3":"Bounding Box"}}
@submodel.in.constant.advanced = no
@submodel.in.constant.description = Integer value identifying the type of centroid to calculate.
@submodel.in.constant.name = centroidType
@submodel.in.constant.optional = yes
@submodel.in.constant.order = 2
centroidType := PositiveIntegerValue 1;

The example below declares two required inputs. Both use @submodel.in.constant.* as the key because the functors BooleanValue and String each have a single input port named constant:

@submodel.in.constant.advanced = no
@submodel.in.constant.description = If true, aborts the model execution.
@submodel.in.constant.name = shouldAbort
@submodel.in.constant.optional = no
@submodel.in.constant.order = 1
shouldAbort := BooleanValue .UNBOUND;

@submodel.in.constant.advanced = no
@submodel.in.constant.description = Message displayed before aborting the model.
@submodel.in.constant.name = errorMessage
@submodel.in.constant.optional = no
@submodel.in.constant.order = 2
errorMessage := String .UNBOUND;

Optional inputs carry their default value directly instead of .UNBOUND. The following declares an optional, advanced input with a string default:

@submodel.in.constant.advanced = yes
@submodel.in.constant.description = Message used to report an invalid value.
@submodel.in.constant.name = errorMessageFormat
@submodel.in.constant.optional = yes
@submodel.in.constant.order = 3
errorMessageFormat := String $"(The value <v1> is not valid.)";

Output ports follow the same pattern as inputs. @submodel.out.<portName>.* properties are placed before the functor whose output is being exported, where <portName> is the actual name of that functor's output port.

The BooleanValue functor has an output port named object. The following exports it as returnedValue:

@submodel.out.object.description = Always returns true if the validation succeeds.
@submodel.out.object.name = returnedValue
@submodel.out.object.order = 1
_ := BooleanValue .yes;

The two submodels below illustrate both concepts together. AbortConditionally is a simple submodel with two inputs and no outputs. ValidateInputValue has three inputs (one optional and advanced), one output, and calls AbortConditionally internally.

AbortConditionally:

@charset = UTF-8
@submodel.name = AbortConditionally
@submodel.description = Aborts the execution conditionally and prints a message before terminating the model.
@submodel.group = Control
Script {{
    @submodel.in.constant.advanced = no
    @submodel.in.constant.description = If true, aborts the model execution.
    @submodel.in.constant.name = shouldAbort
    @submodel.in.constant.optional = no
    @submodel.in.constant.order = 1
    shouldAbort := BooleanValue .UNBOUND;

    @submodel.in.constant.advanced = no
    @submodel.in.constant.description = Message displayed before aborting the model.
    @submodel.in.constant.name = errorMessage
    @submodel.in.constant.optional = no
    @submodel.in.constant.order = 2
    errorMessage := String .UNBOUND;

    // ...
}};

The resulting AbortConditionally functor exposes:

Inputs:

ValidateInputValue (calls AbortConditionally internally):

@charset = UTF-8
@submodel.name = ValidateInputValue
@submodel.description = Validate a numeric value using a custom expression. The execution will be aborted if the given value is not valid according to the given expression.
@submodel.group = Development
Script {{
    @submodel.in.constant.advanced = no
    @submodel.in.constant.description = Value that will be validated.
    @submodel.in.constant.name = inputValue
    @submodel.in.constant.optional = no
    @submodel.in.constant.order = 1
    inputValue := RealValue .UNBOUND;

    @submodel.in.constant.advanced = no
    @submodel.in.constant.description = Expression used to validate the input value. The input value should be mentioned in the expression as "v1". The given expression must return zero if the value is valid, and non-zero if the value is invalid.
    @submodel.in.constant.name = validationExpression
    @submodel.in.constant.optional = no
    @submodel.in.constant.order = 2
    validationExpression := ImageExpression .UNBOUND;

    @submodel.in.constant.advanced = yes
    @submodel.in.constant.description = Message used to report an invalid value. The invalid value can be mentioned using the tag <v1>.
    @submodel.in.constant.name = errorMessageFormat
    @submodel.in.constant.optional = yes
    @submodel.in.constant.order = 3
    errorMessageFormat := String $"(The value <v1> is not valid.)";

    // ...

    // ValidateInputValue calls AbortConditionally as part of its implementation.
    AbortConditionally isValueValid completeErrorMessage;

    @submodel.out.object.description = Always returns true if the validation succeeds. This value can be used to chain validation with subsequent functors.
    @submodel.out.object.name = returnedValue
    @submodel.out.object.order = 1
    _ := BooleanValue .yes;
}};

The resulting ValidateInputValue functor exposes:

Inputs:

Outputs:

Once defined, a submodel is called exactly like any other functor. Outputs are bound left to right in port order; inputs are supplied positionally in port order. The following call validates that a projection type value equals 2, providing a custom error message as the optional third input:

_ := ValidateInputValue projectionType [ v1 = 2 ] $"(An elevation map with geographic projections cannot be used.)";

The optional errorMessageFormat port is supplied explicitly here. It could be omitted, in which case the default $“(The value <v1> is not valid.)” would be used instead.

It is conventional to name the submodel file after its @submodel.name value with a .ego extension, but what matters is the value of that property, not the filename. Where the file is placed determines whether it becomes a local or user submodel:

• Local submodel — place the file in the <modelfile>_ego_Submodels folder next to the main model file.
• User submodel — place the file in the user submodel folder:
  • Windows: C:\Users\<User>\Documents\Dinamica EGO <version>\Submodels\
  • Linux: /home/<User>/Dinamica EGO <version>/Submodels/

See Submodels for full details on submodel types, storage paths, and the Submodel Store.

When the GUI saves a script or generates an EGO Script fragment, a set of options controls how the output is formatted. These are found under Tools → Options | EGO Script:

CalcAreas returns a single output, areas, of type Table. The table has a key column Category and the data columns Area_In_Cells, Area_In_Hectares, and Area_In_Square_Meters, so one call yields every area measure for every category at once. A common mistake is to treat the output as if it were a single hectares figure; it is a table. To work with one measure, read the corresponding column from it:

areaTable := CalcAreas landscape .no;
// the Area_In_Hectares column
hectaresColumn := GetTableColumn areaTable 3;