option-chain-analytics 2.0.0__py3-none-any.whl

option_chain_analytics/__init__.py

@@ -0,0 +1,56 @@
+
+"""Point-in-time option-chain containers and reconstruction analytics."""
+
+from option_chain_analytics.chain_loader_from_ts import (
+    create_chain_from_from_options_dfs,
+    create_chain_timeseries,
+    generate_atm_vols_skew,
+    generate_vol_delta_ts,
+)
+from option_chain_analytics.chain_ts import FuturesChainTs, OptionsDataDFs
+from option_chain_analytics.config import (
+    NearestStrikeOnGrid,
+    StrikeSelection,
+    compute_time_to_maturity,
+    mat_to_timestamp,
+)
+from option_chain_analytics.data.simulated import generate_simulated_options_data
+from option_chain_analytics.option_chain import (
+    ExpirySlice,
+    SliceColumn,
+    SlicesChain,
+    get_contract_execution_price,
+)
+from option_chain_analytics.ts_loaders import DataSource, ts_data_loader_wrapper
+from option_chain_analytics.utils.portfolio_payoff import (
+    compute_option_portfolio_dt,
+    compute_portfolio_payoff,
+)
+from option_chain_analytics.visuals.chain_report import run_chain_report
+from option_chain_analytics.visuals.slices import plot_slice_open_interest, plot_slice_vols
+
+__all__ = [
+    'DataSource',
+    'ExpirySlice',
+    'FuturesChainTs',
+    'NearestStrikeOnGrid',
+    'OptionsDataDFs',
+    'SliceColumn',
+    'SlicesChain',
+    'StrikeSelection',
+    'compute_option_portfolio_dt',
+    'compute_portfolio_payoff',
+    'compute_time_to_maturity',
+    'create_chain_from_from_options_dfs',
+    'create_chain_timeseries',
+    'generate_atm_vols_skew',
+    'generate_simulated_options_data',
+    'generate_vol_delta_ts',
+    'get_contract_execution_price',
+    'mat_to_timestamp',
+    'plot_slice_open_interest',
+    'plot_slice_vols',
+    'run_chain_report',
+    'ts_data_loader_wrapper',
+]
+

option_chain_analytics/chain_loader_from_ts.py

@@ -0,0 +1,239 @@
+"""
+create chain data object with options using time series options data in OptionsDataDFs
+"""
+# package
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import qis
+from qis import TimePeriod, timer
+from qis.utils.np_ops import np_nonan_weighted_avg
+
+from option_chain_analytics.chain_ts import OptionsDataDFs
+
+# analytics
+from option_chain_analytics.option_chain import ExpirySlice, SliceColumn, SlicesChain, UnderlyingColumn
+
+
+# @timer
+def create_chain_from_from_options_dfs(options_data_dfs: OptionsDataDFs,
+                                       value_time: pd.Timestamp,
+                                       ) -> Optional[SlicesChain]:
+    """
+    create chain of slices for options_data_dfs
+    """
+    options_df = options_data_dfs.get_time_slice(timestamp=value_time)
+
+    if not options_df.empty:
+        # options_df[SliceColumn.CONTRACT.value] = options_df.index.to_list()
+        mat_slice = options_df.groupby(SliceColumn.MATURITY_ID.value)
+        expiry_slices, undelying_datas = {}, {}
+        for mat, df in mat_slice:
+            if np.any(df[SliceColumn.OPEN_INTEREST].isna() == False):
+                # forward is contract weighted avs
+                forward = np_nonan_weighted_avg(a=df[SliceColumn.FORWARD_PRICE.value],
+                                                weights=df[SliceColumn.OPEN_INTEREST])
+            else:
+                # forward is contract weighted avs
+                forward = np.nanmean(df[SliceColumn.FORWARD_PRICE.value])
+            if not np.isnan(forward):
+                undelying_data = {UnderlyingColumn.EXPIRY_ID: str(mat),
+                                  UnderlyingColumn.VALUE_TIME: value_time,
+                                  UnderlyingColumn.EXPIRY: df[SliceColumn.EXPIRY].iloc[0],
+                                  UnderlyingColumn.SPOT_PRICE: forward,  # to do
+                                  UnderlyingColumn.UNDERLYING_INDEX: str(mat),  # to do
+                                  UnderlyingColumn.FORWARD_PRICE: forward,  # to do
+                                  UnderlyingColumn.IR_RATE: 0.0,
+                                  UnderlyingColumn.TTM: df[SliceColumn.TTM].iloc[0]}
+                undelying_data = pd.Series(undelying_data)
+                expiry_slices[str(mat)] = ExpirySlice(options_df=df, undelying_data=undelying_data)
+                undelying_datas[str(mat)] = undelying_data
+        undelying_df = pd.DataFrame.from_dict(undelying_datas, orient='index')
+        chain = SlicesChain(options_df=options_df,#.set_index(SliceColumn.CONTRACT),
+                            undelying_df=undelying_df,
+                            expiry_slices=expiry_slices,
+                            value_time=value_time)
+    else:
+        chain = None
+    return chain
+
+
+@timer
+def create_chain_timeseries(options_data_dfs: OptionsDataDFs,
+                            dates_schedule: pd.DatetimeIndex = None,
+                            time_period: TimePeriod = None,
+                            freq: str = 'W-FRI',
+                            hour_offset: int = 8
+                            ) -> Dict[pd.Timestamp, SlicesChain]:
+    """
+    create dictionary of timestamp and corresponding slices
+    """
+    if dates_schedule is None:
+        if time_period is None:
+            raise ValueError(f"time_period={time_period} must be non Nons")
+        dates_schedule = qis.generate_dates_schedule(time_period=time_period,
+                                                     freq=freq,
+                                                     hour_offset=hour_offset)
+
+    chain_data = {}
+    for timestamp in dates_schedule:
+        chain = create_chain_from_from_options_dfs(options_data_dfs=options_data_dfs, value_time=timestamp)
+        if chain is not None:
+            chain_data[timestamp] = chain
+    return chain_data
+
+
+@timer
+def generate_atm_vols_skew(options_data_dfs: OptionsDataDFs,
+                           time_period: TimePeriod = None,
+                           freq: str = 'D',
+                           hour_offset: int = 8,
+                           days_before_roll: int = 7
+                           ) -> Tuple[pd.Series, pd.Series]:
+
+    """
+    fetch time series of atm vols and skew from  options_data_dfs
+    """
+    if time_period is None:
+        time_period = options_data_dfs.get_start_end_date()
+
+    chain_data = create_chain_timeseries(options_data_dfs=options_data_dfs,
+                                         time_period=time_period,
+                                         freq=freq,
+                                         hour_offset=hour_offset)
+    vols = {}
+    skews = {}
+    for date, chain in chain_data.items():
+        next_date = date + pd.DateOffset(days=days_before_roll)
+        slice_id = chain.get_next_slice_after_date(mat_date=next_date)
+        vols[date] = chain.get_atm_vol(slice_id=slice_id)
+        skews[date] = chain.get_skew(slice_id=slice_id)
+    vols = pd.Series(vols, name='atm_vol')
+    skews = pd.Series(skews, name='skew')
+    return vols, skews
+
+
+@timer
+def generate_vol_delta_ts(options_data_dfs: OptionsDataDFs,
+                          days_map: Dict[str, int] = None,
+                          deltas: List[float] = (-0.10, -0.25, 0.50, 0.25, 0.10),
+                          freq: str = 'D',
+                          hour_offset: Optional[int] = 8,
+                          time_period: TimePeriod = None
+                          ) -> Tuple[pd.DataFrame, ...]:
+    """
+    return dataframes of vols with columns = deltas and index = dates
+    """
+    if time_period is None:
+        time_period = options_data_dfs.get_start_end_date()
+
+    chain_data = create_chain_timeseries(options_data_dfs=options_data_dfs,
+                                         time_period=time_period,
+                                         freq=freq,
+                                         hour_offset=hour_offset)
+    if days_map is None:
+        days_map = {'1d': 1, '2d': 2, '1w': 7, '2w': 10, '1m': 28, '2m': 56, '3m': 84, '2Q': 168}
+
+    is_add_tenor_to_delta_name = False if len(days_map.keys()) == 1 else True
+    vols, strikes, options, underlying_prices = {}, {}, {}, {}
+    for date, chain in chain_data.items():
+        delta_vol_matrix = chain.generate_delta_vol_matrix(value_time=date, days_map=days_map, deltas=deltas)
+        if delta_vol_matrix is not None:
+            vols_, strikes_, options_, index_prices_ = delta_vol_matrix.get_melted_matrix(is_add_tenor_to_delta_name=is_add_tenor_to_delta_name)
+            vols[date] = vols_['vols'].rename(date)
+            strikes[date] = strikes_['strikes'].rename(date)
+            options[date] = options_['options'].rename(date)
+            underlying_prices[date] = index_prices_['underlying_prices_matrix'].rename(date)
+    vols = pd.DataFrame.from_dict(vols, orient='index')
+    strikes = pd.DataFrame.from_dict(strikes, orient='index')
+    options = pd.DataFrame.from_dict(options, orient='index')
+    underlying_prices = pd.DataFrame.from_dict(underlying_prices, orient='index')
+    return vols, strikes, options, underlying_prices
+
+
+class UnitTests(Enum):
+    CREATE_CHAIN_AT_TS = 1
+    CREATE_TS_CHAIN_DATA = 2
+    CREATE_WEEKLY_ROLLS = 3
+    GENERATE_VOL_DELTA_TS = 4
+
+
+def run_unit_test(unit_test: UnitTests):
+
+    from option_chain_analytics.ts_loaders import DataSource, ts_data_loader_wrapper
+
+    ticker = 'ETH'
+    options_data_dfs = OptionsDataDFs(**ts_data_loader_wrapper(ticker=ticker, data_source=DataSource.TARDIS_LOCAL))
+
+    if unit_test == UnitTests.CREATE_CHAIN_AT_TS:
+        date = pd.Timestamp('2022-09-19 08:00:00+00:00')
+        chain = create_chain_from_from_options_dfs(options_data_dfs=options_data_dfs, value_time=date)
+        chain.save_joint_slices(file_name=f"{ticker}_{date.strftime('%Y%m%d_%H_%M_%S')}")
+
+        next_date = date+pd.DateOffset(days=30)
+        slice_id = chain.get_next_slice_after_date(mat_date=next_date)
+        print(f"{date}: {slice_id}")
+        print(f"{chain.get_atm_put_id(slice_id=slice_id)}, {chain.get_atm_call_id(slice_id=slice_id)}")
+        print(f"{chain.get_put_delta_option_id(slice_id=slice_id, delta=-0.25)}")
+        print(f"{chain.get_call_delta_option_id(slice_id=slice_id, delta=0.25)}")
+
+        # days_map = {'1d': 1, '2d': 2, '1w': 7, '2w': 14, '1m': 30, '2m': 60, '3m': 90, '2Q': 120,  '3Q': 180}
+        # days_map = {'1d': 1, '2d': 2, '1w': 7, '2w': 14, '1m': 30, '2m': 60, '3m': 90, '2Q': 120}
+        days_map = {'2d': 2, '1w': 7, '2w': 14, '1m': 30, '2m': 60, '3m': 90}
+        delta_vol_matrix = chain.generate_delta_vol_matrix(value_time=date, days_map=days_map)
+        delta_vol_matrix.print()
+
+        vols, strikes, options, index_prices = delta_vol_matrix.get_melted_matrix()
+        print(vols)
+        print(strikes)
+        delta_vol_matrix.plot_vol_in_strike()
+
+    elif unit_test == UnitTests.CREATE_TS_CHAIN_DATA:
+        chain_data = create_chain_timeseries(options_data_dfs=options_data_dfs,
+                                             time_period=options_data_dfs.get_start_end_date(),
+                                             freq='W-FRI',
+                                             hour_offset=8)
+        for key, chain in chain_data.items():
+            print(f"{key}, {chain.expiry_slices.keys()}")
+
+    elif unit_test == UnitTests.CREATE_WEEKLY_ROLLS:
+        weekly_fridays_rolls = qis.generate_dates_schedule(TimePeriod(pd.Timestamp('2022-05-06 00:00:00+00:00'),
+                                                                      qis.get_current_time_with_tz(tz='UTC', days_offset=7)),
+                                                           freq='W-FRI',
+                                                           hour_offset=8)
+        weekly_fridays_rolls = weekly_fridays_rolls[:-2]
+        print(weekly_fridays_rolls)
+
+        chain_data = create_chain_timeseries(options_data_dfs=options_data_dfs,
+                                             dates_schedule=weekly_fridays_rolls[:-1])
+
+        for date, next_date in zip(weekly_fridays_rolls[:-1], weekly_fridays_rolls[1:]):
+            print(f"{date}: {chain_data[date].get_next_slice_after_date(mat_date=next_date)}, "
+                  f"{chain_data[date].get_atm_put_id(mat_date=next_date)}")
+
+    elif unit_test == UnitTests.GENERATE_VOL_DELTA_TS:
+        time_period = TimePeriod('2023-01-01 00:00:00+00:00', '2023-07-14 00:00:00+00:00', tz='UTC')
+        vols, strikes, options, index_prices = generate_vol_delta_ts(options_data_dfs=options_data_dfs,
+                                                                     days_map={'1w': 7, '1m': 30},
+                                                                     deltas=[-0.10, -0.25, 0.50, 0.25, 0.10],
+                                                                     freq='B',
+                                                                     hour_offset=8,
+                                                                     time_period=time_period)
+        print(vols)
+
+    plt.show()
+
+
+if __name__ == '__main__':
+
+    unit_test = UnitTests.GENERATE_VOL_DELTA_TS
+
+    is_run_all_tests = False
+    if is_run_all_tests:
+        for unit_test in UnitTests:
+            run_unit_test(unit_test=unit_test)
+    else:
+        run_unit_test(unit_test=unit_test)

option_chain_analytics/chain_ts.py

@@ -0,0 +1,248 @@
+"""
+collector of aligned time series data for option
+options data is split in frames
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Literal, Optional, Tuple, Union
+
+import numpy as np
+
+# package
+import pandas as pd
+import qis
+from qis import TimePeriod
+
+# analytics
+from option_chain_analytics.option_chain import SliceColumn
+
+
+@dataclass
+class ChainTs:
+    """
+    df collection for options and futures time series
+    chain_ts must contain SliceColumn.EXCHANGE_TIME.value
+    the most frequent request will be get df[contracts] at given timestamp
+    to expedite request we add groupby[SliceColumn.EXCHANGE_TIME.value]
+    """
+    chain_ts: pd.DataFrame
+    spot_data: pd.DataFrame
+    ticker: str
+
+    def __post_init__(self):
+        self.chain_ts_group_by_time = self.chain_ts.groupby(SliceColumn.EXCHANGE_TIME.value)
+        self.ewm_vol: Optional[pd.Series] = None
+
+    def get_contract_data(self, contact: str) -> pd.DataFrame:
+        df = self.chain_ts.loc[self.chain_ts[SliceColumn.CONTRACT.value] == contact, :]
+        return df
+
+    def print(self):
+        print('chain_ts')
+        print(self.chain_ts)
+        print('spot_data')
+        print(self.spot_data)
+
+    def get_timeindex(self) -> pd.DatetimeIndex:
+        return pd.DatetimeIndex(self.chain_ts_group_by_time.groups.keys())
+
+    def get_start_end_date(self) -> TimePeriod:
+        times = self.get_timeindex()
+        return qis.TimePeriod(times.min(), times.max())
+
+    def get_spot_data(self, time_period: TimePeriod = None) -> pd.DataFrame:
+        df = self.spot_data
+        if time_period is not None:
+            df = time_period.locate(df)
+        return df
+
+    def get_time_slice(self,
+                       timestamp: pd.Timestamp,
+                       contracts: List[str] = None
+                       ) -> pd.DataFrame:
+        """
+         get non-nan time slice from series
+         return is df(index=contracts, colums=[mark_rpice, mark_vol,...])
+         """
+        if timestamp in self.chain_ts_group_by_time.groups:
+            df = self.chain_ts_group_by_time.get_group(timestamp)
+            df = df.set_index(SliceColumn.CONTRACT.value, drop=False)
+            df.index.name = 'contract'
+
+            # remove dublicates per timestamp
+            df = df.loc[~df.index.duplicated(keep='first')]
+
+            if contracts is not None:
+                df = df.iloc[np.in1d(df.index, contracts, assume_unique=False), :]
+        else:
+            # print(f"no slice data for {timestamp}")
+            df = pd.DataFrame()
+        return df
+
+    def get_spot_price(self,
+                       value_time: pd.Timestamp = None,
+                       index: Union[pd.DatetimeIndex, pd.Index] = None
+                       ) -> Union[float, pd.Series]:
+        value = self.spot_data['close'].rename(self.ticker)
+        if value_time is not None:
+            if value_time in value.index:
+                value = value[value_time]
+            else:
+                raise KeyError(f"in get_spot_price {value_time} not in {value.index}")
+        elif index is not None:
+            value = value.reindex(index=index, method='ffill').ffill()
+        return value
+
+    def get_spot_and_perp_price(self,
+                                value_time: pd.Timestamp = None,
+                                index: Union[pd.DatetimeIndex, pd.Index] = None
+                                ) -> Tuple[Union[float, pd.Series], Union[float, pd.Series]]:
+        """
+        specific for cryptocurrency data where both spot and perp prices are used:
+        spot_price is the spot price
+        perp_mark_price is the mark price of the futures
+        """
+        value = self.spot_data[['close', 'mark_price']]
+        if value_time is not None:
+            if value_time in value.index:
+                value = value[value_time]
+            else:
+                raise KeyError(f"in get_spot_price {value_time} not in {value.index}")
+        elif index is not None:
+            value = value.reindex(index=index, method='ffill').ffill()
+
+        spot_price = value['close'].rename(self.ticker)
+        perp_price = value['mark_price'].rename(self.ticker)
+
+        return spot_price, perp_price
+
+    def get_funding_rate(self,
+                         freq: Optional[Literal['h', 'D']] = 'h',
+                         index: Union[pd.DatetimeIndex, pd.Index] = None,
+                         is_rescale_to_one_hour: bool = True,
+                         time_period: TimePeriod = None
+                         ) -> pd.Series:
+        """
+        deribit reports hourly funding rate extrapolated to 8h interval
+        for h freq we resample at 8h and return last
+        for d freq we resample at 8h and then return the sum
+        if freq is Non we return actual rate, it needs to be divided by 8 for comps H or D frequences with is_rescale_to_one_hour = True
+        """
+        funding_rate_1h = self.spot_data['funding_rate'].rename(self.ticker)
+        if freq is not None:
+            funding_rate_8h = funding_rate_1h.resample('8h').mean()
+            if freq == 'h':
+                funding_rate = funding_rate_8h
+                if index is not None:
+                    funding_rate = funding_rate.reindex(index=index).fillna(0.0)
+            elif freq == 'D':
+                funding_rate = funding_rate_8h.resample('D').sum()
+                if index is not None:
+                    funding_rate = funding_rate.reindex(index=index, method='ffill').fillna(0.0)
+            else:
+                raise NotImplementedError(f"freq={freq}")
+        else:
+            # funding_rate = funding_rate_1h.cumsum(0).reindex(index=index, method='ffill').diff(1)
+            funding_rate = funding_rate_1h
+            if is_rescale_to_one_hour:
+                funding_rate = funding_rate / 8.0  # deribit computes funding based on 8h frequency
+
+        if time_period is not None:
+            funding_rate = time_period.locate(funding_rate)
+
+        return funding_rate
+
+    def get_ewm_vol(self,
+                    value_time: pd.Timestamp,
+                    span: float = 168  # =7*24
+                    ) -> float:
+        if self.ewm_vol is None:
+            returns = np.log(self.spot_data['close']).diff()
+            self.ewm_vol = qis.compute_ewm_vol(data=returns, span=span, af=24.0 * 365.0)
+        idx = self.ewm_vol.index.get_indexer([value_time], method='ffill')
+        vol = self.ewm_vol.iloc[idx].to_numpy()[0]
+        return vol
+
+    @classmethod
+    def reduce(cls, obj: ChainTs, contracts: List[str]) -> ChainTs:
+        """
+        reduce chain to contain only given contracts
+        """
+        chain_ts = obj.chain_ts
+        return ChainTs(chain_ts=chain_ts.loc[chain_ts[SliceColumn.CONTRACT.value].isin(contracts), :],
+                       spot_data=obj.spot_data,
+                       ticker=obj.ticker)
+
+
+@dataclass
+class FuturesChainTs(ChainTs):
+    """
+    implementation of futures time series data
+    """
+    class FuturesDataColumns(str, Enum):
+        MARK_PRICE = 'mark_price'
+        OPEN = 'open'
+        HIGH = 'high'
+        LOW = 'low'
+        CLOSE = 'close'
+        VOLUME = 'usd_volume'
+        VOLUME_CONTRACTS = 'contract_count'
+        OI_VOLUME = 'oi_value_usd'
+        OI_CONTRACTS = 'oi_contract_count'
+
+
+@dataclass
+class OptionsDataDFs(ChainTs):
+    """
+    implementation of options time series data
+    fields of SliceColumn are contained in data_dict
+    all info (maturity, option type, etc is passed inside option data dfs)
+    """
+
+    @classmethod
+    def reduce(cls, obj: OptionsDataDFs, contracts: List[str]) -> OptionsDataDFs:
+        """
+        reduce chain to contain only given contracts
+        """
+        chain_ts = obj.chain_ts
+        return OptionsDataDFs(chain_ts=chain_ts.loc[chain_ts[SliceColumn.CONTRACT.value].isin(contracts), :],
+                              spot_data=obj.spot_data,
+                              ticker=obj.ticker)
+
+
+class UnitTests(Enum):
+    TEST_CHAIN = 1
+
+
+def run_unit_test(unit_test: UnitTests):
+
+    from option_chain_analytics import local_path as local_path
+
+    if unit_test == UnitTests.TEST_CHAIN:
+        ticker = 'ETH'
+        chain_ts = qis.load_df_from_feather(file_name=f"{ticker}_freq_H",
+                                            index_col=None,
+                                            local_path=f"{local_path.get_resource_path()}\\tardis\\")
+        spot_data = qis.load_df_from_feather(file_name=f"{ticker}-spot",
+                                             local_path=f"{local_path.get_resource_path()}\\deribit\\")
+
+        chain_ts = ChainTs(chain_ts=chain_ts, spot_data=spot_data, ticker=ticker)
+        chain_ts.print()
+        chain_ts.get_start_end_date().print()
+
+        df = chain_ts.get_time_slice(timestamp=pd.Timestamp('2019-04-01 08:00:00+00:00'))
+        print(df)
+
+
+if __name__ == '__main__':
+
+    unit_test = UnitTests.TEST_CHAIN
+
+    is_run_all_tests = False
+    if is_run_all_tests:
+        for unit_test in UnitTests:
+            run_unit_test(unit_test=unit_test)
+    else:
+        run_unit_test(unit_test=unit_test)

option_chain_analytics/config.py

@@ -0,0 +1,83 @@
+"""
+define api and data specific conversions of options and futures tickers
+"""
+from enum import Enum
+from typing import Optional
+
+import pandas as pd
+
+TIME_FMT = '%Y%m%d%H%M%S'
+EXPIRY_DATE_FORMAT = '%d%b%Y'
+SECONDS_PER_DAY = 24*60*60  # hours, minute, seconds
+
+
+class NearestStrikeOnGrid(Enum):
+    """
+    for selection of strikes
+    this specifies nearest strike from the strikes grid, for put ratios must be strictly below or above
+    """
+    NEAREST = 0
+    MAX_OI = 1
+    ABOVE = 2
+    BELOW = 3
+
+
+class StrikeSelection(Enum):
+    # strike selection for a strategy
+    ATM = 1
+    DELTA = 2
+
+
+def compute_time_to_maturity(maturity_time: pd.Timestamp,
+                             value_time: pd.Timestamp,
+                             is_floor_at_zero: bool = True,
+                             af: float = 365
+                             ) -> float:
+    """
+    return annualised difference between mat_date and value_time
+    """
+    ttm = (maturity_time - value_time).total_seconds() / (af*SECONDS_PER_DAY)
+    if is_floor_at_zero and ttm < 0.0:
+        ttm = 0.0
+    return ttm
+
+
+def compute_days_to_maturity(maturity_time: pd.Timestamp,
+                             value_time: pd.Timestamp,
+                             is_floor_at_zero: bool = True,
+                             af: float = 365
+                             ) -> float:
+    """
+    return annualised difference between mat_date and value_time
+    """
+    ttm = (maturity_time - value_time).total_seconds() / (af*SECONDS_PER_DAY)
+    if is_floor_at_zero and ttm < 0.0:
+        ttm = 0.0
+    return ttm
+
+
+def mat_to_timestamp(mat: str,
+                     date_format: Optional[str] = None,  # deribit = "%d%b%y"
+                     hour_offset: Optional[int] = 8
+                     ) -> pd.Timestamp:
+    """
+    from maturity string get timestamp
+    """
+    mat = pd.Timestamp(pd.to_datetime(mat, format=date_format), tz='UTC')
+    if hour_offset is not None:
+        mat = mat + pd.to_timedelta(hour_offset, unit='h')
+    return mat
+
+
+def get_file_name(ticker: str, freq: Optional[str], hour_offset: Optional[int]) -> str:
+    if freq is not None:
+        if freq in ['h', 'H']:
+            file_name = f"{ticker}_freq_{freq}"
+        else:
+            if hour_offset is not None:
+                file_name = f"{ticker}_freq_{freq}_hour_{hour_offset}"
+            else:
+                file_name = f"{ticker}_freq_{freq}"
+    else:
+        file_name = ticker
+    return file_name

option_chain_analytics/data/__init__.py

@@ -0,0 +1,27 @@
+"""Data generators and optional provider integrations.
+
+Provider modules are imported lazily so the deterministic simulation path does
+not require credentials or provider-specific dependencies.
+"""
+
+from typing import Any
+
+from option_chain_analytics.data.simulated import generate_simulated_options_data
+
+__all__ = [
+    'fetch_yahoo_options_live_data',
+    'generate_simulated_options_data',
+    'update_deribit_options_data',
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == 'update_deribit_options_data':
+        from option_chain_analytics.data.deribit import update_deribit_options_data
+
+        return update_deribit_options_data
+    if name == 'fetch_yahoo_options_live_data':
+        from option_chain_analytics.data.yahoo import fetch_yahoo_options_live_data
+
+        return fetch_yahoo_options_live_data
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')