Merge pull request #90 from Open-Lemma/time_to_expiry

Updated valuation_date and expiry date to accept timestamps, instead of just calendar dates

Author: tyrneh

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to **oipd** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.3]
+### Changed
+- Finalized the maturity contract around three explicit fields:
+    - `time_to_expiry_years` for pricing and calibration
+    - `time_to_expiry_days` for continuous day-based reporting
+    - `calendar_days_to_expiry` for integer calendar-bucket reporting
+
+### Removed
+- Removed the old `days_to_expiry` compatibility path from active APIs.
+
 ## [2.0.2] - 2026-03-06
 ### Added
 - Added stable DataFrame export methods for fitted results:

README.md

@@ -101,7 +101,7 @@ chain, snapshot = sources.fetch_chain(ticker, expiries=single_expiry) # download
 
 # 2. fill in the parameters 
 market = MarketInputs(
-    valuation_date=snapshot.date,               # date on which the options data was downloaded
+    valuation_date=snapshot.asof,               # datetime on which the options data was downloaded
     underlying_price=snapshot.underlying_price, # the price of the underlying stock at the time when the options data was downloaded 
     risk_free_rate=0.04,                        # the risk-free rate of return. Use the US Fed or Treasury yields that are closest to the horizon of the expiry date
 )
@@ -141,7 +141,7 @@ chain_surface, snapshot_surface = sources.fetch_chain(
 
 # 2. fill in the parameters
 surface_market = MarketInputs(
-    valuation_date=snapshot_surface.date,               # date on which the options data was downloaded
+    valuation_date=snapshot_surface.asof,               # datetime on which the options data was downloaded
     underlying_price=snapshot_surface.underlying_price, # price of the underlying stock at download time
     risk_free_rate=0.04,                                # risk-free rate for the horizon
 )
@@ -154,9 +154,9 @@ surface.plot_fan() # Plot a fan chart of price probability over time
 plt.show()
 
 # 5. query at arbitrary maturities directly from ProbSurface
-pdf_45d = surface.pdf(100, t=45/365)       # density at K=100, 45 days
-cdf_45d = surface.cdf(100, t="2025-02-15") # equivalent date-style maturity input
-q50_45d = surface.quantile(0.50, t=45/365) # median at 45 days
+pdf_45d = surface.pdf(100, t=45/365)                      # density at K=100, 45.0 ACT/365 days from valuation_date
+cdf_intraday = surface.cdf(100, t="2025-02-15 09:30:00")  # example timestamp-style maturity input
+q50_45d = surface.quantile(0.50, t=45/365)                # median at 45 days
 
 # 6. "slice" the surface to get a ProbCurve, and query its statistical properties in the same manner as in example A 
 surface.expiries                                  # list all the expiry dates that were captured

docs/3_user-guide.md

@@ -97,14 +97,57 @@ from oipd import MarketInputs
 
 market = MarketInputs(
     risk_free_rate=0.04,
-    valuation_date=snapshot.date,              # or a fixed date
+    valuation_date=snapshot.asof,              # recommended for intraday precision
     underlying_price=snapshot.underlying_price, # set explicitly if snapshot is unavailable
     # optional:
     # risk_free_rate_mode="annualized",  # default
     # dividend_yield=0.01,
 )
 ```
 
+`valuation_date` accepts both plain dates and full datetimes. Date-only values
+remain fully supported, and full datetimes (for example `snapshot.asof`) should
+be preferred when intraday precision matters.
+
+Market-object contract:
+
+- `valuation_date` remains the public field name and stores the canonical
+  normalized timestamp.
+- `valuation_calendar_date` is the explicit date-only convenience view.
+- `valuation_timestamp` remains as a temporary compatibility alias to the same
+  canonical timestamp value.
+
+The option maturity field remains `expiry`. OIPD keeps `valuation_date` as the
+public input name for backwards compatibility, but internally it resolves both
+`valuation_date` and `expiry` to full timestamps before computing maturity.
+That means exact `time_to_expiry_years` is now the source-of-truth input for
+pricing, calibration, and probability calculations. Reporting in day units now
+uses explicit `time_to_expiry_days`, while `calendar_days_to_expiry` is the
+explicit integer calendar bucket.
+
+Maturity contract:
+
+- `oipd.core.maturity` is the canonical home of maturity logic.
+- `time_to_expiry_years` is the pricing truth.
+- `time_to_expiry_days` is the continuous reporting truth.
+- `calendar_days_to_expiry` is the integer calendar bucket.
+
+Migration note:
+
+- replace old `days_to_expiry` inputs with `time_to_expiry_years` for pricing
+  or `time_to_expiry_days` for reporting
+- replace old `days_to_expiry` metadata reads with
+  `calendar_days_to_expiry` if you intended integer calendar-bucket semantics
+
+If you use explicit dividends in the Black-Scholes path, `dividend_schedule`
+supports both date-only and timestamp-style `ex_date` values. Same-day timing
+matters: an ex-dividend timestamp after `valuation_date` is included in pricing,
+while one before `valuation_date` is excluded. Date-only dividend rows keep the
+current midnight semantics for backwards compatibility.
+
+Timezone display redesign is still out of scope for this cycle. Intraday
+arithmetic is supported, but timezone-aware display semantics are unchanged.
+
 ### 2.3 Fit single-expiry (`VolCurve`) or multi-expiry (`VolSurface`)
 
 Single-expiry example:
@@ -143,6 +186,12 @@ Both surface objects support *slicing*:
 
 After slicing, you can use the same methods you would use on regular curve objects (`implied_vol`, `price`, `greeks`, `iv_results` for volatility curves; `pdf`, `prob_below`, `quantile`, `density_results`, `plot` for probability curves).
 
+When `expiry` or `valuation_date` includes a non-midnight timestamp, OIPD
+preserves that intraday precision through surface queries and will show the
+time-of-day in labels/plots where relevant. Midnight timestamps continue to
+render as date-only labels, so older date-based workflows remain visually
+stable.
+
 ```python
 # volatility surface -> volatility curve snapshot
 vol_curve_slice = vol_surface.slice("2026-01-16")
@@ -173,7 +222,7 @@ p_below_240 = prob_curve_slice.prob_below(240)
 | **Expiries** | `expiries` (1-tuple) | Single expiry date. | `expiries` (list) | List of fitted expiry dates. |
 | **Distributions** | `implied_distribution()` | Get `ProbCurve` (RND). | `implied_distribution()` | Get `ProbSurface` (RND Surface). |
 | **Visualization (2D curve)** | `plot()` | Plot fitted smile vs market. | `plot()` | Overlayed IV smiles. |
-| **Visualization (3D surface)** | | | `plot_3d()` | Isometric 3D volatility surface. |
+| **Visualization (3D surface)** | | | `plot_3d()` | Isometric 3D volatility surface. `expiry_range` accepts date-like bounds and is converted to continuous `time_to_expiry_days` internally. |
 | **Term Structure** | | | `plot_term_structure()` | Interpolated ATM-forward IV term structure vs days to expiry. |
 
 ### Probability API Methods Comparison

docs/4_examples.md

@@ -10,3 +10,36 @@ The notebooks below mirror the workflows in the User Guide.
 - [`examples/quickstart_yfinance.ipynb`](https://github.com/Open-Lemma/options-implied-probability/blob/main/examples/quickstart_yfinance.ipynb): live-data probability workflow (vendor fetch).
 - [`examples/quickstart_VolCurve.ipynb`](https://github.com/Open-Lemma/options-implied-probability/blob/main/examples/quickstart_VolCurve.ipynb): single-expiry volatility workflow.
 - [`examples/quickstart_VolSurface.ipynb`](https://github.com/Open-Lemma/options-implied-probability/blob/main/examples/quickstart_VolSurface.ipynb): multi-expiry surface workflow.
+
+`MarketInputs.valuation_date` accepts both dates and datetimes. For intraday
+precision when using vendor data, prefer `snapshot.asof`.
+
+Object-model contract used throughout the examples:
+
+- `valuation_date` remains the public field name and stores the canonical
+  normalized timestamp.
+- `valuation_calendar_date` is the explicit date-only convenience view.
+- `valuation_timestamp` remains as a temporary compatibility alias to the same
+  canonical timestamp value.
+
+Across the examples, the canonical maturity field is `expiry`. Exact
+`time_to_expiry_years` is used internally for pricing and probability
+calculations. Reporting in day units uses explicit `time_to_expiry_days`,
+while `calendar_days_to_expiry` is the explicit integer calendar bucket. If
+you pass intraday timestamps, plots will surface that time-of-day where it
+matters.
+
+Developer note:
+
+- `oipd.core.maturity` is the canonical home of maturity logic.
+
+Migration note:
+
+- old `days_to_expiry` inputs should move to `time_to_expiry_years` for
+  pricing or `time_to_expiry_days` for reporting
+- old `days_to_expiry` metadata reads should move to
+  `calendar_days_to_expiry` if integer calendar-bucket semantics were intended
+
+If you provide a Black-Scholes `dividend_schedule`, its `ex_date` column can
+also be date-only or full timestamp values. Same-day timestamp ordering matters
+for pricing. Timezone display redesign remains out of scope for this cycle.

examples/quickstart_VolCurve.ipynb

@@ -28,7 +28,6 @@
 )
 from oipd.core.data_processing import filter_stale_options, select_price_column
 
-
 _BASE_EXPORTS = [
     "calculate_cdf_from_pdf",
     "calculate_quartiles",

examples/quickstart_VolSurface.ipynb

@@ -1,8 +1,7 @@
-"""Data preprocessing scaffolding package.
+"""Convenience namespace for data-processing helpers.
 
-This namespace will eventually host the refactored preprocessing helpers.
-While the migration is in flight, it simply re-exports the legacy functions
-so early adopters can rely on the new module paths without breaking.
+This package primarily re-exports the preprocessing functions implemented in
+its submodules so callers can import them from one stable package path.
 """
 
 from . import dividends, iv, moneyness, parity, selection, validation  # noqa: F401

examples/quickstart_yfinance.ipynb

@@ -9,7 +9,6 @@
 from scipy.optimize import brentq
 
 from oipd.core.errors import CalculationError
-from oipd.core.utils import convert_days_to_years
 from oipd.core.vol_surface_fitting import VolCurve, fit_surface
 from oipd.pricing.black76 import black76_call_price as _b76_price
 from oipd.pricing.black_scholes import (
@@ -18,11 +17,37 @@
 )
 
 
+def _resolve_time_to_expiry_years(
+    *,
+    time_to_expiry_years: Optional[float],
+) -> float:
+    """Validate one explicit year-fraction maturity value.
+
+    Args:
+        time_to_expiry_years: Canonical year-fraction maturity.
+
+    Returns:
+        float: Finite maturity in year fractions.
+
+    Raises:
+        ValueError: If no maturity is provided or the resolved value is non-finite.
+    """
+    if time_to_expiry_years is None:
+        raise ValueError("compute_iv requires time_to_expiry_years.")
+
+    years_to_expiry = float(time_to_expiry_years)
+
+    if not np.isfinite(years_to_expiry):
+        raise ValueError("time_to_expiry_years must be finite for IV extraction.")
+
+    return years_to_expiry
+
+
 def compute_iv(
     options_data: pd.DataFrame,
     underlying_price: float,
     *,
-    days_to_expiry: int,
+    time_to_expiry_years: Optional[float] = None,
     risk_free_rate: float,
     solver_method: Literal["newton", "brent"],
     pricing_engine: Literal["black76", "bs"],
@@ -32,14 +57,26 @@ def compute_iv(
 
     Returns a copy of ``options_data`` with an added ``iv`` column and rows where
     IV could not be solved (NaN) removed.
+
+    Args:
+        options_data: Option rows with ``price`` and ``strike``.
+        underlying_price: Spot or forward input used by the pricing engine.
+        time_to_expiry_years: Exact year-fraction maturity input.
+        risk_free_rate: Continuously compounded risk-free rate for pricing.
+        solver_method: BS solver choice when ``pricing_engine == "bs"``.
+        pricing_engine: ``"black76"`` or ``"bs"``.
+        dividend_yield: Continuous dividend yield for BS pricing.
     """
 
     if underlying_price is None:
         raise ValueError(
             "Effective underlying/forward price is required for IV extraction"
         )
 
-    years_to_expiry = convert_days_to_years(days_to_expiry)
+    years_to_expiry = _resolve_time_to_expiry_years(
+        time_to_expiry_years=time_to_expiry_years,
+    )
+
     prices_arr = options_data["price"].to_numpy(dtype=float)
     strikes_arr = options_data["strike"].to_numpy(dtype=float)