Mathematical expressions

When using nodes that filter or generate data, you might encounter a parameter type called “Expression”. This parameter allows to to write simple to complex functions that can test for one or multiple conditions or act as input for a generator node. The basic concept of this expression language is to mix string, boolean, and numeric operations into one simple but powerful language. It allows you for example to first calculate a numeric metric and use it for filtering objects within one line.

There are always four components you will interact with:

1. Literals like numbers (0.5), strings ("hello world"), and boolean values (TRUE, FALSE)
2. Variables that are supplied from the node itself like x, y, or Area
3. Functions that process literals or variables like MIN(x, 5), STRING_EQUALS("abc", "abc"). Parameters are separated by commas.
4. Operators that do something with the literals, variables, or function results, like subtraction, concatentation, or conditions
5. New in 1.74.0: The $ operator has a second function: escaping expressions into strings.

The expression language is interpreted as one line and you cannot write own variables. The result of the one expression is supplied to the node for processing.

The user interface of the expression parameter allows you to type the expression via a text field. You can also create new lines if you have longer expressions. They will be all merged automatically. If you are unfamiliar with the expression language, you can click the button to open a tool that lists all available functions and operators. This tool will help you to build expressions and check the syntax.

Variables

Variables are set externally by the node and can contain various useful values. For example, filter nodes will put numbers into the variables. Image generator nodes might put the pixel coordinates into them.

Example Here the node supplies the variables x and y and expects a number back. You can input a formula that will be automatically applied to ally x and y values:

(x + y) + x/y + 1

Statements

You can also set variables to re-use them in more complicated calculations by introducing multiple statements:

SET_VARIABLE("x", 5); PRINT("x=", x); SET_VARIABLE("y", x + 5); PRINT("y=", y); y + 15

The code above will run the operations from left to right and print into your console:

x=5
y=10

The return value will always be the right-most operation (here 15)

As you can use new-lines in expression editors, we recommend to put each statement into a new line:

SET_VARIABLE("x", 5); 
PRINT("x=", x); 
SET_VARIABLE("y", x + 5); 
PRINT("y=", y); y + 15

Pairs

1.74.x+

The pair operator and SET_VARIABLES were introduced in JIPipe 1.74.0

Escaping expressions

1.74.x+

Expression escaping requires JIPipe 1.74.0 or newer

There are various functions that require the input of a “sub-expression” that for example is executed for each item:

MAKE_SEQUENCE_EXPR("item + 1", ARRAY(1,2,3))

The item is a variable that is set for each array item. The result that is generated is an array [2,3,4].

It can be complicated to provide more advanced expressions as string parameter. This is the reason behind the escape expression operator ${ }. All parts within the braces are not evaluated and instead converted into an appropriate string.

Example usage:

MAKE_SEQUENCE_EXPR(${item + 1}, ARRAY(1,2,3))

Operators

The expressions understand a wide range of common operators for numeric, string, and boolean data:

• You can add, subtract, divide, … numbers
• Strings can be concatenated or checked for if one string contains another
• All basic boolean operators are available

Example You can combine various operators to do complex filtering. Here the node supplies variables Area and MaxWidth:

(Area > 1000) AND ((MaxWidth^2 / Area > 0.5))

Functions

The expression language comes with a large library of predefined functions that you can use for more complex tasks:

Example To find files, it can be useful to utilize a Glob-filter that can reliably test for the file extension. Here name is the file name and supplied by the node.

STRING_MATCHES_GLOB(name, "*.tif") AND ("data" IN name)

User functions

1.74.x+

This type of user-created function was introduced in JIPipe 1.74.0

You can create custom functions to be utilized within the current expression via the FUNCTION(name, expression) function. The function then can be executed via RUN_FUNCTION(name, parameter 1, parameter 2, ...). The parameters must correspond to the expected variable names inside the function and must be provided via PAIR(name, value), ARRAY(name, value), or name: value (pair operator).

Example

FUNCTION("ADD_ONE", ${ x + 1 });
RUN_FUNCTION("ADD_ONE", "x": 1)

The output will be 2

Example 2

FUNCTION("ADD", ${x + y});
RUN_FUNCTION("ADD", "x": 1, "y": 2)

The output will be 3

Data types

The expression language supports five basic data types: Numbers, strings, arrays, and maps

Numbers

Numbers are any kind of number (integer or floating point). Number literals are read as floating point numbers (double).

Example: 1, 0.5

Strings

Strings are character sequences (texts). They are defined by putting double quotes around a text. If you want to have a double quote inside your string, escape it via \. If you want a \ in your text, escape it with another \.

Example: "hello world", "this text has a \" quote and \\ backslash"

Arrays

Arrays are collections of values. They are defined via the ARRAY(...) function. Individual items are access via the @ operator and a numeric index starting from zero.

Example: ARRAY(1,2,3,4) @ 2 will return 3.

Example: ARRAY(1,2,3,4) @ ARRAY(0,1) will return an array with 1 and 2

A special case are arrays with two entries (pairs) that can be also created via PAIR(a, b) or the colon operator a: b.

Maps

Maps are collections of values where each value is given a unique name. They are defined via the MAP(...) function that should be provided with 2-item arrays (there is a PAIR(key, value) function for this). You can get an array of all keys via the KEYS() function and can access elements via the @ operator.

Example: MAP(PAIR("a", 1), PAIR("b", 2), PAIR("c", 3)) @ "b" returns 2

Example: KEYS(MAP(PAIR("a", 1), PAIR("b", 2), PAIR("c", 3))) returns an array with a, b, and c

Example: VALUES(MAP(PAIR("a", 1), PAIR("b", 2), PAIR("c", 3))) returns an array with 1, 2, and 3

Operators

There are many operators with alternative ways to write them available. There are two kinds of operators:

1. Symbolic operators are using symbols like $, & or *
2. Textual operators are written words like AND or CONTAINS

The difference between the operators is that symbolic operators can be written without spaces. For example you can write 5+5 or !x. Textual operators require spaces to be separated. For example you cannot write NOTx. You have to write NOT x.

Precedence

The operators are ordered according to a precedence table. You might need to use brackets (()) to force the order you expect:

The higher the number is the more the operator is preferred.

Compatible types

Not all operators are compatible to all types. See following table for the operator’s behavior:

Note that statements are compatible to any type, as they are structural parameters.