"""Static-fit, forecast, and no-arbitrage metrics for Tangent Lévy."""
from __future__ import annotations
import math
from dataclasses import dataclass
import numpy as np
from cdxcore.err import verify_inp
from .coordinates import implied_volatility, normalized_call_intrinsic
[docs]
@dataclass(frozen=True)
class PriceErrorMetrics:
"""Outright errors against a smoothed normalized call target."""
observations: int
weighted_rmse: float
rmse: float
mae: float
median_absolute_error: float
p95_absolute_error: float
p99_absolute_error: float
maximum_absolute_error: float
mean_signed_error: float
[docs]
@dataclass(frozen=True)
class IntervalErrorMetrics:
"""Half-spread-normalized executable-interval diagnostics."""
observations: int
fraction_inside: float
fraction_outside: float
mean_all: float
median_all: float
mean_positive: float
median_positive: float
p95: float
p99: float
[docs]
@dataclass(frozen=True)
class NoArbitrageMetrics:
"""Maximum finite-grid static-arbitrage violations."""
lower_bound: float
upper_bound: float
strike_monotonicity: float
strike_convexity: float
calendar_monotonicity: float
@property
def maximum(self) -> float:
"""Largest reported violation."""
return max(
self.lower_bound,
self.upper_bound,
self.strike_monotonicity,
self.strike_convexity,
self.calendar_monotonicity,
)
[docs]
@dataclass(frozen=True)
class StatisticalFidelityMetrics:
"""Centered-innovation moment and factor-structure comparison."""
reference_observations: int
model_observations: int
dimensions: int
mean_change_error_norm: float
relative_covariance_error: float
correlation_error: float
median_variance_ratio: float
eigenvalue_spectrum_error: float
maximum_principal_angle_degrees: float
reference_covariance_condition: float
model_covariance_condition: float
[docs]
def price_error_metrics(
model: np.ndarray,
target: np.ndarray,
*,
half_spread: np.ndarray | None = None,
mask: np.ndarray | None = None,
) -> PriceErrorMetrics:
"""Compute original-strike or dense-grid outright price errors."""
model = np.asarray(model, dtype=np.float64)
target = np.asarray(target, dtype=np.float64)
verify_inp(
model.shape == target.shape,
lambda: f"model and target shapes differ: {model.shape}, {target.shape}",
)
active = np.ones(model.shape, dtype=bool) if mask is None else np.asarray(mask, dtype=bool)
verify_inp(
active.shape == model.shape,
lambda: f"mask shape {active.shape} does not match prices {model.shape}",
)
active &= np.isfinite(model) & np.isfinite(target)
verify_inp(np.any(active), "no finite active observations for price metrics")
errors = model[active] - target[active]
absolute = np.abs(errors)
if half_spread is None:
weighted_rmse = float(np.sqrt(np.mean(np.square(errors))))
else:
spread = np.asarray(half_spread, dtype=np.float64)
verify_inp(
spread.shape == model.shape
and np.all(np.isfinite(spread[active]))
and np.all(spread[active] > 0.0),
lambda: "half spreads must be finite, positive, and match prices",
)
inverse_variance = 1.0 / np.square(spread[active])
weighted_rmse = float(
np.sqrt(np.sum(inverse_variance * np.square(errors)) / np.sum(inverse_variance))
)
return PriceErrorMetrics(
observations=int(errors.size),
weighted_rmse=weighted_rmse,
rmse=float(np.sqrt(np.mean(np.square(errors)))),
mae=float(np.mean(absolute)),
median_absolute_error=float(np.median(absolute)),
p95_absolute_error=float(np.quantile(absolute, 0.95)),
p99_absolute_error=float(np.quantile(absolute, 0.99)),
maximum_absolute_error=float(np.max(absolute)),
mean_signed_error=float(np.mean(errors)),
)
[docs]
def interval_error_metrics(
model: np.ndarray,
bids: np.ndarray,
asks: np.ndarray,
*,
half_spread_floor: float = 1.0e-4,
mask: np.ndarray | None = None,
) -> IntervalErrorMetrics:
"""Implement the repository half-spread interval-error convention."""
model = np.asarray(model, dtype=np.float64)
bids = np.asarray(bids, dtype=np.float64)
asks = np.asarray(asks, dtype=np.float64)
verify_inp(
model.shape == bids.shape == asks.shape,
lambda: "model, bid, and ask arrays must have the same shape",
)
verify_inp(
math.isfinite(half_spread_floor) and half_spread_floor > 0.0,
lambda: f"invalid half-spread floor {half_spread_floor!r}",
)
active = np.ones(model.shape, dtype=bool) if mask is None else np.asarray(mask, dtype=bool)
verify_inp(active.shape == model.shape, "mask shape does not match interval arrays")
active &= (
np.isfinite(model)
& np.isfinite(bids)
& np.isfinite(asks)
& (asks > bids)
)
verify_inp(np.any(active), "no finite active observations for interval metrics")
model_active = model[active]
bids_active = bids[active]
asks_active = asks[active]
half_spread = np.maximum(
0.5 * (asks_active - bids_active),
half_spread_floor,
)
errors = (
np.maximum(0.0, model_active - asks_active)
+ np.maximum(0.0, bids_active - model_active)
) / half_spread
positive = errors[errors > 0.0]
return IntervalErrorMetrics(
observations=int(errors.size),
fraction_inside=float(np.mean(errors == 0.0)),
fraction_outside=float(np.mean(errors > 0.0)),
mean_all=float(np.mean(errors)),
median_all=float(np.median(errors)),
mean_positive=float(np.mean(positive)) if positive.size else 0.0,
median_positive=float(np.median(positive)) if positive.size else 0.0,
p95=float(np.quantile(errors, 0.95)),
p99=float(np.quantile(errors, 0.99)),
)
[docs]
def implied_volatility_error(
*,
tau: np.ndarray,
strikes: np.ndarray,
model_calls: np.ndarray,
target_calls: np.ndarray,
mask: np.ndarray | None = None,
) -> PriceErrorMetrics:
"""Return implied-volatility error summaries in volatility points."""
model_vol = implied_volatility(tau=tau, strike=strikes, call_price=model_calls)
target_vol = implied_volatility(tau=tau, strike=strikes, call_price=target_calls)
return price_error_metrics(model_vol, target_vol, mask=mask)
[docs]
def no_arbitrage_metrics(
calls: np.ndarray,
*,
tau: np.ndarray,
strikes: np.ndarray,
) -> NoArbitrageMetrics:
"""Measure normalized call bounds and finite-grid shape restrictions."""
calls = np.asarray(calls, dtype=np.float64)
tau = np.asarray(tau, dtype=np.float64)
strikes = np.asarray(strikes, dtype=np.float64)
verify_inp(
calls.ndim == 2
and tau.shape == (calls.shape[0],)
and strikes.shape in {(calls.shape[1],), calls.shape}
and np.all(np.isfinite(calls)),
lambda: (
"calls must have shape (T,N), tau shape (T,), and strikes shape "
f"(N,) or (T,N); got {calls.shape}, {tau.shape}, {strikes.shape}"
),
)
strike_grid = (
np.broadcast_to(strikes, calls.shape) if strikes.ndim == 1 else strikes
)
verify_inp(
calls.shape[1] >= 3
and np.all(np.diff(strike_grid, axis=1) > 0.0)
and np.allclose(strike_grid, strike_grid[:1]),
lambda: (
"no-arbitrage surface metrics require at least three common, "
"strictly increasing strikes across maturities"
),
)
intrinsic = normalized_call_intrinsic(strike_grid)
lower = float(np.max(np.maximum(intrinsic - calls, 0.0)))
upper = float(np.max(np.maximum(calls - 1.0, 0.0)))
monotonic = float(np.max(np.maximum(np.diff(calls, axis=1), 0.0)))
slopes = np.diff(calls, axis=1) / np.diff(strike_grid, axis=1)
convexity = float(np.max(np.maximum(-np.diff(slopes, axis=1), 0.0)))
calendar = float(np.max(np.maximum(-np.diff(calls, axis=0), 0.0)))
return NoArbitrageMetrics(
lower_bound=lower,
upper_bound=upper,
strike_monotonicity=monotonic,
strike_convexity=convexity,
calendar_monotonicity=calendar,
)
[docs]
def statistical_fidelity_metrics(
reference_changes: np.ndarray,
model_changes: np.ndarray,
*,
num_factors: int = 5,
) -> StatisticalFidelityMetrics:
"""Compare two change samples without assigning a physical-measure claim."""
reference = np.asarray(reference_changes, dtype=np.float64)
model = np.asarray(model_changes, dtype=np.float64)
verify_inp(
reference.ndim == 2
and model.ndim == 2
and reference.shape[1] == model.shape[1]
and reference.shape[0] >= 2
and model.shape[0] >= 2
and np.all(np.isfinite(reference))
and np.all(np.isfinite(model)),
lambda: (
"statistical fidelity requires finite samples (N,D) with a common "
f"dimension, got {reference.shape} and {model.shape}"
),
)
verify_inp(
isinstance(num_factors, int) and num_factors > 0,
lambda: f"'num_factors' must be positive, got {num_factors!r}",
)
reference_covariance = np.atleast_2d(np.cov(reference, rowvar=False, ddof=1))
model_covariance = np.atleast_2d(np.cov(model, rowvar=False, ddof=1))
covariance_scale = max(float(np.linalg.norm(reference_covariance)), 1.0e-15)
covariance_error = float(
np.linalg.norm(model_covariance - reference_covariance) / covariance_scale
)
reference_variance = np.diag(reference_covariance)
model_variance = np.diag(model_covariance)
active = (reference_variance > 1.0e-15) & (model_variance > 1.0e-15)
verify_inp(
np.count_nonzero(active) >= 2,
lambda: "fewer than two common nondegenerate dimensions",
)
reference_scale = np.sqrt(reference_variance[active])
model_scale = np.sqrt(model_variance[active])
reference_correlation = reference_covariance[np.ix_(active, active)] / (
reference_scale[:, None] * reference_scale[None, :]
)
model_correlation = model_covariance[np.ix_(active, active)] / (
model_scale[:, None] * model_scale[None, :]
)
correlation_error = float(
np.linalg.norm(model_correlation - reference_correlation)
/ max(float(np.linalg.norm(reference_correlation)), 1.0e-15)
)
reference_values, reference_vectors = np.linalg.eigh(reference_covariance)
model_values, model_vectors = np.linalg.eigh(model_covariance)
reference_order = np.argsort(reference_values)[::-1]
model_order = np.argsort(model_values)[::-1]
reference_values = np.maximum(reference_values[reference_order], 0.0)
model_values = np.maximum(model_values[model_order], 0.0)
eigenvalue_error = float(
np.linalg.norm(model_values - reference_values)
/ max(float(np.linalg.norm(reference_values)), 1.0e-15)
)
factors = min(
num_factors,
int(np.count_nonzero(reference_values > 1.0e-15)),
int(np.count_nonzero(model_values > 1.0e-15)),
)
if factors == 0:
maximum_angle = 90.0
else:
reference_basis = reference_vectors[:, reference_order[:factors]]
model_basis = model_vectors[:, model_order[:factors]]
singular_values = np.linalg.svd(
reference_basis.T @ model_basis,
compute_uv=False,
)
angles = np.arccos(np.clip(singular_values, 0.0, 1.0))
maximum_angle = float(np.degrees(np.max(angles)))
def condition(values: np.ndarray) -> float:
positive = values[values > 1.0e-15]
return (
float(positive[0] / positive[-1])
if positive.size > 0
else math.inf
)
return StatisticalFidelityMetrics(
reference_observations=reference.shape[0],
model_observations=model.shape[0],
dimensions=reference.shape[1],
mean_change_error_norm=float(
np.linalg.norm(np.mean(model, axis=0) - np.mean(reference, axis=0))
),
relative_covariance_error=covariance_error,
correlation_error=correlation_error,
median_variance_ratio=float(
np.median(model_variance[active] / reference_variance[active])
),
eigenvalue_spectrum_error=eigenvalue_error,
maximum_principal_angle_degrees=maximum_angle,
reference_covariance_condition=condition(reference_values),
model_covariance_condition=condition(model_values),
)
[docs]
def energy_score(
ensemble: np.ndarray,
observation: np.ndarray,
*,
component_weights: np.ndarray | None = None,
) -> float:
"""Compute the unbiased finite-ensemble multivariate energy score."""
ensemble = np.asarray(ensemble, dtype=np.float64)
observation = np.asarray(observation, dtype=np.float64)
verify_inp(
ensemble.ndim == 2
and ensemble.shape[0] >= 2
and observation.shape == (ensemble.shape[1],)
and np.all(np.isfinite(ensemble))
and np.all(np.isfinite(observation)),
lambda: "energy score requires finite ensemble (M,D) and observation (D,)",
)
weights = (
np.ones(ensemble.shape[1], dtype=np.float64)
if component_weights is None
else np.asarray(component_weights, dtype=np.float64)
)
verify_inp(
weights.shape == (ensemble.shape[1],)
and np.all(np.isfinite(weights))
and np.all(weights >= 0.0)
and np.any(weights > 0.0),
lambda: "component weights must be finite, nonnegative, and nonzero",
)
def norms(values: np.ndarray) -> np.ndarray:
return np.sqrt(np.sum(weights * np.square(values), axis=-1))
first = float(np.mean(norms(ensemble - observation)))
scaled = ensemble * np.sqrt(weights)[None, :]
squared_norms = np.sum(np.square(scaled), axis=1)
pair_sum = 0.0
block_size = min(512, ensemble.shape[0])
# Block the O(M^2) Gram calculation to keep memory bounded at 5,000 paths.
for left_start in range(0, ensemble.shape[0], block_size):
left_stop = min(left_start + block_size, ensemble.shape[0])
left = scaled[left_start:left_stop]
for right_start in range(left_start, ensemble.shape[0], block_size):
right_stop = min(right_start + block_size, ensemble.shape[0])
right = scaled[right_start:right_stop]
distance_squared = (
squared_norms[left_start:left_stop, None]
+ squared_norms[None, right_start:right_stop]
- 2.0 * left @ right.T
)
distances = np.sqrt(np.maximum(distance_squared, 0.0))
if right_start == left_start:
pair_sum += float(np.sum(np.triu(distances, k=1)))
else:
pair_sum += float(np.sum(distances))
second = pair_sum / (ensemble.shape[0] * (ensemble.shape[0] - 1))
return first - second
[docs]
def variogram_score(
ensemble: np.ndarray,
observation: np.ndarray,
*,
pairs: np.ndarray,
pair_weights: np.ndarray | None = None,
order: float = 0.5,
) -> float:
"""Compute a finite-ensemble variogram score on prespecified pairs."""
ensemble = np.asarray(ensemble, dtype=np.float64)
observation = np.asarray(observation, dtype=np.float64)
pairs = np.asarray(pairs, dtype=np.int64)
verify_inp(
ensemble.ndim == 2
and observation.shape == (ensemble.shape[1],)
and pairs.ndim == 2
and pairs.shape[1] == 2
and pairs.size > 0
and np.all(pairs >= 0)
and np.all(pairs < ensemble.shape[1]),
lambda: "invalid ensemble, observation, or variogram pairs",
)
verify_inp(
math.isfinite(order) and 0.0 < order < 2.0,
lambda: f"variogram order must lie in (0,2), got {order!r}",
)
weights = (
np.ones(pairs.shape[0], dtype=np.float64)
if pair_weights is None
else np.asarray(pair_weights, dtype=np.float64)
)
verify_inp(
weights.shape == (pairs.shape[0],)
and np.all(np.isfinite(weights))
and np.all(weights >= 0.0),
lambda: "invalid variogram pair weights",
)
left = pairs[:, 0]
right = pairs[:, 1]
observed = np.abs(observation[left] - observation[right]) ** order
predicted = np.mean(
np.abs(ensemble[:, left] - ensemble[:, right]) ** order,
axis=0,
)
return float(np.sum(weights * np.square(observed - predicted)))
[docs]
def paired_block_bootstrap_interval(
score_difference: np.ndarray,
*,
block_length: int = 20,
confidence: float = 0.95,
samples: int = 2_000,
seed: int = 15_040_033,
) -> tuple[float, float, float]:
"""Return mean and percentile interval for paired rolling-origin scores."""
values = np.asarray(score_difference, dtype=np.float64)
verify_inp(
values.ndim == 1 and values.size >= 2 and np.all(np.isfinite(values)),
lambda: "score differences must be a finite vector with at least two values",
)
verify_inp(
isinstance(block_length, int) and 0 < block_length <= values.size,
lambda: f"invalid block length {block_length!r} for {values.size} scores",
)
verify_inp(
0.0 < confidence < 1.0 and isinstance(samples, int) and samples > 0,
lambda: "confidence and bootstrap sample count are invalid",
)
rng = np.random.default_rng(seed)
starts = np.arange(values.size - block_length + 1)
blocks_needed = math.ceil(values.size / block_length)
bootstrap = np.empty(samples, dtype=np.float64)
offsets = np.arange(block_length)
for sample in range(samples):
selected_starts = rng.choice(starts, size=blocks_needed, replace=True)
index = (selected_starts[:, None] + offsets[None, :]).ravel()[: values.size]
bootstrap[sample] = np.mean(values[index])
tail = 0.5 * (1.0 - confidence)
return (
float(np.mean(values)),
float(np.quantile(bootstrap, tail)),
float(np.quantile(bootstrap, 1.0 - tail)),
)