Source code for quantdata.dysanos.grid.gendysanos.plot_conditional_spot_example
"""Plot conditional physical and widened-proposal spot ranges from a real state."""
from __future__ import annotations
import argparse
import json
import math
import os
from datetime import date
from pathlib import Path
import numpy as np
from cdxcore.verbose import Context
from scipy.stats import norm
from quantdata.biz_calendar import DAYS_PER_YEAR
from quantdata.dysanos.grid.torch_simulator import (
_xar1_gaussian_step_factor,
_xar1_matrix_exp_terms,
)
from .torch_prep import GenDysanosExperiment, _load_generator_components
def _json_ready(value):
if isinstance(value, dict):
return {key: _json_ready(item) for key, item in value.items()}
if isinstance(value, np.ndarray):
return value.tolist()
if isinstance(value, np.floating):
return float(value)
if isinstance(value, np.integer):
return int(value)
return value
def _conditional_mean_surface_path(
*,
sampler,
initial_state: np.ndarray,
num_steps: int,
dt: float,
) -> np.ndarray:
"""Continue the selected surface state along its conditional mean path."""
center = np.asarray(sampler.pcaxar1.state_center, dtype=np.float64)
scale = np.asarray(sampler.pcaxar1.state_scale, dtype=np.float64)
raw_k = sampler.pcaxar1.k
raw_intercept = sampler.pcaxar1.U0
k = raw_k * scale[:, None] / scale[None, :]
intercept = (raw_intercept - center[None, :] @ raw_k) / scale[None, :]
transition, offset = _xar1_matrix_exp_terms(
U0=intercept,
k=k,
h=float(dt / sampler.pcaxar1.mean_dt),
)
autonomy_tolerance = 1.0e3 * np.finfo(float).eps * max(
1.0, float(np.linalg.norm(transition, ord=2))
)
if np.max(np.abs(transition[0, 1:])) > autonomy_tolerance:
raise ValueError(
"surface conditional mean depends on current spot by "
f"{transition[0, 1:]}"
)
standardized = np.empty((num_steps, initial_state.size), dtype=np.float64)
standardized[0] = (initial_state - center) / scale
for step in range(num_steps - 1):
standardized[step + 1, 0] = standardized[step, 0]
standardized[step + 1, 1:] = (
standardized[step, 1:] @ transition[1:, 1:]
+ offset[0, 1:]
)
return center[None, :] + standardized * scale[None, :]
def _conditional_log_spot_moments(
*,
sampler,
reference_path: np.ndarray,
dt: float,
) -> tuple[np.ndarray, np.ndarray, float]:
"""Return conditional log-spot means and standard deviations.
The complete surface component of ``reference_path`` is held fixed. The
moments therefore refer only to the scalar spot residual left after
conditioning on every realized surface innovation.
"""
center = np.asarray(sampler.pcaxar1.state_center, dtype=np.float64)
scale = np.asarray(sampler.pcaxar1.state_scale, dtype=np.float64)
if center.shape != scale.shape or center.shape != (reference_path.shape[1],):
raise ValueError(
f"invalid state normalization {center.shape}/{scale.shape} for "
f"path {reference_path.shape}"
)
standardized = (reference_path - center[None, :]) / scale[None, :]
normalized_dt = float(dt / sampler.pcaxar1.mean_dt)
raw_k = sampler.pcaxar1.k
raw_intercept = sampler.pcaxar1.U0
k = raw_k * scale[:, None] / scale[None, :]
intercept = (raw_intercept - center[None, :] @ raw_k) / scale[None, :]
loadings = sampler.pcaxar1.dU / scale[None, :]
transition, offset = _xar1_matrix_exp_terms(
U0=intercept,
k=k,
h=normalized_dt,
)
alpha_covariance = sampler.cholesky @ sampler.cholesky.T
covariance_rate = loadings.T @ alpha_covariance @ loadings
noise_factor = _xar1_gaussian_step_factor(
k=k,
C=covariance_rate,
h=normalized_dt,
A=transition,
)
covariance = noise_factor @ noise_factor.T
surface_covariance = 0.5 * (
covariance[1:, 1:] + covariance[1:, 1:].T
)
surface_inverse = np.linalg.pinv(
surface_covariance,
rcond=1.0e3 * np.finfo(float).eps,
hermitian=True,
)
spot_given_surface = surface_inverse @ covariance[1:, 0]
residual_variance = float(
covariance[0, 0] - covariance[0, 1:] @ spot_given_surface
)
if not math.isfinite(residual_variance) or residual_variance <= 0.0:
raise ValueError(
"conditional spot residual variance must be positive, got "
f"{residual_variance:g}"
)
innovations = (
standardized[1:]
- standardized[:-1] @ transition
- offset
)
surface_innovations = innovations[:, 1:]
conditional_mean = np.empty(reference_path.shape[0], dtype=np.float64)
conditional_variance = np.empty(reference_path.shape[0], dtype=np.float64)
conditional_mean[0] = standardized[0, 0]
conditional_variance[0] = 0.0
spot_autoregression = float(transition[0, 0])
for step in range(reference_path.shape[0] - 1):
conditional_mean[step + 1] = (
conditional_mean[step] * spot_autoregression
+ standardized[step, 1:] @ transition[1:, 0]
+ offset[0, 0]
+ surface_innovations[step] @ spot_given_surface
)
conditional_variance[step + 1] = (
spot_autoregression**2 * conditional_variance[step]
+ residual_variance
)
raw_mean = center[0] + scale[0] * conditional_mean
raw_std = scale[0] * np.sqrt(conditional_variance)
return raw_mean, raw_std, math.sqrt(residual_variance) * scale[0]
[docs]
def create_figure(
*,
start_date: date,
tail_multiplier: float,
seed: int,
output_path: Path,
) -> dict[str, object]:
if not math.isfinite(tail_multiplier) or tail_multiplier <= 1.0:
raise ValueError(
f"tail_multiplier must be finite and greater than one, got {tail_multiplier}"
)
output_path.parent.mkdir(parents=True, exist_ok=True)
experiment = GenDysanosExperiment(
num_samples=1,
num_alpha=None,
use_matrix_exp=True,
bandwidth=1.0,
seed=seed,
)
grid_config, market, _, sampler = _load_generator_components(
experiment,
verbose=Context.quiet,
)
matching_dates = [
index
for index, market_date in enumerate(market.dates)
if str(market_date) == start_date.isoformat()
]
if len(matching_dates) != 1:
raise ValueError(
f"expected one observation for {start_date}, found {len(matching_dates)}"
)
start_index = matching_dates[0]
dt = 1.0 / DAYS_PER_YEAR
expiries = np.asarray(grid_config.grid_expiries, dtype=np.float64)
expiry_steps = np.rint(expiries / dt).astype(np.int64)
if np.any(expiry_steps <= 0) or np.any(np.diff(expiry_steps) <= 0):
raise ValueError(f"invalid expiry steps {expiry_steps}")
maximum_expiry_error = float(np.max(np.abs(expiry_steps * dt - expiries)))
if maximum_expiry_error > 0.5 * dt:
raise ValueError(
f"expiry grid cannot be represented on the daily path: {maximum_expiry_error:g}"
)
reference_path = _conditional_mean_surface_path(
sampler=sampler,
initial_state=sampler.xstate[start_index].astype(np.float64),
num_steps=int(expiry_steps[-1]) + 1,
dt=dt,
)
if not np.allclose(reference_path[0], sampler.xstate[start_index]):
raise RuntimeError("simulated path does not start at the selected historical state")
conditional_log_mean, conditional_log_std, daily_residual_std = (
_conditional_log_spot_moments(
sampler=sampler,
reference_path=reference_path,
dt=dt,
)
)
initial_spot = float(market["spot_ref"][start_index])
log_spot_scale = math.log(initial_spot) - float(reference_path[0, 0])
absolute_log_mean = log_spot_scale + conditional_log_mean
normal_quantile = float(norm.ppf(0.95))
calibrated_lower = np.exp(
absolute_log_mean - normal_quantile * conditional_log_std
)
calibrated_upper = np.exp(
absolute_log_mean + normal_quantile * conditional_log_std
)
proposal_lower = np.exp(
absolute_log_mean
- normal_quantile * tail_multiplier * conditional_log_std
)
proposal_upper = np.exp(
absolute_log_mean
+ normal_quantile * tail_multiplier * conditional_log_std
)
conditional_median = np.exp(absolute_log_mean)
model_strikes = (
sampler.pricer.strikes[start_index].detach().cpu().numpy().astype(np.float64)
)
if model_strikes.shape != (expiries.size, 20):
raise ValueError(
f"unexpected initial model-strike grid {model_strikes.shape}"
)
cash_strikes = initial_spot * model_strikes
os.environ.setdefault("MPLCONFIGDIR", "/tmp/quantdata-matplotlib")
import matplotlib.pyplot as plt
from matplotlib.ticker import FuncFormatter
day_grid = np.arange(1, expiry_steps[-1] + 1)
time_grid = day_grid / DAYS_PER_YEAR
fig, axis = plt.subplots(figsize=(9.2, 4.8), constrained_layout=True)
axis.fill_between(
time_grid,
proposal_lower[1:],
proposal_upper[1:],
color="#d98c28",
alpha=0.20,
label=rf"widened component, $r={tail_multiplier:g}$ (5–95%)",
)
axis.plot(
time_grid,
proposal_lower[1:],
color="#b66c0d",
linewidth=0.8,
)
axis.plot(
time_grid,
proposal_upper[1:],
color="#b66c0d",
linewidth=0.8,
)
axis.fill_between(
time_grid,
calibrated_lower[1:],
calibrated_upper[1:],
color="#3976af",
alpha=0.32,
label="calibrated conditional law (5–95%)",
)
axis.plot(
time_grid,
conditional_median[1:],
color="#174b73",
linewidth=1.3,
label="conditional spot median",
)
for expiry_index, (expiry, strikes) in enumerate(
zip(expiries, cash_strikes, strict=True)
):
axis.scatter(
np.full(strikes.size, expiry),
strikes,
marker="_",
s=80,
linewidths=0.85,
color="#222222",
label=r"cash strikes of $C_0$" if expiry_index == 0 else None,
zorder=4,
)
axis.axhline(
initial_spot,
color="#555555",
linestyle=":",
linewidth=0.9,
label=rf"initial spot $S_0={initial_spot:,.0f}$",
)
axis.set_xscale("log")
axis.set_xticks(
expiries,
tuple(
f"{int(step)}d" if step < DAYS_PER_YEAR else "1y"
for step in expiry_steps
),
)
axis.set_xlim(time_grid[0], time_grid[-1] * 1.04)
axis.set_ylim(0.0, float(np.max(proposal_upper[expiry_steps])) * 1.04)
axis.set_xlabel("time from initial surface (log scale)")
axis.set_ylabel("SPX level / cash strike")
axis.yaxis.set_major_formatter(FuncFormatter(lambda value, _: f"{value:,.0f}"))
axis.grid(axis="y", alpha=0.22)
axis.legend(frameon=False, fontsize=8, loc="upper left")
fig.savefig(output_path, dpi=240)
plt.close(fig)
report = {
"definition": (
"Spot bands conditional on the mean future surface path starting from "
"a historical ML-SANOS state. The widened ranges are individual "
"importance-mixture components and are not physical-law confidence bands."
),
"start_date": start_date.isoformat(),
"start_index": start_index,
"initial_spot": initial_spot,
"surface_factors": sampler.pcaxar1.num_surface_alpha,
"tail_multiplier": tail_multiplier,
"seed": seed,
"daily_conditional_log_spot_residual_std": daily_residual_std,
"expiries_years": expiries,
"expiry_steps": expiry_steps,
"cash_strike_minimum": np.min(cash_strikes, axis=1),
"cash_strike_maximum": np.max(cash_strikes, axis=1),
"conditional_spot_median": conditional_median[expiry_steps],
"calibrated_spot_q05": calibrated_lower[expiry_steps],
"calibrated_spot_q95": calibrated_upper[expiry_steps],
"proposal_spot_q05": proposal_lower[expiry_steps],
"proposal_spot_q95": proposal_upper[expiry_steps],
}
report_path = output_path.with_suffix(".json")
report_path.write_text(
json.dumps(_json_ready(report), indent=2, sort_keys=True) + "\n",
encoding="utf-8",
)
return report
[docs]
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--start-date", type=date.fromisoformat, default=date(2025, 5, 6))
parser.add_argument("--tail-multiplier", type=float, default=8.0)
parser.add_argument("--seed", type=int, default=614_203)
parser.add_argument(
"--output-path",
type=Path,
default=(
Path(__file__).resolve().parents[2]
/ "tex"
/ "generated"
/ "conditional_spot_importance_example.png"
),
)
arguments = parser.parse_args()
report = create_figure(
start_date=arguments.start_date,
tail_multiplier=arguments.tail_multiplier,
seed=arguments.seed,
output_path=arguments.output_path,
)
print(
f"Wrote conditional spot example for {report['start_date']} to "
f"{arguments.output_path}"
)
if __name__ == "__main__":
main()