Syntax¶
A qex expression is one formula. It reads like arithmetic over named operators, and every part of it stands for a value per date and stock (see How qex Evaluates).
Function calls¶
An operator is called by name with its arguments in parentheses, separated by commas. Arguments are positional,
with one exception: the options of ts_match and ts_match_score can also be given by name, as in within='sector'
(Statistical Twins).
An argument is either an expression (anything on this page) or a constant the operator needs: a window length, a number of buckets, a field or group name. The operator reference gives each operator's arguments.
Values¶
| Write | Means |
|---|---|
20, 0.05, 1e-3, -1 |
a number, the same on every date and stock |
'sector', "sector" |
a string: a field or group name, or a label to compare with (group('sector') == 'Technology') |
None |
no value here, on purpose (see Missing Values) |
A number in an expression is broadcast: returns(5) - 0.01 subtracts 1% from every stock's return.
Arithmetic¶
| Operator | Means |
|---|---|
a + b, a - b, a * b, a / b |
element-wise arithmetic |
-a |
negation |
a ** n |
a to the power n; n must be a plain number. For any other exponent write power(a, b) |
Division by zero gives an infinity, not an error; see Missing Values.
Comparisons and logic¶
| Operator | Means |
|---|---|
a > b, a < b, a >= b, a <= b |
1 or 0, and missing where either side is missing |
a == b, a != b |
the same; also compares labels |
a & b, a \| b |
and, or |
~a |
not |
&, | and ~ are three-valued: false & missing is false, true | missing is true, and anything else with a missing
side is missing. Missing Values has the full table.
Comparisons can't be chained: write (a < b) & (b < c), not a < b < c.
Precedence¶
From tightest to loosest, as in ordinary arithmetic:
- function calls and parentheses
**-a,~a*,/+,-&|>,<,>=,<=,==,!=
& and | bind tighter than comparisons, so comparisons inside & and | need parentheses:
(returns(5) > 0) & (volume(1) > volume(20)) right
returns(5) > 0 & volume(1) > volume(20) refused: it reads as a chained comparison
returns(5) > 0 & volume(1) no error, but reads as returns(5) > (0 & volume(1))
Names: let ... in¶
let names a part of an expression so it can be used more than once:
- Bindings are separated by commas; a later binding can use an earlier one.
- A name is used only in the
inbody and in later bindings. - A name must be a valid identifier (letters, digits,
_, not starting with a digit) and can't be an operator's name:let rank = ...is refused. - A named part is computed once, however many times it is used.
Layout¶
Spaces and line breaks don't matter outside quoted strings, so an expression can be laid out across lines anywhere, including after an operator:
A # starts a comment, which runs to the end of its line; a # inside a quoted string is part of the string:
let mom = returns(60), # three months
vol = volatility(60) # over the same window
in rank(mom / vol) # risk-adjusted momentum
(Before qex 0.12.1, the lines were joined before comments were removed, so a comment hid every line after it.)
What is refused¶
An expression that qex can't read, or that asks for something it doesn't do, is refused before anything is computed, with a message:
| Written | Refused because |
|---|---|
foo(1) |
Unknown function: foo |
a + b with no let for b |
Unknown variable: b |
let rank = returns(1) in rank |
Cannot shadow function name: rank |
rank(returns(1), 2) |
the wrong number of arguments for the operator |
ts_mean(returns(1), period=20) |
arguments are by position, not by name (only ts_match and ts_match_score take names) |
1 < returns(1) < 2 |
Chained comparisons not supported |
returns(1) ** returns(2) |
The exponent of ** must be a number, as in power(x, n) |
rank(group('sector')), group('sector') + 1 |
labels where numbers are needed (Groups and Labels) |
group_std(x, 'pair', 60) |
the window form of group_std was removed in qex 0.12.0; the message gives the replacement |
a and b, a or b, not a |
not qex: write &, \|, ~ |
a % b, a // b |
not qex operators |
[1, 2], x[0], x.y, a if c else b |
not part of qex (for a choice, where(c, a, b)) |
returns('5'), delay(x, 1.5), ts_mean(x, 0) |
each operator's constant arguments are checked (below) |
Every operator's constant arguments are checked when the expression is read, and a bad one is refused with a message naming the operator, the argument and what it must be:
| Argument | Must be | For |
|---|---|---|
| a window | a whole number of days, at least 1 | returns, volatility, volume, adv, the rolling ts_ operators, ts_count_events |
| a lag | a whole number of days, 0 or more | delay, delta |
| a count | a whole number, at least 1 | quantile's buckets, fill_forward's limit, an event operator's n and min_n, a min_periods |
| a half-life | a number of days above 0 | ewma, ewma_var, ewma_cov, ts_beta_ewma |
| a level | from 0 to 1, or 0 to 0.5 for winsorize |
ts_quantile, winsorize |
| a limit | a number above 0 | truncate |
| a name | a quoted string | field, group, the price field of returns and volatility |
20.0 counts as a whole number.