"""Historical, invariant, and aggregate PCA benchmark diagnostics."""
from __future__ import annotations
import copy
from dataclasses import asdict
from typing import Any
import numpy as np
from cdxcore.err import verify_inp
from quantdata.biz_calendar import DAYS_PER_YEAR
from quantdata.dysanos.grid.gendysanos.run_surface_first_diagnostics import (
_distribution_metrics,
_weekly_path_statistics,
)
from .decoder import PCATotalVarianceDecoder, WingHitDiagnostics
from .simulator import ImpliedPCASampler
from .static_arbitrage import StaticArbitrageAccumulator
DATA_QUALIFICATION = (
"GridMarketDefinition.load() first fits a smooth statically arbitrage-free "
"SANOS surface to each date and evaluates it on the regular grid. This "
"comparison tests the SANOS generative decoder against direct PCA when both "
"use the same cleaned, SANOS-interpolated mid_vols observations; it does not "
"test SANOS preprocessing against raw OptionMetrics interpolation."
)
DYNAMIC_ARBITRAGE_QUALIFICATION = (
"Static surface arbitrage and sampled fixed-contract return diagnostics are "
"distinct. Failure to detect a one-sided opportunity in the sampled "
"contracts does not prove absence of arbitrary dynamic arbitrage."
)
[docs]
def invariant_surface_diagnostics(
sampler: ImpliedPCASampler,
*,
num_samples: int = 100_000,
seed_reset: bool = True,
) -> dict[str, Any]:
"""Compare invariant Gaussian draws with historical PCA surface states."""
verify_inp(
isinstance(num_samples, int) and num_samples > 0,
lambda: f"'num_samples' must be positive, got {num_samples!r}",
)
rng_state = copy.deepcopy(sampler.rng.bit_generator.state)
try:
if seed_reset:
sampler.reset_rng()
mean, covariance = sampler.invariant_surface_distribution()
samples = sampler.sample_invariant_surface_states(num_samples)
finally:
# Diagnostics must not change the logically seeded path universe.
sampler.rng.bit_generator.state = rng_state
metrics = _distribution_metrics(
sampler.xstate[:, 1:].astype(np.float64, copy=False),
samples.astype(np.float64, copy=False),
rng=np.random.default_rng(sampler.config.seed + 400_003),
)
return {
"sample_count": num_samples,
"fitted_invariant_mean": mean.tolist(),
"fitted_invariant_covariance": covariance.tolist(),
"historical_comparison": metrics,
"surface_generator_eigenvalues": [
{"real": float(value.real), "imaginary": float(value.imag)}
for value in np.linalg.eigvals(sampler.pcaxar1.k[1:, 1:])
],
}
[docs]
def weekly_path_diagnostics(
sampler: ImpliedPCASampler,
*,
num_samples: int = 100_000,
seed_reset: bool = True,
) -> dict[str, Any]:
"""Compare exact simulated five-day increments with historical ones."""
verify_inp(
isinstance(num_samples, int) and num_samples > 0,
lambda: f"'num_samples' must be positive, got {num_samples!r}",
)
verify_inp(
sampler.xstate.shape[0] > 5,
"weekly diagnostics require at least six historical observations",
)
rng_state = copy.deepcopy(sampler.rng.bit_generator.state)
try:
if seed_reset:
sampler.reset_rng()
paths = sampler.free_sample_xstates(
num_steps=6,
num_samples=num_samples,
dt=1.0 / DAYS_PER_YEAR,
bandwidth=1.0,
)
finally:
sampler.rng.bit_generator.state = rng_state
historical_change = sampler.xstate[5:] - sampler.xstate[:-5]
simulated_change = paths[:, -1] - paths[:, 0]
return {
"sample_count": num_samples,
"weekly_increment_vs_historical_weekly_increment": (
_distribution_metrics(
historical_change,
simulated_change,
rng=np.random.default_rng(sampler.config.seed + 400_009),
)
),
"historical_path_statistics": _weekly_path_statistics(
np.stack((sampler.xstate[:-5], sampler.xstate[5:]), axis=1)
),
"simulated_path_statistics": _weekly_path_statistics(paths),
"independent_path_interpretation": (
"each simulated row is one independently initialized and driven "
"six-state daily path"
),
}
[docs]
def historical_static_arbitrage_diagnostics(
decoder: PCATotalVarianceDecoder,
scores: np.ndarray,
*,
strikes: np.ndarray,
roundoff_multipliers: tuple[int, ...] = (0, 1, 8, 32, 128),
block_size: int = 512,
) -> tuple[dict[str, Any], WingHitDiagnostics]:
"""Check every historical PCA reconstruction without any repair."""
scores = np.asarray(scores)
verify_inp(
scores.ndim == 2
and scores.shape[1] == decoder.pca.num_components
and scores.shape[0] > 0,
lambda: f"invalid historical score matrix {scores.shape}",
)
strikes = np.asarray(strikes, dtype=np.float64)
accumulator = StaticArbitrageAccumulator(
strikes=strikes,
expiries=decoder.pca.expiries,
roundoff_multipliers=roundoff_multipliers,
)
wing_hits = WingHitDiagnostics(queries=0, left_hits=0, right_hits=0)
for start in range(0, scores.shape[0], block_size):
block = scores[start : start + block_size]
calls, hits = decoder.normalized_call_prices(
block,
decoder.pca.expiries[:, None],
strikes[None, :],
)
nms = decoder.nms_from_relative_strikes(
block,
decoder.pca.expiries[:, None],
strikes[None, :],
)
accumulator.update(calls, normalized_moneyness=nms)
wing_hits = wing_hits + hits
return accumulator.report(), wing_hits
[docs]
def sampler_fit_report(sampler: ImpliedPCASampler) -> dict[str, Any]:
"""Serialize the shared surface-first fit without changing its semantics."""
fit = sampler.pcaxar1
quality = fit.fit_quality
assert quality is not None
return {
"surface_first": fit.surface_first,
"num_surface_factors": fit.num_surface_alpha,
"surface_innovation_variance_explained": fit.surface_var_explained,
"spot_innovation_variance_explained_by_surface_factors": (
fit.spot_surface_r2
),
"orthogonal_spot_residual_std": fit.spot_residual_std,
"mean_historical_dt": fit.mean_dt,
"generator": fit.k.tolist(),
"affine_drift": fit.U0.tolist(),
"innovation_loadings": fit.dU.tolist(),
"fit_quality": {
"r2": quality.r2,
"r2_by_state": quality.r2_by_state.tolist(),
"rmse": quality.rmse,
"rmse_by_state": quality.rmse_by_state.tolist(),
"sample_mean": quality.sample_mean.tolist(),
"sample_std": quality.sample_std.tolist(),
"fitted_mean": quality.fitted_mean.tolist(),
"mean_error": quality.mean_error.tolist(),
"summary": quality.summary_statistics(),
},
"configuration": asdict(sampler.config),
}
__all__ = [
"DATA_QUALIFICATION",
"DYNAMIC_ARBITRAGE_QUALIFICATION",
"historical_static_arbitrage_diagnostics",
"invariant_surface_diagnostics",
"sampler_fit_report",
"weekly_path_diagnostics",
]