Skip to content

Commit 2edaed3

Browse files
fix: derive futures expiry rolls from authoritative sessions
Closes #101. Count selected schedule sessions before expiry and never snap triggers backward to missing observed dates. Preserve elapsed-day units, shared calendar precedence and existing FirstNotice conventions. Public-builder regressions reproduce the old wrong contract selections; all applicable exact-head checks passed. AI-assisted maintenance reviewed and verified by the repository owner.
1 parent e6568c0 commit 2edaed3

3 files changed

Lines changed: 200 additions & 22 deletions

File tree

‎docs/api/index.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# API Reference
22

3-
Complete API documentation for the `ml4t-data` library, auto-generated from
3+
API documentation for the `ml4t-data` library, generated from
44
source docstrings via [mkdocstrings](https://mkdocstrings.github.io/).
55

66
---
@@ -420,3 +420,42 @@ ML4TDataError
420420
options:
421421
show_source: false
422422
heading_level: 4
423+
424+
## Futures Expiry Rolls
425+
426+
`TimeBasedRoll` selects the nearest available contract until its configured pre-expiry trigger.
427+
`FirstNoticeDateRoll` delegates the same calendar selection while retaining its existing
428+
first-notice offset convention and five-session cash-settled fallback.
429+
430+
| Mode | Offset units | Calendar behavior |
431+
|------|--------------|-------------------|
432+
| `use_business_days=True` (default) | Authoritative sessions strictly before expiration | Explicit `calendar`, then `feed_spec`, then NYSE |
433+
| `use_business_days=False` | Elapsed civil days | No session counting; an explicitly disabled calendar is allowed |
434+
| Session-count mode with `calendar=None` | Unsupported observation-based expiry offset | Raises clearly; does not substitute NYSE or 24/7 |
435+
436+
The legacy `use_business_days` name now counts the selected exchange's sessions rather than
437+
weekdays. `calendar="24/7"` counts a real continuous schedule. Contract exchange identity does not
438+
select a calendar. Pass the feed declaration explicitly when constructing a roll strategy from
439+
stored metadata. Named calendars are validated before selection.
440+
441+
An offset of zero uses expiration itself. A missing scheduled trigger does not move the trigger
442+
backward to an observed date: selection switches at the first eligible later observation, subject
443+
to the existing contract availability and paired-price checks. Explicit elapsed-day mode also
444+
stops snapping its target backward. Neither mode reinterprets missing data as a closure or changes
445+
elapsed days into row counts.
446+
447+
::: ml4t.data.futures.roll.TimeBasedRoll
448+
options:
449+
show_source: false
450+
heading_level: 3
451+
members:
452+
- __init__
453+
- select_contracts
454+
455+
::: ml4t.data.futures.roll.FirstNoticeDateRoll
456+
options:
457+
show_source: false
458+
heading_level: 3
459+
members:
460+
- __init__
461+
- select_contracts

‎src/ml4t/data/futures/roll.py‎

Lines changed: 57 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,13 @@
66
from abc import ABC, abstractmethod
77
from dataclasses import dataclass
88
from datetime import date, timedelta
9+
from typing import Any
910

1011
import polars as pl
1112

1213
from ml4t.data.futures.schema import ContractSpec
14+
from ml4t.data.sessions.assigner import SessionAssigner
15+
from ml4t.specs import UNSET_CALENDAR, CalendarUnset, FeedSpec
1316

1417

1518
@dataclass(frozen=True)
@@ -99,17 +102,34 @@ def select_contracts(
99102

100103

101104
class TimeBasedRoll(RollStrategy):
102-
"""Select the nearest contract until its configured pre-expiry roll date."""
105+
"""Select the nearest contract until its configured pre-expiry roll date.
106+
107+
``use_business_days=True`` counts authoritative sessions strictly before expiration.
108+
Explicit ``calendar`` overrides ``feed_spec``, then NYSE; an exchange identity does not
109+
select a calendar. A missing target session never moves the trigger to an earlier observation.
110+
``use_business_days=False`` selects elapsed civil days, not an observation count.
111+
Calendar-free row-based expiry offsets are unsupported in session-count mode.
112+
"""
103113

104114
def __init__(
105115
self,
106116
days_before_expiration: int = 5,
107117
use_business_days: bool = True,
108-
):
118+
*,
119+
calendar: str | None | CalendarUnset = UNSET_CALENDAR,
120+
feed_spec: Any | None = None,
121+
) -> None:
109122
if days_before_expiration < 0:
110123
raise ValueError("days_before_expiration cannot be negative")
111124
self.days_before_expiration = days_before_expiration
112125
self.use_business_days = use_business_days
126+
self.feed_spec = FeedSpec.from_any(feed_spec)
127+
self.calendar = self.feed_spec.resolve_calendar(calendar=calendar)
128+
if self.calendar is None and use_business_days:
129+
raise ValueError("calendar-free row-based expiry rolls are not supported")
130+
self._schedule_calendar = (
131+
SessionAssigner(self.calendar).calendar if self.calendar is not None else None
132+
)
113133

114134
def select_contracts(
115135
self,
@@ -122,7 +142,7 @@ def select_contracts(
122142
return _empty_selections()
123143
contracts = dict(_contract_expirations(data))
124144
roll_dates = {
125-
symbol: self._calculate_roll_date(expiration, dates)
145+
symbol: self._calculate_roll_date(expiration)
126146
for symbol, expiration in contracts.items()
127147
}
128148
available_by_date = _available_symbols_by_date(data)
@@ -139,38 +159,54 @@ def select_contracts(
139159
)
140160
return _selection_frame(records)
141161

142-
def _calculate_roll_date(self, expiration: date, trading_dates: list[date]) -> date:
143-
"""Calculate the last configured roll date on the observed calendar."""
144-
target = expiration
145-
if self.use_business_days:
146-
days_counted = 0
147-
while days_counted < self.days_before_expiration:
148-
target -= timedelta(days=1)
149-
if target.weekday() < 5:
150-
days_counted += 1
151-
else:
152-
target -= timedelta(days=self.days_before_expiration)
153-
if target >= trading_dates[-1] or target < trading_dates[0]:
154-
return target
155-
observed = [trading_date for trading_date in trading_dates if trading_date <= target]
156-
return max(observed) if observed else target
162+
def _calculate_roll_date(self, expiration: date) -> date:
163+
"""Calculate a schedule or explicit elapsed-day trigger independently of observations."""
164+
if not self.use_business_days:
165+
return expiration - timedelta(days=self.days_before_expiration)
166+
if self.days_before_expiration == 0:
167+
return expiration
168+
span = max(14, self.days_before_expiration * 2)
169+
while True:
170+
try:
171+
start = expiration - timedelta(days=span)
172+
except OverflowError as error:
173+
raise ValueError(
174+
"not enough calendar history for the requested expiry offset"
175+
) from error
176+
schedule = self._schedule_calendar.schedule(
177+
start_date=start, end_date=expiration - timedelta(days=1)
178+
)
179+
if len(schedule) >= self.days_before_expiration:
180+
return schedule.index[-self.days_before_expiration].date()
181+
span *= 2
157182

158183

159184
class FirstNoticeDateRoll(RollStrategy):
160185
"""Select physical contracts before the configured first-notice interval."""
161186

162-
def __init__(self, days_before_first_notice: int = 1):
187+
def __init__(
188+
self,
189+
days_before_first_notice: int = 1,
190+
*,
191+
calendar: str | None | CalendarUnset = UNSET_CALENDAR,
192+
feed_spec: Any | None = None,
193+
) -> None:
163194
if days_before_first_notice < 0:
164195
raise ValueError("days_before_first_notice cannot be negative")
165196
self.days_before_first_notice = days_before_first_notice
197+
self._time_roll = TimeBasedRoll(calendar=calendar, feed_spec=feed_spec)
166198

167199
def select_contracts(
168200
self, data: pl.DataFrame, contract_spec: ContractSpec | None = None
169201
) -> pl.DataFrame:
170202
if contract_spec is None or contract_spec.is_cash_settled:
171-
return TimeBasedRoll(days_before_expiration=5).select_contracts(data, contract_spec)
203+
return self._time_roll.select_contracts(data, contract_spec)
172204
days = (contract_spec.first_notice_days or 25) + self.days_before_first_notice
173-
return TimeBasedRoll(days_before_expiration=days).select_contracts(data, contract_spec)
205+
return TimeBasedRoll(
206+
days_before_expiration=days,
207+
calendar=self._time_roll.calendar,
208+
feed_spec=self._time_roll.feed_spec,
209+
).select_contracts(data, contract_spec)
174210

175211

176212
class CalendarRoll(RollStrategy):
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
"""Provider-generated contract files must use scheduled, not observed, expiry offsets."""
2+
3+
from datetime import date
4+
5+
import polars as pl
6+
import pytest
7+
8+
from ml4t.data.futures.adjustment import NoAdjustment
9+
from ml4t.data.futures.continuous import ContinuousContractBuilder
10+
from ml4t.data.futures.roll import FirstNoticeDateRoll, TimeBasedRoll
11+
from ml4t.data.providers.synthetic import SyntheticProvider
12+
from ml4t.specs import FeedSpec
13+
14+
15+
def write_contract_files(root, expiration, *, missing=None):
16+
with SyntheticProvider() as provider:
17+
frame = provider.fetch_ohlcv("TEST", "2025-07-01", "2025-07-11", "daily")
18+
frame = frame.filter(pl.col("timestamp").dt.date() != date(2025, 7, 4))
19+
if missing is not None:
20+
frame = frame.filter(pl.col("timestamp").dt.date() != missing)
21+
frames = []
22+
for symbol in ("TESTN2025", "TESTU2025"):
23+
frames.append(frame.with_columns(pl.lit(symbol).alias("symbol")))
24+
ohlcv = root / "ohlcv_1d" / "product=TEST"
25+
definitions = root / "definition" / "product=TEST"
26+
ohlcv.mkdir(parents=True)
27+
definitions.mkdir(parents=True)
28+
pl.concat(frames).write_parquet(ohlcv / "ohlcv_1d.parquet")
29+
pl.DataFrame(
30+
{
31+
"raw_symbol": ["TESTN2025", "TESTU2025"],
32+
"expiration": [expiration, date(2025, 9, 19)],
33+
}
34+
).write_parquet(definitions / "definition.parquet")
35+
36+
37+
def build(root, strategy=None):
38+
return ContinuousContractBuilder(
39+
roll_strategy=strategy or TimeBasedRoll(5),
40+
adjustment_method=NoAdjustment(),
41+
).build("TEST", data_source="databento", storage_path=root)
42+
43+
44+
def test_continuous_workflow_counts_the_july4_closure_in_the_expiry_offset(tmp_path):
45+
write_contract_files(tmp_path, date(2025, 7, 10))
46+
result = build(tmp_path)
47+
assert result.filter(pl.col("date") == date(2025, 7, 2))["symbol"].to_list() == ["TESTU2025"]
48+
assert result.filter(pl.col("is_roll_date"))["date"].to_list() == [date(2025, 7, 2)]
49+
50+
51+
def test_missing_scheduled_roll_session_cannot_move_the_roll_before_the_outage(tmp_path):
52+
write_contract_files(tmp_path, date(2025, 7, 11), missing=date(2025, 7, 3))
53+
result = build(tmp_path)
54+
assert result.filter(pl.col("date") == date(2025, 7, 2))["symbol"].to_list() == ["TESTN2025"]
55+
assert result.filter(pl.col("is_roll_date"))["date"].to_list() == [date(2025, 7, 7)]
56+
57+
58+
@pytest.mark.parametrize("strategy", [TimeBasedRoll, FirstNoticeDateRoll])
59+
@pytest.mark.parametrize("explicit,expected", [("NYSE", "TESTU2025"), ("24/7", "TESTN2025")])
60+
def test_roll_and_first_notice_delegate_preserve_calendar_precedence(
61+
tmp_path, strategy, explicit, expected
62+
):
63+
write_contract_files(tmp_path, date(2025, 7, 10))
64+
feed = FeedSpec(time_contract_version=2, calendar="24/7")
65+
result = build(tmp_path, strategy(calendar=explicit, feed_spec=feed))
66+
assert result.filter(pl.col("date") == date(2025, 7, 3))["symbol"].to_list() == [expected]
67+
68+
69+
@pytest.mark.parametrize("strategy", [TimeBasedRoll, FirstNoticeDateRoll])
70+
def test_declared_continuous_schedule_is_not_replaced_by_default_nyse(tmp_path, strategy):
71+
write_contract_files(tmp_path, date(2025, 7, 10))
72+
result = build(tmp_path, strategy(feed_spec=FeedSpec(time_contract_version=2, calendar="24/7")))
73+
assert result.filter(pl.col("is_roll_date"))["date"].to_list() == [date(2025, 7, 7)]
74+
75+
76+
def test_elapsed_day_mode_does_not_snap_the_trigger_before_a_missing_weekend(tmp_path):
77+
write_contract_files(tmp_path, date(2025, 7, 10))
78+
result = build(tmp_path, TimeBasedRoll(5, False))
79+
assert result.filter(pl.col("date") == date(2025, 7, 3))["symbol"].to_list() == ["TESTN2025"]
80+
assert result.filter(pl.col("is_roll_date"))["date"].to_list() == [date(2025, 7, 7)]
81+
82+
83+
def test_explicit_elapsed_units_need_no_calendar_but_do_not_become_row_counts(tmp_path):
84+
write_contract_files(tmp_path, date(2025, 7, 10))
85+
result = build(tmp_path, TimeBasedRoll(5, False, calendar=None))
86+
assert result.filter(pl.col("is_roll_date"))["date"].to_list() == [date(2025, 7, 7)]
87+
88+
89+
@pytest.mark.parametrize("strategy", [TimeBasedRoll, FirstNoticeDateRoll])
90+
def test_disabled_session_count_roll_fails_instead_of_substituting_a_continuous_schedule(strategy):
91+
with pytest.raises(ValueError, match="row-based"):
92+
strategy(calendar=None)
93+
with pytest.raises(ValueError, match="row-based"):
94+
strategy(feed_spec=FeedSpec(time_contract_version=2, calendar=None))
95+
96+
97+
def test_invalid_calendar_does_not_change_provider_contract_files(tmp_path):
98+
write_contract_files(tmp_path, date(2025, 7, 10))
99+
source = tmp_path / "ohlcv_1d" / "product=TEST" / "ohlcv_1d.parquet"
100+
before = source.read_bytes()
101+
with pytest.raises(ValueError, match="Unknown calendar"):
102+
build(tmp_path, TimeBasedRoll(calendar="not-a-calendar"))
103+
assert source.read_bytes() == before

0 commit comments

Comments
 (0)