Neutral comparisons between observed option quotes and caller-supplied model values.
scan/3 never prices an option or infers volatility. The caller supplies a
quote map, a model-value map, and every comparison policy. Each model entry
includes the inputs used to produce it and volatility provenance declaring
whether that volatility came from the observed quote.
Quotes and model values are keyed by the same caller-selected instrument ID.
A quote contains :bid, :ask, and :observed_at; a model entry contains
:value, :inputs, and :volatility_source. :inputs must expose a
non-negative :volatility. The volatility source has this contract:
%{
name: :realized_30_day,
derived_from_observed_quote: false
}The settings map has no defaults. It requires:
:quote_side—:bid,:ask, or:mid:as_of— aDateTimeor Unix epoch milliseconds:max_quote_age_ms— a non-negative staleness limit:transaction_costs— non-negative:feesand:slippageestimates, expressed in the same units as each quote and model value:action_thresholds—:absoluteand:relativenon-negative deviation thresholds; either may benil, but not both. Relative deviation uses model value as its denominator, and every enabled threshold must be met.
Valid rows report the signed raw deviation (observed - model) separately
from estimated costs. Costs reduce the deviation magnitude without changing
its sign. Thresholds are evaluated against the remaining magnitude and do
not produce a trade recommendation.
Missing, crossed, stale, and future-dated quotes are excluded and labelled. A model whose volatility is declared as derived from the same observed quote is also excluded, so the quote is never labelled deviant from a model that circularly used it as the volatility input.
API Functions
| Function | Arity | Description | Param Kinds |
|---|---|---|---|
scan | 3 | Compare observed quotes with independent caller-supplied model values. | quotes: exchange_data, model_values: value, settings: value |
Summary
Types
Top-level input or policy validation failure.
Caller-supplied model value and the inputs that produced it.
Caller-selected quote observation in model-value currency units.
Successful scan with explicit assumptions and per-instrument results.
Explicit policies applied to every row in one scan.
Provenance for the model's volatility input.
Functions
Compares matching quote and model maps under fully explicit caller policies.
Types
@type error_reason() :: {:invalid_input, :quotes | :model_values | :settings} | {:missing_setting, atom()} | {:invalid_setting, atom()}
Top-level input or policy validation failure.
@type model_value() :: %{ value: number(), inputs: %{:volatility => number(), optional(term()) => term()}, volatility_source: volatility_source() }
Caller-supplied model value and the inputs that produced it.
@type quote() :: %{ bid: number(), ask: number(), observed_at: DateTime.t() | integer() }
Caller-selected quote observation in model-value currency units.
Successful scan with explicit assumptions and per-instrument results.
@type settings() :: %{ quote_side: :bid | :ask | :mid, as_of: DateTime.t() | integer(), max_quote_age_ms: non_neg_integer(), transaction_costs: %{fees: number(), slippage: number()}, action_thresholds: %{absolute: number() | nil, relative: number() | nil} }
Explicit policies applied to every row in one scan.
@type volatility_source() :: %{ :name => atom() | String.t(), :derived_from_observed_quote => boolean(), optional(term()) => term() }
Provenance for the model's volatility input.