Skip to content

Commit d99c60f

Browse files
author
Stefan Jansen
committed
fix: honor CME crypto cutover and business trade dates
1 parent 721adee commit d99c60f

5 files changed

Lines changed: 275 additions & 15 deletions

File tree

‎docs/user-guide/sessions.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,27 @@ assigner = SessionAssigner("CME Globex Crypto")
114114
Calendar names and schedules can change upstream. Check the installed calendar before assigning a
115115
large dataset.
116116

117+
### CME Crypto and Spot Crypto
118+
119+
`CME` selects CME Globex cryptocurrency futures and options, not all CME products and not
120+
spot-quoted futures. Data preserves the upstream historical schedule through May 29, 2026. After
121+
that day's 16:00-16:30 Chicago maintenance, trading includes weekends and holidays. Regular Globex
122+
maintenance is Monday-Friday 16:00-16:02 Chicago time and Saturday 02:00-04:00. Pre-open periods
123+
are not trading intervals. See the [CME crypto FAQ](https://www.cmegroup.com/articles/faqs/frequently-asked-questions-cryptocurrency-futures.html)
124+
and [launch notice](https://cmegroupclientsite.atlassian.net/wiki/spaces/EPICSANDBOX/pages/1283194884/Cryptocurrency+Futures+and+Options+Migration+to+24-7+Trading).
125+
126+
CME observations retain the following business trade date across weekends and holidays, rather
127+
than acquiring a separate Saturday or Sunday label. Data uses the upstream `CME_TradeDate`
128+
business calendar, qualified against CME's
129+
[2026 reporting calendar](https://www.cmegroup.com/content/dam/cmegroup/notices/market-regulation/2026/01/msn01-09-2026revisedholidayprocessinglargetrader2026.pdf).
130+
Schedule queries include the next business date when needed; a Saturday observation can therefore
131+
map to Monday, or Tuesday after Labor Day. Assignment and completion share these intervals and
132+
exclude maintenance. The adapter does not change the upstream calendar registry or other products.
133+
134+
Ordinary spot crypto uses `calendar="24/7"`, with civil-day labels and no CME maintenance. Explicit
135+
`calendar=None` disables session handling instead. Select the schedule from the feed's actual
136+
market, not from its symbol or asset-class name.
137+
117138
## Complete Minute Sessions
118139

119140
`SessionCompleter` expands minute bars to the exchange schedule. It requires `timestamp`, `open`,
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
"""CME crypto's May 2026 transition, without changing the upstream registry."""
2+
3+
from __future__ import annotations
4+
5+
from typing import Any
6+
7+
import pandas as pd
8+
9+
10+
class CMEGlobexCryptoSchedule:
11+
def __init__(self, legacy: Any, trade_dates: Any) -> None:
12+
self._legacy = legacy
13+
self._trade_dates = trade_dates
14+
self._business_day = trade_dates.holidays()
15+
self.tz = legacy.tz
16+
self.name = legacy.name
17+
18+
def schedule(
19+
self, start_date: Any, end_date: Any, tz: Any = "UTC", *, interruptions: bool = False
20+
) -> pd.DataFrame:
21+
start = pd.Timestamp(start_date).tz_localize(None).normalize()
22+
end = pd.Timestamp(end_date).tz_localize(None).normalize()
23+
if start > end:
24+
raise ValueError("start_date must not be later than end_date")
25+
cutover = pd.Timestamp("2026-05-29")
26+
frames = []
27+
if start <= cutover:
28+
frames.append(
29+
self._legacy.schedule(start, min(end, cutover), tz=tz, interruptions=interruptions)
30+
)
31+
if end > cutover:
32+
labels = self._trade_dates.valid_days(
33+
max(start, cutover + pd.Timedelta(days=1)), end, tz=None
34+
)
35+
rows = []
36+
for label in labels:
37+
previous = label - self._business_day
38+
opening = previous + pd.Timedelta(hours=16, minutes=2)
39+
if previous == cutover:
40+
opening = previous + pd.Timedelta(hours=16, minutes=30)
41+
closing = label + pd.Timedelta(hours=16)
42+
row = {
43+
"market_open": opening.tz_localize(self.tz).tz_convert(tz),
44+
"market_close": closing.tz_localize(self.tz).tz_convert(tz),
45+
}
46+
if interruptions:
47+
closures = []
48+
for day in pd.date_range(previous, label):
49+
if day.dayofweek < 5:
50+
halt = day + pd.Timedelta(hours=16)
51+
reopen = halt + pd.Timedelta(minutes=2)
52+
elif day.dayofweek == 5:
53+
halt = day + pd.Timedelta(hours=2)
54+
reopen = halt + pd.Timedelta(hours=2)
55+
else:
56+
continue
57+
if opening < reopen and halt < closing:
58+
closures.append((halt, reopen))
59+
for index, (halt, reopen) in enumerate(closures, start=1):
60+
row[f"interruption_start_{index}"] = halt.tz_localize(self.tz).tz_convert(
61+
tz
62+
)
63+
row[f"interruption_end_{index}"] = reopen.tz_localize(self.tz).tz_convert(
64+
tz
65+
)
66+
rows.append(row)
67+
frames.append(
68+
pd.DataFrame(
69+
rows, index=labels, columns=None if rows else ["market_open", "market_close"]
70+
)
71+
)
72+
return pd.concat(frames).sort_index()
73+
74+
def schedule_for_instants(self, start: Any, end: Any) -> pd.DataFrame:
75+
start_timestamp, end_timestamp = pd.Timestamp(start), pd.Timestamp(end)
76+
start_local = (
77+
start_timestamp.tz_convert(self.tz) if start_timestamp.tzinfo else start_timestamp
78+
)
79+
end_local = end_timestamp.tz_convert(self.tz) if end_timestamp.tzinfo else end_timestamp
80+
next_trade_date = pd.Timestamp(end_local.date()) + self._business_day
81+
return self.schedule(
82+
pd.Timestamp(start_local.date()) - pd.Timedelta(days=1),
83+
next_trade_date,
84+
interruptions=True,
85+
)

‎src/ml4t/data/sessions/assigner.py‎

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,20 @@ def _session_intervals(row: Any) -> list[tuple[datetime, datetime]]:
5252
return intervals
5353

5454

55+
def _schedule_for_instants(calendar: Any, start: Any, end: Any) -> Any:
56+
import pandas as pd
57+
58+
from ml4t.data.sessions._cme_crypto import CMEGlobexCryptoSchedule
59+
60+
if isinstance(calendar, CMEGlobexCryptoSchedule):
61+
return calendar.schedule_for_instants(start, end)
62+
return calendar.schedule(
63+
start_date=pd.Timestamp(start).normalize() - pd.Timedelta(days=1),
64+
end_date=pd.Timestamp(end).normalize() + pd.Timedelta(days=1),
65+
interruptions=True,
66+
)
67+
68+
5569
# Exchange to calendar mapping
5670
EXCHANGE_CALENDARS = {
5771
"CME": "CME Globex Crypto",
@@ -111,8 +125,7 @@ class SessionAssigner:
111125
Uses pandas_market_calendars to determine trading sessions and assigns
112126
a session_date column to each timestamp.
113127
114-
For CME futures, sessions start at 5pm CT Sunday and end at 4pm CT Friday.
115-
The session_date is the date when the session ENDS (4pm date).
128+
CME crypto uses business trade dates across overnight and weekend trading.
116129
"""
117130

118131
def __init__(
@@ -168,6 +181,16 @@ def __init__(
168181

169182
try:
170183
self.calendar = mcal.get_calendar(self.calendar_name)
184+
from pandas_market_calendars.calendars.cme_globex_crypto import (
185+
CMEGlobexCryptoExchangeCalendar,
186+
)
187+
188+
if type(self.calendar) is CMEGlobexCryptoExchangeCalendar:
189+
from ml4t.data.sessions._cme_crypto import CMEGlobexCryptoSchedule
190+
191+
self.calendar = CMEGlobexCryptoSchedule(
192+
self.calendar, mcal.get_calendar("CME_TradeDate")
193+
)
171194
except Exception as e:
172195
raise ValueError(f"Unknown calendar '{self.calendar_name}': {e}")
173196

@@ -265,11 +288,7 @@ def assign_sessions(
265288
end_timestamp, pd.Timestamp
266289
):
267290
raise ValueError("start_date and end_date must not be NaT")
268-
start_pd = start_timestamp.normalize() - pd.Timedelta(days=1)
269-
end_pd = end_timestamp.normalize() + pd.Timedelta(days=1)
270-
schedule = self.calendar.schedule(
271-
start_date=start_pd, end_date=end_pd, interruptions=True
272-
)
291+
schedule = _schedule_for_instants(self.calendar, start_timestamp, end_timestamp)
273292
logger.debug(f"Got {len(schedule)} sessions from calendar")
274293

275294
session_map = []

‎src/ml4t/data/sessions/completer.py‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,11 @@
1111
import polars as pl
1212
import structlog
1313

14-
from ml4t.data.sessions.assigner import SessionAssigner, _session_intervals
14+
from ml4t.data.sessions.assigner import (
15+
SessionAssigner,
16+
_schedule_for_instants,
17+
_session_intervals,
18+
)
1519
from ml4t.specs import UNSET_CALENDAR, BarLabel, CalendarUnset, TimestampSemantics
1620

1721
logger = structlog.get_logger()
@@ -166,13 +170,7 @@ def complete_sessions(
166170
):
167171
raise ValueError("start_date and end_date must be minute-aligned")
168172

169-
start_pd = request_start.normalize() - pd.Timedelta(days=1)
170-
end_pd = request_end.normalize() + pd.Timedelta(days=1)
171-
172-
# Get trading schedule
173-
schedule = self.calendar.schedule(
174-
start_date=start_pd, end_date=end_pd, interruptions=True
175-
)
173+
schedule = _schedule_for_instants(self.calendar, request_start, request_end)
176174

177175
if len(schedule) == 0:
178176
logger.warning("No trading sessions found in date range")

‎tests/test_cme_crypto_cutover.py‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
"""Real provider rows must survive the CME crypto schedule transition."""
2+
3+
from datetime import date, datetime
4+
5+
import polars as pl
6+
import pytest
7+
from polars.testing import assert_frame_equal
8+
9+
from ml4t.data import DataManager
10+
from ml4t.data.providers import SyntheticProvider
11+
from ml4t.data.sessions import SessionAssigner, SessionCompleter
12+
from ml4t.specs import FeedSpec
13+
14+
15+
def provider_rows(day: str, clocks: list[str]) -> pl.DataFrame:
16+
with SyntheticProvider(calendar_mode="continuous") as provider:
17+
frame = provider.fetch_ohlcv("BTCUSD", day, day, "minute")
18+
selected = frame.filter(pl.col("timestamp").dt.strftime("%H:%M").is_in(clocks))
19+
assert selected.height == len(clocks)
20+
return selected
21+
22+
23+
@pytest.mark.parametrize(
24+
"day,clock,expected",
25+
[
26+
("2026-05-23", "12:00", None),
27+
("2026-05-30", "12:00", date(2026, 6, 1)),
28+
("2026-10-17", "12:00", date(2026, 10, 19)),
29+
("2026-10-16", "21:03", date(2026, 10, 19)),
30+
("2026-10-16", "21:00", None),
31+
("2026-10-16", "21:01", None),
32+
("2026-10-17", "07:59", None),
33+
("2026-10-17", "09:00", date(2026, 10, 19)),
34+
("2026-12-05", "08:00", None),
35+
("2026-12-05", "10:00", date(2026, 12, 7)),
36+
("2026-05-29", "21:15", None),
37+
("2026-05-29", "21:30", date(2026, 6, 1)),
38+
("2026-09-05", "12:00", date(2026, 9, 8)),
39+
("2026-07-02", "21:03", date(2026, 7, 6)),
40+
("2026-06-18", "21:03", date(2026, 6, 22)),
41+
("2026-11-25", "22:03", date(2026, 11, 27)),
42+
("2026-12-24", "22:03", date(2026, 12, 28)),
43+
("2026-10-12", "12:00", date(2026, 10, 12)),
44+
("2026-11-11", "12:00", date(2026, 11, 11)),
45+
("2026-05-29", "20:59", date(2026, 5, 29)),
46+
("2026-05-28", "21:30", None),
47+
("2026-05-28", "22:00", date(2026, 5, 29)),
48+
("2026-11-01", "07:30", date(2026, 11, 2)),
49+
],
50+
)
51+
def test_cme_crypto_uses_cutover_maintenance_and_business_dates(day, clock, expected):
52+
frame = provider_rows(day, [clock])
53+
assigned = SessionAssigner.from_exchange("CME").assign_sessions(frame, bar_frequency="intraday")
54+
assert assigned["session_date"].to_list() == [expected]
55+
assert_frame_equal(assigned.select(frame.columns), frame)
56+
57+
58+
def test_cme_completion_preserves_weekend_observations_and_fills_only_open_gap():
59+
frame = provider_rows("2026-10-17", ["12:00", "12:02"])
60+
completed = SessionCompleter("CME Globex Crypto").complete_sessions(frame)
61+
assert completed.height == 3
62+
assert completed["is_imputed"].to_list() == [False, True, False]
63+
assert completed["session_date"].to_list() == [date(2026, 10, 19)] * 3
64+
observed = completed.filter(~pl.col("is_imputed")).select(frame.columns).cast(frame.schema)
65+
assert_frame_equal(observed, frame)
66+
67+
68+
def test_spot_continuous_calendar_keeps_civil_dates_not_cme_trade_dates():
69+
frame = provider_rows("2026-10-17", ["12:00", "12:02"])
70+
assigned = SessionAssigner("24/7").assign_sessions(frame, bar_frequency="intraday")
71+
assert assigned["session_date"].to_list() == [date(2026, 10, 17)] * 2
72+
completed = SessionCompleter("24/7").complete_sessions(frame)
73+
assert completed.height == 3
74+
assert completed["session_date"].to_list() == [date(2026, 10, 17)] * 3
75+
76+
77+
def test_calendar_none_never_assigns_or_manufactures_cme_or_spot_rows():
78+
frame = provider_rows("2026-10-17", ["12:00", "12:02"])
79+
assert_frame_equal(SessionAssigner(None).assign_sessions(frame), frame)
80+
assert_frame_equal(SessionCompleter(None).complete_sessions(frame), frame)
81+
82+
83+
@pytest.mark.parametrize(
84+
"day,clocks,expected",
85+
[
86+
("2026-10-17", ["06:59", "09:00"], [date(2026, 10, 19)] * 2),
87+
("2026-09-07", ["20:59", "21:02"], [date(2026, 9, 8)] * 2),
88+
("2026-05-29", ["20:59", "21:30"], [date(2026, 5, 29), date(2026, 6, 1)]),
89+
],
90+
)
91+
def test_completion_does_not_fill_weekly_holiday_or_launch_maintenance(day, clocks, expected):
92+
frame = provider_rows(day, clocks)
93+
completed = SessionCompleter("CME Globex Crypto").complete_sessions(frame)
94+
assert completed.height == 2
95+
assert completed["is_imputed"].to_list() == [False, False]
96+
assert completed["session_date"].to_list() == expected
97+
assert_frame_equal(completed.select(frame.columns).cast(frame.schema), frame)
98+
99+
100+
@pytest.mark.parametrize("alias", ["CME Globex Crypto", "CME Globex Cryptocurrencies"])
101+
def test_cme_aliases_and_facade_honor_shared_override_and_disable(alias):
102+
frame = provider_rows("2026-10-17", ["12:00"])
103+
feed = FeedSpec(calendar=alias, timestamp_semantics="event_time")
104+
with DataManager() as manager:
105+
assert manager.assign_sessions(frame, feed_spec=feed)["session_date"].to_list() == [
106+
date(2026, 10, 19)
107+
]
108+
assert manager.assign_sessions(frame, calendar="24/7", feed_spec=feed)[
109+
"session_date"
110+
].to_list() == [date(2026, 10, 17)]
111+
assert_frame_equal(manager.assign_sessions(frame, calendar=None, feed_spec=feed), frame)
112+
113+
114+
def test_selected_crypto_schedule_does_not_modify_upstream_or_other_product_calendars():
115+
import pandas_market_calendars as mcal
116+
from pandas_market_calendars.calendars.cme_globex_crypto import CMEGlobexCryptoExchangeCalendar
117+
118+
SessionAssigner("CME Globex Crypto")
119+
legacy = mcal.get_calendar("CME Globex Crypto")
120+
assert type(legacy) is CMEGlobexCryptoExchangeCalendar
121+
assert legacy.schedule("2026-10-17", "2026-10-17").empty
122+
other = SessionAssigner("CME_Equity")
123+
frame = provider_rows("2026-10-17", ["12:00"])
124+
assert other.assign_sessions(frame, bar_frequency="intraday")["session_date"].to_list() == [
125+
None
126+
]
127+
128+
129+
def test_cme_daily_labels_are_business_dates_not_each_open_weekend_civil_date():
130+
with SyntheticProvider(calendar_mode="continuous") as provider:
131+
daily = provider.fetch_ohlcv("BTCUSD", "2026-10-17", "2026-10-19", "daily")
132+
feed = FeedSpec(calendar="CME Globex Crypto", timestamp_semantics="session_label")
133+
assigned = SessionAssigner(feed_spec=feed).assign_sessions(daily)
134+
assert assigned["session_date"].to_list() == [None, None, date(2026, 10, 19)]
135+
info = SessionCompleter("CME Globex Crypto").get_session_info(datetime(2026, 10, 19))
136+
assert info["market_open"].isoformat() == "2026-10-16T21:02:00+00:00"
137+
assert info["market_close"].isoformat() == "2026-10-19T21:00:00+00:00"

0 commit comments

Comments
 (0)