quantdata.massive.options.contracts#
Managing contract information per underyling.
The main functions in this module are:
* filter_contracts
* filter_contracts_between
Each retrieves, filters, and caches contrats for a given underlying.
..
!! processed by numpydoc !!
- class quantdata.massive.options.contracts.REJECTED[source]#
Bases:
objectReasons why a contract was rejected from the final list
.. !! processed by numpydoc !!- USED = 0#
- EXPIRY = 1#
- MONEYNESS = 2#
- VOLUME = 3#
- PREV_VOLUME_MISSING = -1#
- PREV_NO_QUOTES_OR_TRADES = -2#
- NO_TODAY_QUOTES = -3#
- NO_TODAY_TRADES = -4#
- quantdata.massive.options.contracts.SCHEMA = {'approx_cash_vol_prev_k': Float32, 'approx_cash_vol_today_k': Float32, 'cfi': String, 'contract_type': String, 'date': Date, 'days_to_exp': Int16, 'exercise_style': String, 'exp_date': Date, 'has_prev_quotes': Boolean, 'has_prev_trades': Boolean, 'has_today_quotes': Boolean, 'has_today_trades': Boolean, 'nms': Float32, 'nms5': Float32, 'opt_close': Float32, 'opt_open': Float32, 'opt_prev_close': Float32, 'opt_prev_open': Float32, 'prev_bus_date': Date, 'primary_exchange': String, 'reject_code': Int8, 'shares_per_contract': Int32, 'spot_adj_close': Float32, 'spot_adj_prev_close': Float32, 'spot_close': Float32, 'spot_open': Float32, 'spot_prev_close': Float32, 'spot_ref_prev_close': Float32, 'strike_price': Float32, 'ticker': String, 'underlying_ticker': String}#
Schema of the polars.DataFrame returned by filter_contracts and filter_contracts_between.
See also massive documentation (https://massive.com/docs/rest/options/contracts/contract-overview) for the original field definitions. .. !! processed by numpydoc !!
- class quantdata.massive.options.contracts.ContractsFilter(max_dte=7, max_mns=2.0, max_mns5=None, min_opt_vol_k=0.0)[source]#
Bases:
objectConfiguration on to filter the options retrieved via filter_contracts and filter_contracts_between.
.. !! processed by numpydoc !!- max_mns: float | None = 2.0#
Maximum absolute normalized strike, i.e. $ log(K/S_mathrm{prev})*sqrt((1+e)/(T+e)/0.1 ~ log(K/S_mathrm{prev})/(0.1*sqrt(T)) $, where $S_mathrm{prev}$ is the previous close adjusted for stock splits and dividends to match today’s unadjusted price, and T is time to expiry in years. Here $e$ is one hour. This is a measure of moneyness that accounts for both distance to the money and time to expiry.
.. !! processed by numpydoc !!
- max_mns5: float | None = None#
Maximum normalized strike, i.e. $ log(K/S_mathrm{prev})*sqrt((1+g)/(T+g)/0.1 $, where $S_mathrm{prev}$ is the previous close adjusted for stock splits and dividends to match today’s unadjusted price, and T is time to expiry in years. Here $g$ is five days which tends to make this measure more robust than NMS alone. This is a measure of moneyness that accounts for both distance to the money and time to expiry.
.. !! processed by numpydoc !!
- quantdata.massive.options.contracts.filter_contracts(underlying, d, contracts_filter, exclude_half_days, *, drop_no_trades_today=False, pool_config=<cdxcore.jcpool.JCPoolConfig object>, verbose=<cdxcore.verbose.Context object>)[source]#
Filters and processes option contracts for a given underlying on a given date.
Applies filtering rules based on expiry, moneyness, and trading volume, and returns a data frame with enriched contract information including reject codes and calculated metrics. This function also computes a correctly cash-valued adjused spot_ref_prev_close which can be used as non-forward looking normalizer for all cash values "today". Filtering Rules implemented in ContractsFilter: 1. Expiry filter: business days to expiry in [0, contracts_filter.max_dte]. 2. Moneyness filter: $\log(K/S_{prev})/\sqrt{T}/0.1$ <= contracts_filter.max_mns where T = days_to_exp / DAYS_PER_YEAR. 3. Volume filter (previous day): approx_cash_vol_prev_k >= contracts_filter.min_opt_vol_k (in 1000$). The returned polars.DataFrame includes all contracts, with a "reject_code" column indicating the reason for rejection based on the above rules. To obtain the filtered options, use:: from quantdata.massive.options.contracts import filter_contracts, ContractsFilter, REJECTED df = filter_contracts(...).filter(pl.col("reject_code") == REJECTED.USED) **Performance Warning** This function downloads the adjusted and unadjusted daily data, and trade and quote activity for each option. That is much slower than just obtaining the list of contracts. :param underlying: The underlying ticker symbol. :type underlying: :sphinx_autodoc_typehints_type:\:py\:class\:\str\ :param d: The date for which to retrieve contracts. :type d: :sphinx_autodoc_typehints_type:\:py\:class\:\\~datetime.date\ :param contracts_filter: Filter configuration specifying max_dte, max_mns, and min_opt_vol_k thresholds. :type contracts_filter: :sphinx_autodoc_typehints_type:\:py\:class\:\\~quantdata.massive.options.contracts.ContractsFilter\ :param exclude_half_days: If True, exclude half trading days when calculating business days to expiry. This parameter is not contained in ContractsFilter because it is structural to the model development. :type exclude_half_days: :sphinx_autodoc_typehints_type:\:py\:class\:\bool\ :param drop_no_trades_today: If True, drop options which do not trade 'today'. This parameter is not contained in ContractsFilter because it is structural to the model development. In particular, the model logic must be such this feature is not forward-looking (for example by ensuring any model analytics only start once the first trade was observed). :type drop_no_trades_today: :sphinx_autodoc_typehints_type:\:py\:class\:\bool\ :param pool_config: Configuration for thread pool processing. Defaults to PoolConfig(). :type pool_config: :sphinx_autodoc_typehints_type:\:py\:class\:\\~cdxcore.jcpool.JCPoolConfig\ \ \:py\:class\:\\~cdxcore.jcpool.JCPool\ :param verbose: Verbosity context for logging. Defaults to Context.quiet. :type verbose: :sphinx_autodoc_typehints_type:\:py\:class\:\\~cdxcore.verbose.Context\ :returns: **Result** -- Data frame with schema SCHEMA of filtered contracts with added fields: - reject_code (int): Rejection reason code - spot_prev_close (float): Previous close adjusted spot price - nms (float): Scaled moneyness metric using NMS - nms5 (float): Scaled moneyness metric using NMS5 - approx_cash_vol_prev_m (float): Previous day approx cash volume (USD millions) - approx_cash_vol_today_m (float): Today approx cash volume (USD millions) - days_to_exp (int): Business days to expiration - spot_ref_prev_close (float): Previous close adjusted to match today's spot :rtype: polars.DataFrame .. !! processed by numpydoc !!
- quantdata.massive.options.contracts.filter_contracts_between(ticker, date_range, contracts_filter, *, refresh=False, pool_config=<cdxcore.jcpool.JCPoolConfig object>, verbose=<cdxcore.verbose.Context object>)[source]#
Filter option contracts for a given underlying ticker between start and end for a given ticker.
:param ticker: Underlying ticker symbol, e.g. "AAPL" for Apple. :type ticker: :sphinx_autodoc_typehints_type:\:py\:class\:\str\ :param date_range: Date range for which to filter contracts. Only contracts with expiration_date >= date_range.start and expiration_date <= date_range.end are returned. :type date_range: :sphinx_autodoc_typehints_type:\:py\:class\:\\~quantdata.biz\_calendar.DateRange\ :param contracts_filter: Filter parameters for contract filtering. See ContractsFilter for details. :type contracts_filter: :sphinx_autodoc_typehints_type:\:py\:class\:\\~quantdata.massive.options.contracts.ContractsFilter\ :param refresh: If True, refresh data (this will only refresh the top level files, i.e. the files for individual dates, but it will not refresh the cached results of individual contracts). :type refresh: :sphinx_autodoc_typehints_type:\:py\:class\:\bool\ :param pool_config: Configuration for parallel processing. See PoolConfig for details. :type pool_config: :sphinx_autodoc_typehints_type:\:py\:class\:\\~cdxcore.jcpool.JCPoolConfig\ :param verbose: Verbose context for logging. See Context for details. :type verbose: :sphinx_autodoc_typehints_type:\:py\:class\:\\~cdxcore.verbose.Context\ :returns: DataFrame with filtered contracts for each date in the date range. The DataFrame has the same schema as the output of filter_contracts, with an additional column "date" indicating the date for which the contracts were filtered. :rtype: pl.DataFrame .. !! processed by numpydoc !!