Events and State¶
For data that arrives now and then, such as quarterly earnings, and for signals that hold a state from one day to the
next. In the toy data, field('surprise') has four reports: A on Jan 03, C on
Jan 05, B and D on Jan 08.
Holding values¶
fill_forward¶
fill_forward(x[, limit])
Carries each value forward over the missing days after it, for at most limit days; with no limit, until the next
value. Below, each surprise is held for one more day.
field('surprise')| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | 0.05 | · | · | · |
| Jan 04 | · | · | · | · |
| Jan 05 | · | · | −0.02 | · |
| Jan 08 | · | −0.01 | · | 0.03 |
| Jan 09 | · | · | · | · |
fill_forward(field('surprise'), 1)| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | 0.05 | · | · | · |
| Jan 04 | 0.05 | · | · | · |
| Jan 05 | · | · | −0.02 | · |
| Jan 08 | · | −0.01 | −0.02 | 0.03 |
| Jan 09 | · | −0.01 | · | 0.03 |
latch¶
latch(on, off)
A switch: 1 from a day on is true until a day off is true, then 0 until on is true again. It starts at 0, off
wins a tie, and a day where either is missing changes nothing. With the exit below the entry, small moves around a
threshold don't flip it back and forth. Below, a price filter: A trades above $11.50 on Jan 04 and switches on;
it slips to $11 on Jan 05, which turns the plain comparison off, but the latch stays on until a price under $10.50.
field('price') > 11.5| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | 0 | 1 | 1 | 1 |
| Jan 03 | 0 | 1 | 1 | 1 |
| Jan 04 | 1 | 1 | · | 1 |
| Jan 05 | 0 | 1 | 1 | 1 |
| Jan 08 | 1 | 1 | 1 | 1 |
| Jan 09 | 1 | 1 | 1 | 1 |
latch(field('price') > 11.5, field('price') < 10.5)| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | 0 | 1 | 1 | 1 |
| Jan 03 | 0 | 1 | 1 | 1 |
| Jan 04 | 1 | 1 | 1 | 1 |
| Jan 05 | 1 | 1 | 1 | 1 |
| Jan 08 | 1 | 1 | 1 | 1 |
| Jan 09 | 1 | 1 | 1 | 1 |
latch gives a universe hysteresis (Universes), and holds a position from an
entry rule to an exit rule.
Counting by events¶
A fixed window in days holds a varying number of quarterly reports. These operators count reports instead: the last
n values x has had, however far back, held between events.
ts_mean_events¶
ts_mean_events(x, n[, min_n])
The mean of the last n values, with a value every day once there are min_n (default n).
field('surprise')| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | 0.05 | · | · | · |
| Jan 04 | · | · | · | · |
| Jan 05 | · | · | −0.02 | · |
| Jan 08 | · | −0.01 | · | 0.03 |
| Jan 09 | · | · | · | · |
ts_mean_events(field('surprise'), 4, 1)| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | 0.05 | · | · | · |
| Jan 04 | 0.05 | · | · | · |
| Jan 05 | 0.05 | · | −0.02 | · |
| Jan 08 | 0.05 | −0.01 | −0.02 | 0.03 |
| Jan 09 | 0.05 | −0.01 | −0.02 | 0.03 |
ts_std_events¶
ts_std_events(x, n[, min_n])
The standard deviation of the last n values, once there are min_n.
ts_sum_events¶
ts_sum_events(x, n[, min_n])
The sum of the last n values, once there are min_n.
ts_count_events¶
ts_count_events(x, period)
How many values x has had in the last period days: an answer every day once period days have passed, 0 included.
field('surprise')| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | 0.05 | · | · | · |
| Jan 04 | · | · | · | · |
| Jan 05 | · | · | −0.02 | · |
| Jan 08 | · | −0.01 | · | 0.03 |
| Jan 09 | · | · | · | · |
ts_count_events(field('surprise'), 3)| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | · | · | · | · |
| Jan 04 | 1 | 0 | 0 | 0 |
| Jan 05 | 1 | 0 | 1 | 0 |
| Jan 08 | 0 | 1 | 1 | 1 |
| Jan 09 | 0 | 1 | 1 | 1 |
days_since¶
days_since(x)
How many trading days since x was last nonzero: 0 on a day it is, 1 the day after, and so on. A day counts when x
has a value that is not 0 (a negative value counts; so does an infinity, as in where). A missing day is not an
event, and it neither resets nor stops the count, so a halt between two events still counts its days. Before x is
first nonzero the answer is missing. There is no window: the count runs however far back the last event is.
Days are rows of the data, trading days, not calendar days. Below, C's report on Jan 05 starts its count, and B and D have no count until their reports on Jan 08.
field('surprise')| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | 0.05 | · | · | · |
| Jan 04 | · | · | · | · |
| Jan 05 | · | · | −0.02 | · |
| Jan 08 | · | −0.01 | · | 0.03 |
| Jan 09 | · | · | · | · |
days_since(field('surprise'))| A | B | C | D | |
|---|---|---|---|---|
| Jan 02 | · | · | · | · |
| Jan 03 | 0 | · | · | · |
| Jan 04 | 1 | · | · | · |
| Jan 05 | 2 | · | 0 | · |
| Jan 08 | 3 | 0 | 1 | 0 |
| Jan 09 | 4 | 1 | 2 | 1 |
days_since(field('surprise')) <= 5 # a report in the last week
where(days_since(field('surprise')) < 10, field('surprise'), None) # the latest report, for ten days
days_since(close() >= ts_max(close(), 252)) # days since a 52-week high
For "days since the latest", use days_since, not ts_argmax: given two events in its window, ts_argmax counts
back to the older one.