Skip to content

Commit eed81dc

Browse files
committed
fix(bars): report current adaptive state for incomplete run bars
1 parent c74a52d commit eed81dc

2 files changed

Lines changed: 121 additions & 30 deletions

File tree

‎src/ml4t/engineer/bars/run.py‎

Lines changed: 30 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
"""Run bar sampler implementations.
22
3-
AFML-compliant run bars per López de Prado Chapter 2.3.
3+
Run bars based on López de Prado's cumulative run definition.
44
5-
Run bar threshold formula:
5+
Tick-run threshold formula:
66
E[θ_T] = E[T] × max{P[b=1], 1-P[b=1]}
77
88
Where:
99
E[T] = EWMA of bar lengths (ticks per bar)
1010
P[b=1] = buy probability
1111
12+
Volume and dollar variants use cumulative volume/value as the adaptive size
13+
in the same threshold calculation, rather than mixing value units with tick counts.
14+
1215
CRITICAL: θ_T = max{Σ(all buys in bar), Σ(all sells in bar)}
1316
- NOT consecutive same-sided trades
1417
- NO reset on direction change within bar
@@ -51,8 +54,10 @@ def _calculate_run_bars_nb(
5154
npt.NDArray[np.float64],
5255
npt.NDArray[np.float64],
5356
npt.NDArray[np.float64],
57+
float,
58+
float,
5459
]:
55-
"""Calculate AFML-compliant run bar indices.
60+
"""Calculate cumulative weighted run bar indices.
5661
5762
AFML Chapter 2.3 formula:
5863
θ_T = max{Σ(all buys in bar), Σ(all sells in bar)}
@@ -68,7 +73,7 @@ def _calculate_run_bars_nb(
6873
sides : ndarray
6974
Array of trade signs (+1 for buy, -1 for sell)
7075
initial_expected_t : float
71-
Initial expected ticks per bar (E[T])
76+
Initial expected total value per bar, in the same units as values
7277
initial_p_buy : float
7378
Initial buy probability P[b=1]
7479
alpha : float
@@ -78,9 +83,9 @@ def _calculate_run_bars_nb(
7883
7984
Returns
8085
-------
81-
tuple of arrays
86+
tuple
8287
(bar_indices, thetas, expected_thetas, expected_ts, p_buys,
83-
cumulative_buys, cumulative_sells)
88+
cumulative_buys, cumulative_sells, current_expected_t, current_p_buy)
8489
"""
8590
n = len(values)
8691

@@ -163,6 +168,8 @@ def _calculate_run_bars_nb(
163168
np.array(p_buys, dtype=np.float64),
164169
np.array(cumulative_buys_out, dtype=np.float64),
165170
np.array(cumulative_sells_out, dtype=np.float64),
171+
float(expected_t),
172+
float(p_buy),
166173
)
167174

168175

@@ -261,6 +268,8 @@ def sample(
261268
p_buys,
262269
cumulative_buys,
263270
cumulative_sells,
271+
current_expected_t,
272+
current_p_buy,
264273
) = _calculate_run_bars_nb(
265274
values,
266275
sides,
@@ -318,11 +327,7 @@ def sample(
318327
cum_sells = float(np.sum(bar_sides < 0))
319328
current_theta = max(cum_buys, cum_sells)
320329

321-
last_expected_t = (
322-
expected_ts[-1] if len(expected_ts) > 0 else float(self.expected_ticks_per_bar)
323-
)
324-
last_p_buy = p_buys[-1] if len(p_buys) > 0 else self.initial_p_buy
325-
expected_theta = last_expected_t * max(last_p_buy, 1 - last_p_buy)
330+
expected_theta = current_expected_t * max(current_p_buy, 1 - current_p_buy)
326331

327332
bar = self._create_ohlcv_bar(
328333
bar_ticks,
@@ -333,8 +338,8 @@ def sample(
333338
"expected_run": float(expected_theta),
334339
"theta": float(current_theta),
335340
"expected_theta": float(expected_theta),
336-
"expected_t": float(last_expected_t),
337-
"p_buy": float(last_p_buy),
341+
"expected_t": current_expected_t,
342+
"p_buy": current_p_buy,
338343
"cumulative_buys": float(cum_buys),
339344
"cumulative_sells": float(cum_sells),
340345
},
@@ -372,7 +377,7 @@ def _empty_run_bars_df(self) -> pl.DataFrame:
372377

373378

374379
class VolumeRunBarSampler(BarSampler):
375-
"""Sample bars based on cumulative volume runs (AFML-compliant).
380+
"""Sample bars based on cumulative volume runs.
376381
377382
AFML Chapter 2.3 formula with volume weighting:
378383
θ_T = max{Σ(buy volumes in bar), Σ(sell volumes in bar)}
@@ -451,6 +456,8 @@ def sample(
451456
p_buys,
452457
cumulative_buys,
453458
cumulative_sells,
459+
current_expected_t,
460+
current_p_buy,
454461
) = _calculate_run_bars_nb(
455462
volumes, # Use volumes as values
456463
sides,
@@ -506,11 +513,7 @@ def sample(
506513
# Calculate current theta (cumulative volumes)
507514
current_theta = max(buy_vol, sell_vol)
508515

509-
last_expected_t = (
510-
expected_ts[-1] if len(expected_ts) > 0 else initial_expected_t_scaled
511-
)
512-
last_p_buy = p_buys[-1] if len(p_buys) > 0 else self.initial_p_buy
513-
expected_theta = last_expected_t * max(last_p_buy, 1 - last_p_buy)
516+
expected_theta = current_expected_t * max(current_p_buy, 1 - current_p_buy)
514517

515518
bar = self._create_ohlcv_bar(
516519
bar_ticks,
@@ -521,8 +524,8 @@ def sample(
521524
"expected_run": float(expected_theta),
522525
"theta": float(current_theta),
523526
"expected_theta": float(expected_theta),
524-
"expected_t": float(last_expected_t),
525-
"p_buy": float(last_p_buy),
527+
"expected_t": current_expected_t,
528+
"p_buy": current_p_buy,
526529
"cumulative_buys": float(buy_vol),
527530
"cumulative_sells": float(sell_vol),
528531
},
@@ -560,7 +563,7 @@ def _empty_run_bars_df(self) -> pl.DataFrame:
560563

561564

562565
class DollarRunBarSampler(BarSampler):
563-
"""Sample bars based on cumulative dollar value runs (AFML-compliant).
566+
"""Sample bars based on cumulative dollar value runs.
564567
565568
AFML Chapter 2.3 formula with dollar weighting:
566569
θ_T = max{Σ(buy dollars in bar), Σ(sell dollars in bar)}
@@ -638,6 +641,8 @@ def sample(
638641
p_buys,
639642
cumulative_buys,
640643
cumulative_sells,
644+
current_expected_t,
645+
current_p_buy,
641646
) = _calculate_run_bars_nb(
642647
dollar_volumes, # Use dollar volumes as values
643648
sides,
@@ -705,11 +710,7 @@ def sample(
705710
sell_dollars = float(np.sum(bar_dollars[bar_sides < 0]))
706711
current_theta = max(buy_dollars, sell_dollars)
707712

708-
last_expected_t = (
709-
expected_ts[-1] if len(expected_ts) > 0 else initial_expected_t_scaled
710-
)
711-
last_p_buy = p_buys[-1] if len(p_buys) > 0 else self.initial_p_buy
712-
expected_theta = last_expected_t * max(last_p_buy, 1 - last_p_buy)
713+
expected_theta = current_expected_t * max(current_p_buy, 1 - current_p_buy)
713714

714715
bar = self._create_ohlcv_bar(
715716
bar_ticks,
@@ -722,8 +723,8 @@ def sample(
722723
"expected_run": float(expected_theta),
723724
"theta": float(current_theta),
724725
"expected_theta": float(expected_theta),
725-
"expected_t": float(last_expected_t),
726-
"p_buy": float(last_p_buy),
726+
"expected_t": current_expected_t,
727+
"p_buy": current_p_buy,
727728
"cumulative_buys": float(buy_dollars),
728729
"cumulative_sells": float(sell_dollars),
729730
},

‎tests/bars/test_run_bars.py‎

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
AFML-compliant: uses CUMULATIVE counts, NOT consecutive runs.
55
"""
66

7-
from datetime import datetime
7+
from datetime import UTC, datetime, timedelta
88

99
import numpy as np
1010
import polars as pl
@@ -102,6 +102,7 @@ def test_basic_cumulative_run_detection(self):
102102
p_buys,
103103
cumulative_buys,
104104
cumulative_sells,
105+
*_,
105106
) = _calculate_run_bars_nb(
106107
values,
107108
sides,
@@ -133,6 +134,7 @@ def test_cumulative_not_consecutive(self):
133134
p_buys,
134135
cumulative_buys,
135136
cumulative_sells,
137+
*_,
136138
) = _calculate_run_bars_nb(
137139
values,
138140
sides,
@@ -183,6 +185,7 @@ def test_ewma_update(self):
183185
p_buys,
184186
cumulative_buys,
185187
cumulative_sells,
188+
*_,
186189
) = _calculate_run_bars_nb(
187190
values,
188191
sides,
@@ -378,6 +381,91 @@ def test_dollar_run_expectation_stays_in_dollar_units(self):
378381
assert float(bars["expected_t"][1]) >= 5_000.0
379382

380383

384+
@pytest.fixture(scope="module")
385+
def run_unit_scaling_trades():
386+
return pl.DataFrame(
387+
{
388+
"timestamp": [
389+
datetime(2024, 1, 2, 14, 30, tzinfo=UTC) + timedelta(seconds=i) for i in range(512)
390+
],
391+
"price": [(100 + (i * 7) % 13) / 4 for i in range(512)],
392+
"volume": [float(10 + i % 7) for i in range(512)],
393+
"side": [float([1, -1, 1, 1, -1][i % 5]) for i in range(512)],
394+
}
395+
)
396+
397+
398+
@pytest.mark.parametrize(
399+
"sampler_type,column,scale",
400+
[
401+
(TickRunBarSampler, "volume", 16),
402+
(VolumeRunBarSampler, "volume", 16),
403+
(DollarRunBarSampler, "volume", 16),
404+
(DollarRunBarSampler, "price", 8),
405+
],
406+
)
407+
@pytest.mark.parametrize("alpha", [0.1, 0.25, 0.5, 1.0])
408+
@pytest.mark.parametrize("warmup", [0, 2, 10])
409+
@pytest.mark.parametrize("incomplete", [False, True])
410+
def test_unit_rescaling_does_not_change_run_bar_boundaries(
411+
run_unit_scaling_trades, sampler_type, column, scale, alpha, warmup, incomplete
412+
):
413+
sampler = sampler_type(
414+
expected_ticks_per_bar=16, alpha=alpha, initial_p_buy=0.6, min_bars_warmup=warmup
415+
)
416+
original = sampler.sample(run_unit_scaling_trades, include_incomplete=incomplete)
417+
rescaled = sampler.sample(
418+
run_unit_scaling_trades.with_columns(pl.col(column) * scale), include_incomplete=incomplete
419+
)
420+
assert original.select("timestamp", "tick_count").equals(
421+
rescaled.select("timestamp", "tick_count")
422+
)
423+
424+
425+
@pytest.mark.parametrize(
426+
"sampler_type", [TickRunBarSampler, VolumeRunBarSampler, DollarRunBarSampler]
427+
)
428+
@pytest.mark.parametrize("alpha", [0.1, 0.25, 0.5, 1.0])
429+
@pytest.mark.parametrize("warmup", [0, 1, 10])
430+
@pytest.mark.parametrize("update", [False, True])
431+
@pytest.mark.parametrize("initial_side", [1.0, -1.0])
432+
def test_incomplete_diagnostics_use_final_adaptive_state(
433+
sampler_type, alpha, warmup, update, initial_side
434+
):
435+
complete_bars = warmup + int(update)
436+
size = complete_bars * 4 + 2
437+
trades = pl.DataFrame(
438+
{
439+
"timestamp": [
440+
datetime(2024, 1, 2, 14, 30, tzinfo=UTC) + timedelta(seconds=i) for i in range(size)
441+
],
442+
"price": [100.0] * (size - 1) + [99.75],
443+
"volume": [10.0] * size,
444+
"side": [initial_side] * (size - 2) + [1.0, -1.0],
445+
}
446+
)
447+
if sampler_type is TickRunBarSampler:
448+
values = np.ones(size)
449+
elif sampler_type is VolumeRunBarSampler:
450+
values = np.full(size, 10.0)
451+
else:
452+
values = trades["price"].to_numpy() * 10.0
453+
expected_t = 8 * np.mean(values)
454+
expected_p_buy = 0.5
455+
if update:
456+
expected_t = (1 - alpha) * expected_t + alpha * np.sum(values[:4])
457+
expected_p_buy = (1 - alpha) * 0.5 + alpha * (initial_side > 0)
458+
bars = sampler_type(
459+
expected_ticks_per_bar=8, alpha=alpha, initial_p_buy=0.5, min_bars_warmup=warmup
460+
).sample(trades, include_incomplete=True)
461+
assert bars["tick_count"].to_list() == [4] * complete_bars + [2]
462+
assert bars["expected_t"][-1] == pytest.approx(expected_t)
463+
assert bars["p_buy"][-1] == pytest.approx(expected_p_buy)
464+
expected_theta = expected_t * max(expected_p_buy, 1 - expected_p_buy)
465+
assert bars["expected_theta"][-1] == pytest.approx(expected_theta)
466+
assert bars["expected_run"][-1] == pytest.approx(expected_theta)
467+
468+
381469
class TestVolumeRunBarSampler:
382470
"""Tests for VolumeRunBarSampler."""
383471

@@ -649,6 +737,7 @@ def test_theta_is_max_of_cumulative(self):
649737
p_buys,
650738
cumulative_buys,
651739
cumulative_sells,
740+
*_,
652741
) = _calculate_run_bars_nb(
653742
values,
654743
sides,
@@ -712,6 +801,7 @@ def test_cumulative_not_reset_on_direction_change(self):
712801
p_buys,
713802
cumulative_buys,
714803
cumulative_sells,
804+
*_,
715805
) = _calculate_run_bars_nb(
716806
values,
717807
sides,

0 commit comments

Comments
 (0)