ProbCurve

ProbCurve represents the risk-neutral probability distribution implied by a single-expiry option chain. You can build one directly from an option chain, or derive one from a fitted VolCurve when you want to inspect the volatility fit first. You can then query probabilities, moments, and quantiles, export a DataFrame, or render a plot.

from oipd import ProbCurve

Constructors

You normally build a ProbCurve in one of two ways:

Use ProbCurve.from_chain(...) when you want OIPD to fit the volatility smile and derive the probability curve in one step.
Use VolCurve.implied_distribution(...) when you already have a fitted VolCurve and want to reuse it.

`ProbCurve.from_chain`

The one-step constructor. Accepts a single-expiry option chain DataFrame and market inputs, fits an SVI smile, and derives the risk-neutral distribution.

ProbCurve.from_chain(
    chain,
    market,
    column_mapping=None,
    max_staleness_days=3,
    cdf_violation_policy="warn",
)

pd.DataFrame

required

Option chain DataFrame for a single expiry. Must contain an expiry column and at least one supported price column (last_price, or bid/ask).

MarketInputs

required

Market inputs providing the risk-free rate, valuation date, and underlying price.

dict[str, str] | None

default:"None"

Optional mapping in the form {"dataframe_column": "oipd_column"}. For example, {"type": "option_type"} means your DataFrame has a type column and OIPD should treat it as option_type. See Standard columns for the target names.

int

default:"3"

Maximum age of option quotes in calendar days, relative to the valuation date. Rows older than this threshold are filtered out before fitting.

Literal['warn', 'raise']

default:"warn"

Policy for handling CDF monotonicity violations during materialization. "warn" repairs the CDF and records a diagnostic warning; "raise" raises a CalculationError on material violations.

Raises: ValueError if the chain contains multiple expiries. CalculationError if volatility calibration fails.

From a fitted `VolCurve`

If you have already fitted a VolCurve, call implied_distribution() on that object:

from oipd import VolCurve

vol = VolCurve().fit(chain, market)
prob = vol.implied_distribution()

See VolCurve.implied_distribution.

Methods

pdf(price)

Evaluate the Probability Density Function at one or more price levels.

prob.pdf(price)

float | np.ndarray

required

Price level or array of price levels to evaluate.

float | np.ndarray

PDF value(s). Returns a scalar float when price is a scalar, or an ndarray otherwise. Values outside the fitted domain return 0.0.

ProbCurve is also callable: prob(price) is an alias for prob.pdf(price).

prob_below(price)

Probability that the asset price at expiry is strictly below price.

prob.prob_below(price)

float

required

Upper bound price level.

float

P(S < price), interpolated from the CDF. Returns 0.0 below the domain and 1.0 above.

prob_above(price)

Probability that the asset price at expiry is at or above price.

prob.prob_above(price)

float

required

Lower bound price level.

float

P(S >= price). Computed as 1 - prob_below(price).

prob_between(low, high)

Probability that the asset price at expiry falls in the interval [low, high).

prob.prob_between(low, high)

float

required

Lower bound of the interval.

float

required

Upper bound of the interval. Must be greater than or equal to low.

float

P(low <= S < high).

Raises: ValueError if low > high.

mean()

Expected value of the asset price under the fitted PDF.

prob.mean()

float

E[S], computed by numerical integration of price × pdf over the domain.

variance()

Variance of the asset price under the fitted PDF.

prob.variance()

float

Var[S] = E[(S - mean)²].

skew()

Skewness (third standardized moment) of the fitted PDF.

prob.skew()

float

Skew = E[(S - μ)³] / σ³. Negative values indicate a fat left tail, which is typical for equity distributions.

kurtosis()

Excess kurtosis (fourth standardized moment minus 3) of the fitted PDF.

prob.kurtosis()

float

Excess kurtosis = E[(S - μ)⁴] / σ⁴ - 3. Zero implies a normal distribution; positive values indicate fat tails.

quantile(q)

Inverse CDF: returns the price level at which the cumulative probability equals q.

prob.quantile(q)

float

required

Target probability level. Must be in the open interval (0, 1).

float

Price S such that P(Asset < S) = q.

Raises: ValueError if q is not in (0, 1).

density_results(domain, points, full_domain)

Export the fitted distribution as a DataFrame for analysis or custom plotting.

prob.density_results(domain=None, points=200, full_domain=False)

tuple[float, float] | None

default:"None"

Optional explicit export domain as (min_price, max_price). When provided, the native distribution is resampled onto this range. Takes precedence over full_domain.

int

default:"200"

Number of output rows when resampling to a compact or explicit domain. Ignored when full_domain=True and no domain is specified.

bool

default:"False"

When True and domain is not set, returns the full native distribution arrays without resampling.

pd.DataFrame

DataFrame with columns price, pdf, and cdf.

plot(kind, figsize, title, xlim, ylim, points, full_domain)

Render the risk-neutral probability distribution as a matplotlib figure.

prob.plot(
    kind="both",
    figsize=(10, 5),
    title=None,
    xlim=None,
    ylim=None,
    points=800,
    full_domain=False,
)

Literal['pdf', 'cdf', 'both']

default:"both"

Which distribution curve(s) to render.

tuple[float, float]

default:"(10, 5)"

Figure size as (width, height) in inches.

str | None

default:"None"

Custom title. Auto-generated from market metadata when omitted.

tuple[float, float] | None

default:"None"

Optional explicit x-axis (price) limits.

tuple[float, float] | None

default:"None"

Optional explicit y-axis limits.

int

default:"800"

Number of display points for plot resampling.

bool

default:"False"

When True and xlim is not set, plots across the full native probability domain instead of the compact default view domain.

matplotlib.figure.Figure

The rendered matplotlib figure.

Properties

np.ndarray

The default price grid used for standard visualization. Accessing this property triggers lazy distribution materialization on first call.

np.ndarray

Probability densities over the stored price grid, in decimal form.

np.ndarray

Cumulative probabilities over the stored price grid, in decimal form.

WarningDiagnostics

Structured diagnostic events recorded during fitting and materialization. Inspect .warning_diagnostics.events for details on data-quality issues, model-risk warnings, or CDF repairs.

ResolvedMarket

Immutable snapshot of the market inputs used during calibration, including the resolved underlying price, risk-free rate, and valuation date.

dict[str, Any]

Metadata captured during estimation, including the expiry timestamp, time to expiry in years, diagnostics, and domain information.

Example

from oipd import ProbCurve, MarketInputs, sources

# 1. Fetch a single-expiry option chain
expiries = sources.list_expiry_dates("SPY")
chain, snapshot = sources.fetch_chain("SPY", expiries=expiries[0])

market = MarketInputs(
    risk_free_rate=0.053,
    valuation_date=snapshot.asof,
    underlying_price=snapshot.underlying_price,
)

# 2. Build the probability curve
prob = ProbCurve.from_chain(chain, market)

# 3. Query probabilities
print(prob.prob_below(500))        # P(SPY < 500 at expiry)
print(prob.prob_between(490, 520)) # P(490 <= SPY < 520)
print(prob.prob_above(550))        # P(SPY >= 550)

# 4. Moments
print(f"Mean: {prob.mean():.2f}")
print(f"Skew: {prob.skew():.4f}")
print(f"Excess kurtosis: {prob.kurtosis():.4f}")

# 5. Quantiles
print(f"5th percentile: {prob.quantile(0.05):.2f}")
print(f"95th percentile: {prob.quantile(0.95):.2f}")

# 6. Export as DataFrame
df = prob.density_results(points=300)
print(df.head())

# 7. Plot
fig = prob.plot(kind="both", title="SPY Risk-Neutral Distribution")
fig.savefig("prob_curve.png", dpi=150, bbox_inches="tight")

Core objects

Inputs and data

Errors and diagnostics

Constructors

`ProbCurve.from_chain`

From a fitted `VolCurve`

Methods

Properties

Example

​Constructors

​ProbCurve.from_chain

​From a fitted VolCurve

​Methods

​Properties

​Example

Constructors

`ProbCurve.from_chain`

From a fitted `VolCurve`

Methods

Properties

Example