spb/wp46_uqo

1"""Common containers for fits and forecasts (all models, arch-backed or custom)."""2from __future__ import annotations34from dataclasses import dataclass, field56import numpy as np789@dataclass10class FitResult:11    model_id: str12    dist: str13    param_names: list[str]14    params: np.ndarray                  # natural parameters, order = param_names (mean, volatility, distribution)15    loglik: float16    converged: bool17    n_obs: int18    n_iter: int = 019    n_restarts: int = 020    time_s: float = 0.021    admissible: bool = True             # stationarity/positivity conditions satisfied at the optimum22    notes: str = ""23    aux: dict = field(default_factory=dict)   # model-specific (e.g. kappa, backcast, regime probabilities)2425    @property26    def nparams(self) -> int:27        return int(len(self.params))2829    def param(self, name: str) -> float:30        return float(self.params[self.param_names.index(name)])3132    def dist_params(self) -> np.ndarray:33        from .distributions import DIST_NPARAMS34        k = DIST_NPARAMS[self.dist]35        return self.params[len(self.params) - k:] if k else np.empty(0)363738@dataclass39class Forecast:40    """Per-step conditional variance forecasts E[sigma^2_{t+k} | F_t], k = 1..h, in percent^2, plus the one-step mean and41    the distribution parameters needed for density/VaR evaluation."""42    model_id: str43    dist: str44    step_var: np.ndarray                # shape (h,)45    mean: float                         # one-step conditional mean (percent)46    dist_params: np.ndarray47    method: str                         # 'analytic' | 'simulation' | 'direct'48    sigma2_t: float = float("nan")      # fitted sigma^2 at the origin (diagnostic)4950    def cumulative(self, h: int) -> float:51        """Variance of the h-day cumulative return under conditional serial uncorrelation of the innovations."""52        return float(np.sum(self.step_var[:h]))53