"""
Business day calendar utilities.
Uses pandas_market_calendars to get NYSE trading days and identify
early-close (half) days.
"""
from __future__ import annotations
import datetime as dt
import math as math
from dataclasses import dataclass
from zoneinfo import ZoneInfo
import numpy as np
import pandas_market_calendars as mcal
import polars as pl
from cdxcore.err import verify_inp
from cdxcore.version import version
import quantdata as quantdata # NOQA
import warnings
TZ_NY = ZoneInfo("America/New_York")
""" New York time zone. """
DAYS_PER_YEAR = 252
""" Standardized business days per year. """
ONE_MINUTE = 1.0 / (60.0 * 6.5 * DAYS_PER_YEAR)
""" One minute in year fraction, assuming 6.5 trading hours per day and ``DAYS_PER_YEAR`` trading days per year. """
AM_EXIRY_SUBTRACT = 0.8
""" How much to subtract from an expiry (in days) to account for AM settlement. """
NYSE_CALENDAR = mcal.get_calendar("NYSE")
""" NYSE calendar provided by `pandas market calendars <https://pandas-market-calendars.readthedocs.io/en/latest/usage.html>`_. """
_BUSINESS_DAYS_CACHE = {}
_EARLY_DAYS_CACHE = {}
[docs]
@dataclass(frozen=True)
class NormalizedStrikes:
r"""
NMS generates relative strikes by:
$$
\mathrm{NMS}(z,t) := \exp\left( z \cdot \sqrt{\frac{\sigma_\epsilon^2\epsilon+\sigma^2 t}{\epsilon+1}} \right)
$$
where:
* $\epsilon$ is :attr:`EPS`, and $t$ is time to expiry in years.
* $\sigma$ is the volatility scale, which defaults to :attr:`SCALE`.
* $\sigma_\epsilon$ is the volatility scale for epsilon.
"""
EPS : float = 1.0 / DAYS_PER_YEAR / 8.0 #: Small epsilon for NMS computation ~ 1 hour
SCALE : float = math.log(1.1) #: 10% vol
def __post_init__(self):
verify_inp( self.EPS > 0., "EPS must be positive" )
verify_inp( self.SCALE > 0., "SCALE must be positive" )
[docs]
def from_nms(self, z: float|np.ndarray, t: float|np.ndarray, *, vol : float|np.ndarray|None = None, eps_vol : float|np.ndarray|None = None, backbone=np) -> float|np.ndarray:
"""
Converts an NMS strike to a relative strike
Parameters
----------
z : float | :class:`numpy.ndarray`
NMS strike level.
t : float | :class:`numpy.ndarray`
Time to expiry in years.
vol : float | :class:`numpy.ndarray` | None, default ``None``
Volatility in year fraction. If None, :attr:`SCALE` is used.
eps_vol : float | :class:`numpy.ndarray`| None, default ``None``
Volatility scale for epsilon. If None, :attr:`SCALE` is used.
backbone : :class:`Backbone`, default :class:`BackboneNumpy`
Alternative backbone, e.g. torch or jax.
Returns
-------
Strikes: float or :class:`numpy.ndarray`
Relative strikes corresponding to the given NMS strikes, time to expiry and volatility.
"""
assert np.min(t) >= 0., "Time must be non-negative"
if not vol is None:
assert np.min(vol) > 0., "Volatility must be positive"
else:
vol = self.SCALE
if eps_vol is None:
eps_vol = self.SCALE
else:
assert np.min(eps_vol) > 0., "Eps_vol must be positive"
return backbone.exp(z * backbone.sqrt((eps_vol * eps_vol * self.EPS + vol * vol * t) / (self.EPS + 1.0)))
[docs]
def to_nms(self, k: float|np.ndarray, t: float|np.ndarray, *, vol: float|np.ndarray|None = None, eps_vol : float|np.ndarray|None = None, backbone=np) -> float|np.ndarray:
"""
Converts a relative strike to an NMS strike.
Parameters
----------
k : float | :class:`numpy.ndarray`
Relative strike level.
t : float | :class:`numpy.ndarray`
Time to expiry in years.
vol : float | :class:`numpy.ndarray` | None, default ``None``
Volatility in year fraction. If None, :attr:`SCALE` is used.
eps_vol : float | :class:`numpy.ndarray`| None, default ``None``
Volatility scale for epsilon. If None, :attr:`SCALE` is used.
backbone : :class:`Backbone`, default :class:`BackboneNumpy`
Alternative backbone, e.g. torch or jax.
Returns
-------
NMS Strikes: float or :class:`numpy.ndarray`
Relative strikes corresponding to the given NMS strikes, time to expiry and volatility.
"""
vol = self.SCALE if vol is None else vol
assert np.min(k) > 0., "Strike must be positive"
assert np.min(t) >= 0., "Time must be non-negative"
if not vol is None:
assert np.min(vol) > 0., "Volatility must be positive"
else:
vol = self.SCALE
if eps_vol is None:
eps_vol = self.SCALE
else:
assert np.min(eps_vol) > 0., "Eps_vol must be positive"
return (backbone.log(k) ) * backbone.sqrt((self.EPS + 1.0) / (eps_vol * eps_vol * self.EPS + vol * vol * t))
NMS = NormalizedStrikes(EPS = 1.0 / DAYS_PER_YEAR / 8.0, SCALE = math.log(1.1))
NMS5 = NormalizedStrikes(EPS = 5.0 / DAYS_PER_YEAR, SCALE=math.log(1.1))
[docs]
def to_date(d: str | dt.datetime | dt.date | np.datetime64 | None) -> dt.date | None:
"""
Convert ``d`` to a :class:`datetime.date`, or ``None`` if ``d`` is ``None``.
This function converts:
* ``np.datetime64``
* :class:`datetime.datetime`
* :class:`datetime.date`
* ``str`` assuming it is in iso format e.g. "2024-01-31"
"""
if d is None:
return d
if isinstance(d, np.datetime64):
d = d.astype("datetime64[D]").astype(dt.date)
if isinstance(d, dt.datetime):
return d.date()
if isinstance(d, dt.date):
return d
if isinstance(d, str):
return dt.date.fromisoformat(d)
raise ValueError(f"Unsupported type for date conversion: {type(d)}")
[docs]
@version("0.1")
def get_business_days(
start: str | dt.date, end: str | dt.date, exclude_half_days: bool = False
) -> list[dt.date]:
"""
Return NYSE trading days within start and end.
This function returns business days inclusive of ``start`` and ``end``. That means that if ``start`` equals ``end``, and if that is a trading day,
then this function returns that day.
Parameters
----------
start : str | :class:`datetime.date`
Start date (inclusive).
end : str | :class:`datetime.date`
End date (inclusive).
exclude_half_days : bool, default ``False``
If True, remove early-close trading sessions from the calendar.
Returns
-------
list[:class:`datetime.date`]
Sorted trading dates (timezone-naive, date-only precision).
"""
global _BUSINESS_DAYS_CACHE
start = to_date(start)
end = to_date(end)
exclude_half_days = bool(exclude_half_days)
if start > end:
raise ValueError(f"start ({start}) must be <= end ({end})")
key = (start, end, exclude_half_days)
schedule = _BUSINESS_DAYS_CACHE.get(key, None)
if schedule is not None:
return schedule
schedule = NYSE_CALENDAR.schedule(start_date=str(start), end_date=str(end))
if exclude_half_days and len(schedule) > 0:
early = NYSE_CALENDAR.early_closes(schedule)
schedule = schedule.drop(early.index, errors="ignore")
schedule = schedule.index.normalize().tz_localize(
None
) # index is a DatetimeIndex of trading days in the range
schedule = [dt.date(d.year, d.month, d.day) for d in schedule]
assert len(schedule) == 0 or schedule[0] <= schedule[-1], f"Internal error: schedule is not sorted: {schedule}"
_BUSINESS_DAYS_CACHE[key] = schedule
return schedule
[docs]
@version("0.1", dependencies=[get_business_days])
def count_business_days_between(
start: dt.date | np.ndarray,
end: dt.date | np.ndarray,
exclude_half_days: bool = False,
) -> int | np.ndarray:
"""
Count the number of trading days in ``(start, end]``, i.e. from ``start`` (exclusive) to ``end`` (inclusive).
If ``end < start``, then count the number of trading days in ``[end, start)`` and return the negative of that count.
The count *includes* ``end`` if it is a trading day, but *excludes* ``start``, assuming, essentially, an end-of-day convention.
Half days are counted as full trading days unless ``exclude_half_days`` is ``True``.
If ``start == end``, and if that day is a business day, then this function returns 0.
If ``start`` and ``end`` are non-business days bracketing no business days, this function raises a :class:`ValueError`.
Parameters
----------
start : ``datetime.date`` | :class:`numpy.ndarray` of dates
Start date(s) (exclusive).
end : ``datetime.date`` | :class:`numpy.ndarray` of dates
End date(s) (inclusive).
exclude_half_days : bool, default ``False``
If True, remove early-close trading sessions from the calendar before counting.
Returns
-------
Count: ``int`` or :class:`numpy.ndarray`
Number of trading days.
"""
start = to_date(start) if not isinstance(start, np.ndarray) else start
end = to_date(end) if not isinstance(end, np.ndarray) else end
is_vec = isinstance(start, np.ndarray) or isinstance(end, np.ndarray)
start = np.asarray(start, dtype="datetime64[D]")
end = np.asarray(end, dtype="datetime64[D]")
mstart = min(np.min(start), np.min(end))
mend = max(np.max(start), np.max(end))
trading_days = get_business_days(mstart, mend, exclude_half_days=exclude_half_days)
if len(trading_days) == 0:
raise ValueError(f"No trading days between {mstart} and {mend} with half days {'excluded' if exclude_half_days else 'included'}")
if not is_vec:
# Scalar case: count how many trading days are in (start, end]
if start <= end:
count = np.sum((trading_days > start) & (trading_days <= end))
else:
count = -np.sum((trading_days >= end) & (trading_days < start))
return int(count)
# Vectorised case: for each pair of start[i], end[i], count trading days in (start[i], end[i]]
td_array = np.asarray(trading_days, dtype="datetime64[D]")
lo = np.searchsorted(td_array, start, side="right")
hi = np.searchsorted(td_array, end, side="right")
return (hi - lo).astype(np.int32)
[docs]
@version("0.1", dependencies=[get_business_days])
def add_business_days(
start: dt.date, num_days: int, exclude_half_days: bool = False, *, count_start: bool = False
) -> dt.date:
"""
Add a number of business days to a date.
Note that if ``start`` is a business day then use ``count_start`` to include it in counting:
if ``start`` is a business day, and if ``count_start`` is ``True``, then
if ``num_days=1`` or ``num_days=-1`` then the function will the return ``start``.
Parameters
----------
start : ``datetime.date``
Start date. This function raises a :class:`ValueError` if ``start`` is not a business day, or if
it is a half business day and ``exclude_half_days`` is ``False``.
num_days : int
Number of business days to add. Can be negative to subtract business days.
exclude_half_days : bool, default ``False``
If ``True``, remove early-close trading sessions from the calendar before counting.
count_start : bool, default ``False``
Whether to count ``start`` if it is a business day. In that case ``start`` is counted in either
direction as the first day.
If ``False``, then the counts starts from the first business day after start.
This flag has no effect if ``start`` is not a business day.
Returns
-------
``datetime.date``
Resulting date after adding the specified number of business days.
"""
if isinstance(start, np.ndarray):
start = np.asarray(start, dtype="datetime64[D]")
if isinstance(num_days, np.ndarray):
verify_inp( start.shape == num_days.shape,
f"start and num_days must have the same shape, but got {start.shape} and {num_days.shape}" )
return np.asarray( [
add_business_days(s, n, exclude_half_days=exclude_half_days)
for s, n in zip(start, num_days)
], dtype="datetime64[D]" )
return np.asarray(
[add_business_days(s, num_days, exclude_half_days=exclude_half_days) for s in start],
dtype="datetime64[D]")
if isinstance(num_days, np.ndarray):
return np.asarray(
[add_business_days(start, n, exclude_half_days=exclude_half_days) for n in num_days],
dtype="datetime64[D]" )
# scalar version
start = to_date(start)
num_days = int(num_days)
if num_days >= 0:
schedule = get_business_days(
start,
start + dt.timedelta(days=(num_days // 5) * 7 + 7),
exclude_half_days=exclude_half_days,
)
assert len(schedule) > 0, "Internal error - this should never happen"
assert schedule[0] >= start, (
f"Schedule should start on or after {start}, but starts at {schedule[0]}"
)
if start == schedule[0] and count_start:
# start is a business day
num_days = max(0, num_days - 1) # count start, so we need to subtract 1 from num_days
return schedule[num_days]
else:
schedule = get_business_days(
start + dt.timedelta(days=-(abs(num_days) // 5 * 7 + 7)),
start,
exclude_half_days=exclude_half_days,
)
assert len(schedule) > 0, "Internal error - this should never happen"
assert schedule[-1] <= start, (
f"Schedule should end on or before {start}, but ends at {schedule[-1]}"
)
schedule = list(schedule)
schedule.reverse() # reverse to count backwards
num_days = -num_days
if start == schedule[0] and count_start:
# start is a business day
num_days = max(0, num_days - 1) # count start, so we need to subtract 1 from num_days
return schedule[num_days]
[docs]
@version("0.1", dependencies=[add_business_days])
def prev_business_day(
date: dt.date, exclude_half_days: bool = False, *, count_start: bool = False
) -> dt.date:
"""
Get the previous business day before the given date.
Parameters
----------
date : ``datetime.date``
Reference date. This date does not have to be a business day.
exclude_half_days : bool, default ``False``
If True, remove early-close trading sessions from the calendar before counting.
count_start : bool, default ``False``
Whether to count ``date`` if it is a business day. If ``False``, then the counts starts from the first business day before date.
That means even if ``date`` is a business day, the function will return the previous business day before it.
If ``True``, then if ``date`` is a business day, the function will return that date.
This flag has no effect if ``date`` is a business day.
Returns
-------
``datetime.date``
Previous business day before the given date.
"""
return add_business_days(date, -1, exclude_half_days=exclude_half_days, count_start=count_start)
[docs]
@version("0.1", dependencies=[add_business_days])
def next_business_day(
date: dt.date, exclude_half_days: bool = False, *, count_start: bool = False
) -> dt.date:
"""
Get the next business day after the given date.
Parameters
----------
date : ``datetime.date``
Reference date. This date does not have to be a business day.
exclude_half_days : bool, default ``False``
If True, remove early-close trading sessions from the calendar before counting.
count_start : bool, default ``False``
Whether to count ``date`` if it is a business day. If ``False``, then the counts starts from the first business day after date.
That means even if ``date`` is a business day, the function will return the next business day after it.
If ``True``, then if ``date`` is a business day, the function will return that date.
This flag has no effect if ``date`` is a business day.
Returns
-------
``datetime.date``
Next business day after the given date.
"""
return add_business_days(date, 1, exclude_half_days=exclude_half_days, count_start=count_start)
[docs]
@version("0.1")
def get_half_days(start: dt.date, end: dt.date) -> list[dt.date]:
"""
Return a list of half days (early closes) between start and end, inclusive.
"""
global _EARLY_DAYS_CACHE
start = to_date(start)
end = to_date(end)
if start > end:
raise ValueError(f"start ({start}) must be <= end ({end})")
key = (start, end)
schedule = _EARLY_DAYS_CACHE.get(key, None)
if schedule is not None:
return schedule
schedule = NYSE_CALENDAR.schedule(start_date=str(start), end_date=str(end))
schedule = NYSE_CALENDAR.early_closes(schedule=schedule)
schedule = schedule.index.normalize().tz_localize(
None
) # index is a DatetimeIndex of trading days in the range
schedule = [dt.date(d.year, d.month, d.day) for d in schedule]
_EARLY_DAYS_CACHE[key] = schedule
return schedule
[docs]
@version("0.1", dependencies=[get_business_days, get_half_days])
@dataclass
class DateRange:
"""A simple date range class."""
start: dt.date | str #: Start date (inclusive).
end: dt.date | str #: End date (inclusive).
exclude_half_days: bool = True #: Whether to exclude half days (early closes) from the business day count. Default is True.
def __post_init__(self):
if isinstance(self.start, str):
self.start = dt.date.fromisoformat(self.start)
if isinstance(self.end, str):
self.end = dt.date.fromisoformat(self.end)
verify_inp(
isinstance(self.start, dt.date),
f"'start' must be a datetime.date, but found {type(self.start)}",
)
verify_inp(
isinstance(self.end, dt.date),
f"'end' must be a datetime.date, but found {type(self.end)}",
)
if self.start > self.end:
raise ValueError(f"'start' ({self.start}) must be at or before 'end' ({self.end})")
bdays = self.get_business_days()
if len(bdays) == 0:
raise ValueError(
f"No business days in the range {self.start} to {self.end} with half days {'excluded' if self.exclude_half_days else 'included'}"
)
def __str__(self):
return f"{self.start}_{self.end}{'x' if self.exclude_half_days else 'i'}"
def __hash__(self):
return hash((self.start, self.end, self.exclude_half_days))
[docs]
def get_business_days(self) -> list[dt.date]:
"""Get business days in this date range."""
return get_business_days(self.start, self.end, exclude_half_days=self.exclude_half_days)
[docs]
def get_half_days(self) -> list[dt.date]:
"""Get half days (early closes) in this date range."""
return get_half_days(self.start, self.end) if not self.exclude_half_days else []
[docs]
@version("0.1")
def session_open_close( date: dt.date ) -> tuple[dt.datetime, dt.datetime, bool]:
"""
Returns the session open and close for a given ``date`` as :class:`datetime.datetime` objects in New York time zone,
and a boolean indicating whether it is a half day (early close) or not.
This function will return ``(None, None, False)`` if the given date is not a trading day.
"""
date = to_date(date)
schedule = NYSE_CALENDAR.schedule(start_date=date, end_date=date)
if len(schedule) == 0:
return None, None, False
early = NYSE_CALENDAR.early_closes(schedule)
with warnings.catch_warnings(action="ignore"):
schedule['market_open'] = schedule['market_open'].apply(lambda ts: ts.to_pydatetime())
schedule['market_close'] = schedule['market_close'].apply(lambda ts: ts.to_pydatetime())
schedule['market_open'] = schedule['market_open'].dt.tz_convert('America/New_York')
schedule['market_close'] = schedule['market_close'].dt.tz_convert('America/New_York')
assert len(schedule['market_open']) <= 1, "Internal error"
assert len(schedule['market_close']) <= 1, "Internal error"
return schedule['market_open'].iloc[0], schedule['market_close'].iloc[0], len(early)>0
[docs]
@version("0.1")
def full_second_grid_ns(open_dt: dt.datetime, close_dt: dt.datetime) -> pl.Series:
"""
Per-second Polars Series for RTH bins: ``[open_dt, open_dt+1s, ..., close_dt-1s]``.
The grid is end-exclusive so the last bin key is ``close_dt - 1s`` and represents
``[close_dt-1s, close_dt]`` (inclusive close handled by timestamp mapping in the caller).
"""
s = pl.datetime_range(
open_dt,
close_dt,
interval="1s",
time_zone=TZ_NY.key,
eager=True,
closed="left",
)
return s.dt.cast_time_unit("ns").rename("dt_ns")