Expressions allows to use mathematical formulas to be used in d3web knowledge bases. In every formula you may access existing questions and their values, as well as predefined constants. The results of those formulas may be used to assign it to an existing question or as a precondition in a rule.
This tutorial is built in three chapters:
The expressions are integrated in a bunch of existing markups, as well as defining some additional markups.
Expression can be used in %%Rule markup in both conditions and actions. In both, it must be surrounded by eval(...) containing the expression. When using the expression as a condition, the expression must result to a boolean value, otherwise an error is signaled and the rule will not be created. The rule will fire if the condition evaluates to "true". In the following example the rule will fire of the gradient of question "measurement" is above 1 during the last 10 seconds.
%%Rule IF eval( gradient( measurement[-10s,0s] ) > 1 ) THEN ... /%
For rule actions the expression can be used to assign the resulting value to an abstract question. The expression is also surrounded by eval(...), preceded by the question to be assigned. Please note that the questions type must be compatible to the result of the expression, otherwise an error is signaled and the rule will not be created. In the following example the question myGradient will be assigned to the gradient, the question "measurement" had during the last 10 seconds:
%%Rule IF measurement = known THEN myGradient = eval( gradient( measurement[-10s,0s] ) ) /%
Using the markup %%Variable you can directly assign the result of an expression to an existing question. Please note that the questions type must be compatible to the result of the expression, otherwise an error is signaled and the assignment will not be created. Unlike using the expressions in rules, no eval(...) is required. The assignment is always kept up-to-date, so the value of the assigned question is never outdated.
%%Variable myGradient = gradient( measurement[-10s,0s] )
Constants are helpful to define values that have a special meaning and therefore naming it. Those constants can be of any type (e.g. number, date, boolean) and can be used in any expression instead the direct value. This gives you the possibility to also alter the constant's value in the wiki without altering all the usages of the value.
Defining a constant is identical to defining a direct question assignment, but instead of a predefined question the constant name is to be written left to the expression. The type of the constant is automatically derived by the result of the expression. Note that defining a constant, neither questions nor other constants are allowed to be used in the defining expression. See some examples:
// define a numeric constant %%Constant pi = 3.14159265358979323846 // define a date constant (see special date notation) %%Constant bostonTeaParty = #1773-12-16# // you may also use operators and functions %%Constant silvesterParty = #1999-12-31# + 19h + 30min %%Constant pi_of_Archimedes = 3 + 9552/67441 // use other constants is NOT ALLOWED!!! --> error signaled %%Constant invalidDeclaration = 2*pi
Expressions can also be used in the flowchart graphical editor. Similar to rules the expressions can be used as both assignments in nodes and conditions on arrows.
You can write expression in a natural operator infix-notation. For mathematical calculations you can use the common operators "+", "-", "*", "/" to addition, subtraction, multiplication and division. In addition the infix operator "^" for power is also defined. The operators have their priority as usual in algebra (1: "^"; 2: "*", "/"; 3: "+", "-"). Brackets can be used to change priority of evaluation.
// examples of valid expressions 1 + 3 // result is 4 2 ^ 16 - 1 // result is 65635 2 ^ (16 - 1) // result is 32768
Each element in an expression has a defined result type. The following types are defined: numbers, booleans, durations, time-points and strings. In the examples above, only numbers are used. By typing a number in an expression you have defined a literal constant. But also the other types have their literal constants to be used in expressions:
Type | Syntax | Description / Example |
---|---|---|
Number | <DD> <DD>.<DD> <DD>.<DD>e+-<DD> | <DD> is any number character sequence. Defines a number literal constant, either an integer number or an rational number or a floating point number in exponent notation. Examples are "12" or "125.17" or "1.1e-23". |
Boolean | "true" "false" | Defines a boolean literal constant either being true or false. |
Duration | <NUMBER>"ms" <NUMBER>"s" or "sec" <NUMBER>"min" <NUMBER>"h" <NUMBER>"d" | <NUMBER> is a number literal constant as described above. It is appended by a duration unit which may be "ms" for milliseconds, "s" or "sec" for seconds, "min" for minutes, "h" for "hours" or "d" for days. Examples are "1.5d" for 36 hours of time or "1s" for one second. |
Time-Point | #YYYY-MM-DD# | Defines a date as a time-point, where "YYYY" is the year, "MM" is the month (1-12) and "DD" is the day of the month. The time-point literal is always at 0:00 o'clock of the specified date. If a special time is meant, simply add a duration to the date. Examples are "#2000-01-01#" for the millenium sylvester and "#1999-12-31# + 19h" for the party starting at 7pm the day before. |
String | '<any_characters_here>' | Defines a string literal constant. Please note the single quotes to be used for string literals. If the string shall contain a single quote character use "\'" inside the string literal. Examples are "'my string'" or "'quote means \' here'". |
For comparing values the operators "=" (or "==", which is identical), "<", "<=", ">", ">=" and "!=" are defined. The result of these compare operators are a boolean value, "true" or "false" to be more precise. For booleans there are also some additional infix operators defined: "&" for "logical and" and "|" for "logical or", as well as "&&" and "||" which are identical to "&" and "|". You can also use "!" for logical negation.
// example comparators 1 >= 3 // true 2^16-1 == 65535 // true // example boolean operators true & false // false true | false // true true & !false // true
There are a lot of functions provided, that can be applied to a set of arguments. See function reference table for a complete set of all available functions. Each function has a number of signatures describing the arguments allowed to be used for the function.
A function is called by writing the function name followed by brackets. Inside the brackets the arguments of the function can be listed, separated by ",". Examples of functions are:
floor( 3.23 ) // results to 3 average( 1, 2, 3, 4 ) // results to 2.5
Each of the infix operators available have also a corresponding function. By looking in the function reference table you can see to what argument types the operators can be applied to.
Operator | Function | Desciption |
---|---|---|
^ | pow | Returns the value of the first argument raised to the power of the second argument. |
* | mult | Returns the product of the two arguments. |
/ | div | Returns the ratio of the two arguments. |
+ | plus | Returns the sum of the two arguments. |
- | minus | Returns the difference of the two arguments. |
! | not | Returns true, if the argument is false, and vica verse. |
&, && | and | Returns false, if one argument is false. |
|, || | or | Returns true, if one argument is true. |
=, == | equal | Returns true, if both argument are equal, false otherwise. |
!= | unequal | Returns true, if both argument are not equal, false otherwise. |
< | lt | Returns true, if the first argument is less than the second one, false otherwise. |
<= | le | Returns true, if the first argument is less or equal than the second one, false otherwise. |
> | gt | Returns true, if the first argument is greater than the second one, false otherwise. |
>= | ge | Returns true, if the first argument is greater or equal than the second one, false otherwise. |
[] | -- | Access the full history to a certain question. This operator has no functional equivalent. |
[...] | valueAt | Access a value of a history to a certain time. |
[..., ...] | subHistory | Access a sub-history in a certain time range. If there is not value directly at the start of the subhistory, the next earlier value will be included. |
![..., ...] | strictSubHistory | Access a sub-history in a certain time range. The sub-history will not contain values that were set before the given start. |
You can access the current value of a question by simply writing the question's or solution's name in a formula. If the name contains any non-alphanumeric characters, you can use double quotes on the name. Referring to a question or solution, the current (most recent) value is used when the expression is evaluated.
// access question values floor(myQuestion + 1) // using the current value of myQuestion floor("My special question" + 1) // using the current value of the question "My special question"
Using questions or solutions, you can also use the special []-operator, that allows you to access a past value of the object or it's whole history. Please note that this is only allowed for questions and solutions that are recorded in the time database. This is the default behaviour, but may be altered setting the object's property "history" to "false". The []-operator has different possible usages:
// access question values myQuestion[now - 10min] // using the value of myQuestion 10 minutes ago // access question histories average(myQuestion[]) // average of all values myQuestion had before (incl. current one) average(myQuestion[now-10min, now]) // average of the last 10 minutes average(myQuestion![now-10min, now]) // average of all values that were set between 10 minutes ago and now
Instead of using time-points, the operator also allows to use durations (e.g. "10min"). Using a duration means that you refer to the time the specified duration ago. Regardless to whether the duration is positive or negative, the operator always goes into the past starting at the "recent time". This "recent time" is the latest time the object has been set, but not from the global variable 'now'. Especially for rarely set objects this can make a big difference.
// using durations instead of time-points myQuestion[10min] // using the value of myQuestion 10 minutes before its latest value average(myQuestion[-10min, 0min]) // average of the last 10 minutes since the latest value average(myQuestion[10min, 0min]) // identical to the line above
Using questions in formulas, the questions will be interpreted as following:
Using solutions in formulas the solution's value is a numeric integer value as following:
You can also access the choices of the questions as constant symbols. The choices have their value defined by "1" for the first choice of a question, "2" for the second one, and so on. Since the name of choices are not unique, but identical named choices may have different values for different question, it is necessary to link the choice to the correct question.
Usually in expression you can simply write the choice, after you have used the question before. To have this simple rule, there is complex identification behind, you usually not get noticed of. Here it is how the choices are matched to their choice-questions (both, [oc] and [yn]):
As mentioned you usually not in charge to be aware of this rule. Simply use choices natural to after their questions:
myQuestion[-10s] = myChoice myQuestion = myChoice && myOtherQuestion = myOtherChoice average( myQuestion[] ) > myChoice
You can also directly refer to any choice of any question, under ignorance of all the rules above. To do that simply use the question name, append "#" and the choice name. If the question or choice contains any special characters or white-spaces use double quotes around the whole literal:
// direct access to choices myQuestion#myChoice "My special question#my special choice"
You can also access the states of a solution as constant symbols, similar to question choices. The states have their value defined by "0" if the solution is excluded, "1" for neutral, "2" for suggested and "3" for established solutions. Usually the rating states for a certain solution can be accessed by their name (e.g. "ESTABLISHED"). The behavior is identical to choice questions, thus refer to the section above for more details.
mySolution[-10s] = ESTABLISHED median( mySolution[] ) >= SUGGESTED
There is also a number of special literal tokens defined when using expression. Those tokens are:
When using questions in expressions, their values may be undefined, e.g. no value has been set to the question. In addition also functions may return undefined, e.g. calculating the average of an empty history. Most functions will return undefined if any of it's arguments is undefined. Otherwise, function's behavior on undefined values is denoted by the individual functions.