"""Constrained PCA estimation of Tangent Lévy code-book dynamics."""
from __future__ import annotations
from dataclasses import dataclass
import numpy as np
from cdxcore.err import verify, verify_inp
from .config import DynamicsConfig
from .constraints import constraint_residuals, project_factor_constraints
[docs]
@dataclass(frozen=True)
class DynamicsFit:
"""Annualized factor representation of one-session ``kappa`` changes."""
tau: np.ndarray
jump_x: np.ndarray
beta: np.ndarray
eigenvalues_one_session: np.ndarray
explained_variance_ratio: np.ndarray
mean_change: np.ndarray
observations: int
maximum_constraint_residual: float
covariance_shrinkage: float
dt: float
active_mask: np.ndarray | None = None
@property
def num_factors(self) -> int:
"""Number of retained Brownian factors."""
return int(self.beta.shape[0])
[docs]
def reconstructed_one_session_covariance(self) -> np.ndarray:
"""Return the retained low-rank covariance in flattened coordinates."""
flat = self.beta.reshape(self.num_factors, -1)
return self.dt * flat.T @ flat
def _orient_components(components: np.ndarray) -> np.ndarray:
result = components.copy()
for index, component in enumerate(result):
pivot = int(np.argmax(np.abs(component)))
if component[pivot] < 0.0:
result[index] *= -1.0
return result
[docs]
def fit_dynamics(
forward_density_history: np.ndarray,
*,
config: DynamicsConfig = DynamicsConfig(),
consecutive_mask: np.ndarray | None = None,
) -> DynamicsFit:
"""Fit constrained constant factors to consecutive daily code-book changes."""
history = np.asarray(forward_density_history, dtype=np.float64)
tau = np.asarray(config.tau_grid, dtype=np.float64)
jump_x = np.asarray(config.jump_x_grid, dtype=np.float64)
verify_inp(
history.ndim == 3
and history.shape[1:] == (tau.size, jump_x.size)
and history.shape[0] >= 3
and np.all(np.isfinite(history))
and np.all(history >= 0.0),
lambda: (
"history must be finite, nonnegative, and have shape (D,T,X) with "
f"at least three dates; got {history.shape}"
),
)
changes = np.diff(history, axis=0)
if consecutive_mask is not None:
consecutive_mask = np.asarray(consecutive_mask, dtype=bool)
verify_inp(
consecutive_mask.shape == (changes.shape[0],),
lambda: (
"'consecutive_mask' must have one value per date transition, got "
f"{consecutive_mask.shape}"
),
)
changes = changes[consecutive_mask]
verify_inp(
changes.shape[0] >= config.minimum_observations,
lambda: (
"dynamics covariance requires at least "
f"{config.minimum_observations} consecutive changes, got "
f"{changes.shape[0]}"
),
)
empirical_scale = np.std(changes, axis=0, ddof=1)
minimum_history = np.min(history, axis=0)
active_mask = (
(minimum_history > config.inactive_density_threshold)
& (
minimum_history
> config.boundary_standard_deviations * empirical_scale
)
)
for _ in range(5):
projected = project_factor_constraints(
changes,
jump_x=jump_x,
active_mask=active_mask,
)
projected_scale = np.std(projected, axis=0, ddof=1)
updated_mask = active_mask & (
minimum_history
> config.boundary_standard_deviations * projected_scale
)
if np.array_equal(updated_mask, active_mask):
break
active_mask = updated_mask
projected = project_factor_constraints(
changes,
jump_x=jump_x,
active_mask=active_mask,
)
mean_change = np.mean(projected, axis=0)
centered = projected - mean_change
flat = centered.reshape(centered.shape[0], -1)
_, singular_values, right_vectors = np.linalg.svd(flat, full_matrices=False)
components = _orient_components(right_vectors)
eigenvalues = np.square(singular_values) / (flat.shape[0] - 1)
total_variance = float(np.sum(eigenvalues))
average_variance = total_variance / flat.shape[1]
shrunk_eigenvalues = (
(1.0 - config.covariance_shrinkage) * eigenvalues
+ config.covariance_shrinkage * average_variance
)
positive_eigenvalues = eigenvalues > (
np.finfo(np.float64).eps * max(1.0, float(eigenvalues[0]))
)
retained = min(config.num_factors, int(np.count_nonzero(positive_eigenvalues)))
verify(
retained > 0,
lambda: "historical changes have no positive covariance eigenvalue",
)
retained_components = components[:retained].reshape(
retained,
tau.size,
jump_x.size,
)
retained_components = project_factor_constraints(
retained_components,
jump_x=jump_x,
active_mask=active_mask,
)
norms = np.linalg.norm(retained_components.reshape(retained, -1), axis=1)
verify(
np.all(norms > 0.0),
lambda: f"constraint projection annihilated a PCA mode: norms={norms}",
)
retained_components /= norms[:, None, None]
beta = (
np.sqrt(shrunk_eigenvalues[:retained] / config.dt)[:, None, None]
* retained_components
)
residual = constraint_residuals(beta, jump_x=jump_x)
explained = (
shrunk_eigenvalues[:retained] / total_variance
if total_variance > 0.0
else np.zeros(retained, dtype=np.float64)
)
return DynamicsFit(
tau=tau,
jump_x=jump_x,
beta=beta,
eigenvalues_one_session=shrunk_eigenvalues[:retained],
explained_variance_ratio=explained,
mean_change=mean_change,
observations=int(changes.shape[0]),
maximum_constraint_residual=float(np.max(np.abs(residual))),
covariance_shrinkage=config.covariance_shrinkage,
dt=config.dt,
active_mask=active_mask,
)