Using formula expressions

Formula expressions are a key feature when defining models. With them, you can define the mathematical functions to transform and aggregate your raw industrial data to gain insights about your operation.

You can apply formula expressions on transforms and metrics to define the value and format you want Neuron to show the results in.

Formula expression elements

Variables

Variables represent asset properties in formula expressions. Use variables to input values from other asset properties in your expressions, so that you can process data from constant properties (attributes), raw data streams (measurements), and other formula properties.

Variables can represent asset properties from the same asset model or from associated child asset models. Only metric formulas can input variables from child asset models. Variable names are case sensitive.

Operator	Description
`+`	If both operands are numbers, this operator adds the left and right operands. If either operand is a string, this operator concatenates the left and right operands as strings. For example: The expression `1 + 2 + " is three"` evaluates to `"3 is three"` . The concatenated string can have up to 1024 characters. If the string exceeds 1024 characters, then there is no data point for that computation.
`-`	Subtracts the right operand from the left operand. You can only use this operator with numeric operands.
`/`	Divides the left operand by the right operand. You can only use this operator with numeric operands.
`*`	Multiplies the left and right operands. You can only use this operator with numeric operands.
`^`	Raises the left operand to the power of the right operand (exponentiation). You can only use this operator with numeric operands.
`%`	Returns the remainder from dividing the left operand by the right operand. The result has the same sign as the left operand. This behavior differs from the modulo operation. You can only use this operator with numeric operands.
`[]` `s[index]`	Returns the character at an index `index` of the string `s` . Examples: `"Hello!"[1]` returns `e` . `"Hello!"[-2]` returns `o` .
`[]` `s[start:end:step]`	Returns a slice of the string `s` . This operator has the following arguments: `start` - (optional): The inclusive start index of the slice. Defaults to `0` . `end` - (optional): The exclusive end index of the slice. Defaults to the length of the string. `step` - (optional): The number to increment for each step in the slice. For example, you can specify `2` to return a slice with every other character, or specify `-1` to reverse the slice. Defaults to `1` . You can omit the `step` argument to use its default value. For example, `s[1:4:1]` is equivalent to `s[1:4]` . The arguments must be integers or the none constant. If you specify `none` , it uses the default value for that argument. Examples: `"Hello!"[1:4]` returns `"ell"`. `"Hello!"[:2]` returns `"He"`. `"Hello!"[3:]` returns `"lo!"`. `"Hello!"[:-4]` returns `"He"`. `"Hello!"[::2]` returns `"Hlo"`. `"Hello!"[::-1]` returns `"!olleH"`.

Constant	Description
`pi`	The number pi (`π`): `3.141592653589793`.
`e`	The number e: `2.718281828459045`.
`true`	Equivalent to the number 1. Booleans convert to their number equivalents.
`false`	Equivalent to the number 0. Booleans convert to their number equivalents.
`none`	Equivalent to no value. You can use this constant to output nothing as the result of a conditional expression.

Function type	Transforms	Metrics
Common functions	Yes	Yes
Comparison functions	Yes	Yes
Conditional functions	Yes	Yes
String functions	Yes	Yes
Aggregation functions	No	Yes
Temporal functions	No	Yes
Date and time functions	Yes	Yes

Function	Description
`abs(x)`	Returns the absolute value of `x`.
`acos(x)`	Returns the arccosine of `x`.
`asin(x)`	Returns the arcsine of `x`.
`atan(x)`	Returns the arctangent of `x`.
`cbrt(x)`	Returns the cubic root of `x`.
`ceil(x)`	Returns the nearest integer greater than `x`.
`cos(x)`	Returns the cosine of `x`.
`cosh(x)`	Returns the hyperbolic cosine of `x`.
`cot(x)`	Returns the cotangent of `x`.
`exp(x)`	Returns `e` to the power of `x`.
`expm1(x)`	Returns `exp(x) - 1`. Use this function to more accurately calculate `exp(x) - 1` for small values of `x`.
`floor(x)`	Returns the nearest integer less than `x`.
`log(x)`	Returns the `loge` (base `e`) of `x`.
`log10(x)`	Returns the `log10` (base `10`) of `x`.
`log1p(x)`	Returns `log(1 + x)`. Use this function to more accurately calculate `log(1 + x)` for small values of `x`.
`log2(x)`	Returns the `log2` (base `2`) of `x`.
`pow(x, y)`	Returns `x` to the power of `y`. This is equivalent to `x ^ y`.
`signum(x)`	Returns the sign of `x` (`-1` for negative inputs, `0` for zero inputs, `+1` for positive inputs).
`sin(x)`	Returns the sine of `x`.
`sinh(x)`	Returns the hyperbolic sine of `x`.
`sqrt(x)`	Returns the square root of `x`.
`tan(x)`	Returns the tangent of `x`.
`tanh(x)`	Returns the hyperbolic tangent of `x`.

Function	Description
`gt(x, y)`	Returns `1` if `x` is greater than `y`, otherwise `0` (`x > y`). This function doesn't return a value if `x` and `y` are incompatible types, such as a number and a string.
`gte(x, y)`	Returns `1` if `x` is greater than or equal to `y`, otherwise `0` (`x ≥ y`). Neuron considers the arguments equal if they are within a relative tolerance of `1E-9`. This behaves similar to the isclose function in Python. This function doesn't return a value if `x` and `y` are incompatible types, such as a number and a string.
`eq(x, y)`	Returns `1` if `x` is equal to `y`, otherwise `0` (`x == y`). Neuron considers the arguments equal if they are within a relative tolerance of `1E-9`. This behaves similar to the isclose function in Python.
`lt(x, y)`	Returns `1` if `x` is less than `y`, otherwise `0` (`x < y`). This function doesn't return a value if `x` and `y` are incompatible types, such as a number and a string.
`lte(x, y)`	Returns `1` if `x` is less than or equal to `y`, otherwise `0` (`x ≤ y`). Neuron considers the arguments equal if they are within a relative tolerance of `1E-9`. This behaves similar to the isclose function in Python. This function doesn't return a value if `x` and `y` are incompatible types, such as a number and a string.
`isnan(x)`	Returns `1` if `x` is equal to `NaN`, otherwise `0`. This function doesn't return a value if `x` is a string.

Function	Description
`len(s)`	Returns the length of the string `s`.
`find(s, substring)`	Returns the index of the string `substring` in the string `s`.
`contains(s, substring)`	Returns `1` if the string `s` contains the string `substring`, otherwise `0`.
`upper(s)`	Returns the string `s` in uppercase form.
`lower(s)`	Returns the string `s` in lowercase form.
`jp(s, json_path)`	Evaluates the string `s` with the JsonPath expression `json_path` and returns the result. Use this function to do the following: Extract a value, array, or object from a serialized JSON structure. Convert a string to a number. For example, the formula `jp('111', '$')` returns `111` as a number. To extract a string value from a JSON structure and return it as a number, you must use multiple nested `jp` functions. The outer `jp` function extracts the string from the JSON structure, and the inner `jp` function converts the string to a number. The string `json_path` must contain a string literal. This means that `json_path` can't be an expression that evaluates to a string. Examples: `jp('{"status":"active","value":15}', '$.value')` returns `15`. `jp('{"measurement":{"reading":25,"confidence":0.95}}', '$.measurement.reading')` returns `25`. `jp('[2,8,23]', '$[2]')` returns `23`. `jp('{"values":[3,6,7]}', '$.values[1]')` returns `6`. `jp('111', '$')` returns `111`. `jp(jp('{"measurement":{"reading":25,"confidence":"0.95"}}', '$.measurement.confidence'), '$')` returns `0.95`.

Function	Description
`avg(x0, ..., xn)`	Returns the mean of the given variables' values over the current time interval. This function outputs a data point only if the given variables have at least one data point over the current time interval.
`sum(x0, ..., xn)`	Returns the sum of the given variables' values over the current time interval. This function outputs a data point only if the given variables have at least one data point over the current time interval.
`min(x0, ..., xn)`	Returns the minimum of the given variables' values over the current time interval. This function outputs a data point only if the given variables have at least one data point over the current time interval.
`max(x0, ..., xn)`	Returns the maximum of the given variables' values over the current time interval. This function outputs a data point only if the given variables have at least one data point over the current time interval.
`count(x0, ..., xn)`	Returns the total number of data points for the given variables over the current time interval. This function computes a data point for every time interval.

Function	Description
`first(x)`	Returns the given variable's value with the earliest timestamp over the current time interval.
`last(x)`	Returns the given variable's value with the latest timestamp over the current time interval.
`earliest(x)`	Returns the given variable's value with the latest timestamp before the current time interval. This function computes a data point for every time interval, if the input property has at least one data point in its history.
`latest(x)`	Returns the given variable's value with the latest timestamp before the end of the current time interval. This function computes a data point for every time interval, if the input property has at least one data point in its history.
`statetime(x)`	Returns the amount of time in seconds that the given variables are positive over the current time interval. You can use the comparison functions to create a transform property for the `statetime` function to consume. For example, if you have an `Idle` property that is `0` or `1`, you can calculate idle time per time interval with this expression: `IdleTime = statetime(Idle)`. This function doesn't support metric properties as input variables. This function computes a data point for every time interval, if the input property has at least one data point in its history.

Timestamp	2:00:00 PM	2:00:30 PM	2:01:15 PM	2:02:45 PM	2:04:00 PM
Idle	0	1	1	0	0

Timestamp	2:00:00 PM	2:01:00 PM	2:02:00 PM	2:03:00 PM	2:04:00 PM
Idle Time	N/D	30	60	45	0

Function	Description
`now()`	Returns the current date and time, in seconds, in the Unix epoch format.
`timestamp()`	In transforms, the function returns the timestamp of the input message, in seconds, in the Unix epoch format. In metrics, the function returns the timestamp retrieved at the end of the current window, in seconds, in the Unix epoch format.
`mktime(time_zone, year, month, day_of_month, hour, minute, second)`	Returns the input time in seconds, in the Unix epoch format. The following requirements apply, when you use the function: The time zone argument must be a quoted string (`'UTC'`). If not specified, the default time zone is UTC. The year, month, day of month, hour, minute, and second arguments must be in order. The year, month, and date arguments are required. The following limits apply, when you use the function: `year`: Valid values are between 1970 and 2250. `month`: Valid values are between 1 and 12. `day-of-month`: Valid values are between 1 - 31. `hour`: Valid values are between 0 and 23. `minute`: Valid values are between 0 and 59. `second`: Valid values are between 0 and 59. Examples: `mktime(2020, 2, 29)` `mktime('UTC+3', 2021, 12, 31, 22)` `mktime(2022, 10, 13, 2, 55, 13.68, 'PST')`
`localtime(unix_time, time_zone)`	Returns the year, the day of the month, the day of the week, the day of the year, the hour, the minute, or the second in the specified time zone from the unix time. The following requirements apply, when you use the function: The time zone argument must be a quoted string (`'UTC'`). If not specified, the default time zone is UTC. The unix time argument is the time in seconds, in the Unix epoch format. The valid range is between 1-31556889864403199. It can be a floating point number. Example response: `2007-12-03T10:15:30+01:00[Europe/Paris]` `localtime(unix_time, time_zone)` isn't a standalone function. The `year()`, `mon()`, `mday`, `wday()`, `yday()`, `hour()`, `munite()`, and `sec()` functions take `localtime(unix_time, time_zone)` as an argument. Examples: `year(localtime('GMT', 1605898608.8113723))` `now().localtime().year()` `timestamp().localtime(‘PST’).year()` `localtime(1605289736, ‘Europe/London’).year()`
`year(localtime(localtime(unix_time, time_zone))`	Returns the year from`localtime(unix_time, time_zone)`.
`mon(localtime(unix_time, time_zone))`	Returns the month from `localtime(unix_time, time_zone)`.
`mday(localtime(unix_time, time_zone))`	Returns the day of the month from `localtime(unix_time, time_zone)`.
`wday(localtime(unix_time, time_zone))`	Returns the day of the week from `localtime(unix_time, time_zone)`.
`yday(localtime(unix_time, time_zone))`	Returns the day of the year from `localtime(unix_time, time_zone)`.
`hour(localtime(unix_time, time_zone))`	Returns the hour from `localtime(unix_time, time_zone)`.
`minute(localtime(unix_time, time_zone))`	Returns the minute from `localtime(unix_time, time_zone)`.
`sec(localtime(unix_time, time_zone))`	Returns the second from `localtime(unix_time, time_zone)`.

Formula expression elements

Variables

Literals

Operators

Constants

Functions

Function syntax

Common functions

Comparison functions

Conditional functions

String functions

Aggregation functions

Temporal functions

Date and time functions

Supported time zone formats

Using strings in formulas

Filtering data points

Counting data points that match a condition

Late data in formulas

Data quality in formulas

Undefined, infinite, and overflow values