Skip to content

"Vibe-Trading: Your Personal Trading Agent"

9.7 KB
Raw Blame
"""Copula models for non-linear dependency and tail risk analysis.

Implements bivariate Archimedean copulas (Clayton, Gumbel, Frank) and Gaussian copula,
with Kendall's tau calibration and tail dependence coefficients.
"""

from __future__ import annotations

import math
from typing import Literal

import numpy as np
from scipy.stats import norm, rankdata

__all__ = [
    "clayton_copula_cdf",
    "clayton_tail_dependence",
    "fit_copula_from_tau",
    "frank_copula_cdf",
    "gaussian_copula_cdf",
    "gumbel_copula_cdf",
    "gumbel_tail_dependence",
    "pseudo_observations",
]


def pseudo_observations(data: np.ndarray) -> np.ndarray:
    """Transform empirical data to uniform [0, 1] pseudo-observations via rank transformation.

    Tied observations receive their average rank, and NaNs remain missing rather
    than being assigned an arbitrary order.

    Args:
        data: 1-D or 2-D array of observations.

    Returns:
        Array of normalized ranks in (0, 1), shape matching ``data``.
    """
    arr = np.asarray(data, dtype=float)
    if arr.ndim not in (1, 2):
        raise ValueError("data must be 1-D or 2-D")
    if np.isinf(arr).any():
        raise ValueError("data must not contain infinite values")

    if arr.ndim == 1:
        result = np.full(arr.shape, np.nan, dtype=float)
        valid = ~np.isnan(arr)
        n = int(valid.sum())
        if n:
            result[valid] = rankdata(arr[valid], method="average") / (n + 1.0)
        return result

    result = np.full(arr.shape, np.nan, dtype=float)
    for column in range(arr.shape[1]):
        valid = ~np.isnan(arr[:, column])
        n = int(valid.sum())
        if n:
            result[valid, column] = rankdata(arr[valid, column], method="average") / (n + 1.0)
    return result


def clayton_copula_cdf(u: float | np.ndarray, v: float | np.ndarray, theta: float) -> float | np.ndarray:
    """Evaluate bivariate Clayton copula CDF: C(u, v) = (u^{-theta} + v^{-theta} - 1)^{-1/theta}.

    Args:
        u: Uniform marginal in (0, 1].
        v: Uniform marginal in (0, 1].
        theta: Parameter > 0 (models lower tail dependence).

    Returns:
        Copula CDF value in [0, 1].
    """
    if theta <= 0.0:
        raise ValueError(f"Clayton parameter theta must be strictly positive, got {theta}")
    u_arr = np.asarray(u, dtype=float)
    v_arr = np.asarray(v, dtype=float)
    if np.any((u_arr <= 0.0) | (u_arr > 1.0) | (v_arr <= 0.0) | (v_arr > 1.0)):
        raise ValueError("u and v marginals must be in (0, 1]")

    # Compute in log space so u^{-theta} never overflows for large theta:
    # log(u^{-theta} + v^{-theta} - 1) = logaddexp(a, b) + log1p(-exp(-logaddexp(a, b)))
    a = -theta * np.log(u_arr)
    b = -theta * np.log(v_arr)
    lse = np.logaddexp(a, b)
    log_inner = lse + np.log1p(-np.exp(-lse))
    val = np.exp(-log_inner / theta)
    return float(val) if np.ndim(val) == 0 else val


def clayton_tail_dependence(theta: float) -> dict[str, float]:
    """Calculate upper and lower tail dependence coefficients for Clayton copula.

    Lower: lambda_L = 2^{-1/theta}, Upper: lambda_U = 0.
    """
    if theta <= 0.0:
        raise ValueError(f"theta must be positive, got {theta}")
    return {
        "lambda_lower": float(2.0 ** (-1.0 / theta)),
        "lambda_upper": 0.0,
    }


def gumbel_copula_cdf(u: float | np.ndarray, v: float | np.ndarray, theta: float) -> float | np.ndarray:
    """Evaluate bivariate Gumbel copula CDF: C(u, v) = exp(-((-ln u)^theta + (-ln v)^theta)^{1/theta}).

    Args:
        u: Uniform marginal in (0, 1].
        v: Uniform marginal in (0, 1].
        theta: Parameter >= 1.0 (models upper tail dependence).
    """
    if theta < 1.0:
        raise ValueError(f"Gumbel parameter theta must be >= 1.0, got {theta}")
    u_arr = np.asarray(u, dtype=float)
    v_arr = np.asarray(v, dtype=float)
    if np.any((u_arr <= 0.0) | (u_arr > 1.0) | (v_arr <= 0.0) | (v_arr > 1.0)):
        raise ValueError("u and v marginals must be in (0, 1]")

    # Compute in log space so (-ln u)^theta never underflows for large theta:
    # log((-ln u)^theta + (-ln v)^theta) = logaddexp(theta*log(-log u), theta*log(-log v))
    # A marginal of exactly 1.0 gives log(-log 1) = log(0) = -inf, which
    # logaddexp handles correctly; silence the divide-by-zero warning.
    with np.errstate(divide="ignore", invalid="ignore"):
        a = theta * np.log(-np.log(u_arr))
        b = theta * np.log(-np.log(v_arr))
    val = np.exp(-np.exp(np.logaddexp(a, b) / theta))
    return float(val) if np.ndim(val) == 0 else val


def gumbel_tail_dependence(theta: float) -> dict[str, float]:
    """Calculate upper and lower tail dependence coefficients for Gumbel copula.

    Upper: lambda_U = 2 - 2^{1/theta}, Lower: lambda_L = 0.
    """
    if theta < 1.0:
        raise ValueError(f"theta must be >= 1.0, got {theta}")
    return {
        "lambda_lower": 0.0,
        "lambda_upper": float(2.0 - 2.0 ** (1.0 / theta)),
    }


def frank_copula_cdf(u: float | np.ndarray, v: float | np.ndarray, theta: float) -> float | np.ndarray:
    """Evaluate bivariate Frank copula CDF: C(u, v) = -1/theta * ln(1 + (exp(-theta*u) - 1)*(exp(-theta*v) - 1)/(exp(-theta) - 1))."""
    if theta == 0.0:
        raise ValueError("Frank parameter theta must be non-zero (theta=0 is independence)")
    u_arr = np.asarray(u, dtype=float)
    v_arr = np.asarray(v, dtype=float)
    if np.any((u_arr <= 0.0) | (u_arr > 1.0) | (v_arr <= 0.0) | (v_arr > 1.0)):
        raise ValueError("u and v marginals must be in (0, 1]")

    # The naive form breaks at both ends of the parameter range, so neither
    # sign keeps it. For theta > 0 it cancels catastrophically (num/den -> -1,
    # log(0) -> -inf); for theta < 0 every factor is positive but
    # (e^{|theta|u} - 1)(e^{|theta|v} - 1) overflows to inf from
    # |theta| ~ 355, which is the same failure the positive branch was fixed
    # for and just as reachable (Kendall tau -> -1 is a real regime).
    if theta > 0:
        s = np.minimum(u_arr, v_arr)
        t = np.maximum(u_arr, v_arr)
        # inner = 1 + e^{-th(t-s)} - e^{-th t} - e^{-th(1-s)} written as a sum
        # of two POSITIVE terms via expm1. Spelled with plain exp it is a
        # 1+1-1-1 cancellation as theta -> 0: at theta=1e-6 it kept ~6 digits,
        # and the 1/theta factor below multiplied that error by 1e6 (C(0.3,0.7)
        # came out 0.20974 against the independence limit 0.21, breaking the
        # Frechet lower bound).
        inner = -(
            np.expm1(-theta * t)
            + np.exp(-theta * (t - s)) * np.expm1(-theta * (1.0 - t))
        )
        log_num = -theta * s + np.log(inner)
        log_den = np.log(-np.expm1(-theta))
        val = -(1.0 / theta) * (log_num - log_den)
    else:
        # phi = -theta > 0. Every term is positive here, so the ratio needs no
        # cancellation guard — only its logarithm, computed with
        # log(e^{phi x} - 1) = phi x + log1p(-e^{-phi x}):
        #   log r = log(e^{phi u} - 1) + log(e^{phi v} - 1) - log(e^{phi} - 1)
        #   C     = log(1 + r) / phi = logaddexp(0, log r) / phi
        phi = -theta
        log_num = (
            phi * u_arr
            + np.log(-np.expm1(-phi * u_arr))
            + phi * v_arr
            + np.log(-np.expm1(-phi * v_arr))
        )
        log_den = phi + np.log(-np.expm1(-phi))
        val = np.logaddexp(0.0, log_num - log_den) / phi
    return float(val) if np.ndim(val) == 0 else val


def gaussian_copula_cdf(u: float, v: float, rho: float) -> float:
    """Evaluate bivariate Gaussian copula CDF."""
    if not (-1.0 < rho < 1.0):
        raise ValueError(f"rho must be strictly in (-1.0, 1.0), got {rho}")
    if not (0.0 < u <= 1.0 and 0.0 < v <= 1.0):
        raise ValueError("u and v must be in (0, 1]")

    from scipy.stats import multivariate_normal

    z1 = float(norm.ppf(u))
    z2 = float(norm.ppf(v))
    cov = [[1.0, rho], [rho, 1.0]]
    # Near-perfect valid correlations can be numerically rank deficient under
    # SciPy's tolerance. This covariance remains positive semidefinite.
    val = multivariate_normal.cdf(
        [z1, z2], mean=[0.0, 0.0], cov=cov, allow_singular=True
    )
    return float(val)


def fit_copula_from_tau(tau: float, family: Literal["clayton", "gumbel", "gaussian"]) -> dict[str, float]:
    """Calibrate copula parameter from Kendall's rank correlation tau.

    Args:
        tau: Kendall's tau in (-1.0, 1.0).
        family: 'clayton', 'gumbel', or 'gaussian'.

    Returns:
        dict with keys:
            * ``family`` (str)
            * ``theta`` or ``rho`` (float)
            * ``tau`` (float)
    """
    fam = family.strip().lower()
    if fam == "clayton":
        if tau <= 0.0 or tau >= 1.0:
            raise ValueError("Clayton copula requires tau in (0, 1)")
        theta = float(2.0 * tau / (1.0 - tau))
        tail = clayton_tail_dependence(theta)
        return {"family": "clayton", "theta": theta, "tau": tau, **tail}
    elif fam == "gumbel":
        if tau < 0.0 or tau >= 1.0:
            raise ValueError("Gumbel copula requires tau in [0, 1)")
        theta = float(1.0 / (1.0 - tau)) if tau < 1.0 else 1.0
        tail = gumbel_tail_dependence(theta)
        return {"family": "gumbel", "theta": theta, "tau": tau, **tail}
    elif fam == "gaussian":
        if not (-1.0 < tau < 1.0):
            raise ValueError("Gaussian copula requires tau in (-1, 1)")
        # Greiner's relation: rho = sin(pi/2 * tau)
        rho = float(math.sin(math.pi * 0.5 * tau))
        # sin rounds to an exact endpoint for some valid interior tau values.
        # Preserve the strict open interval required by gaussian_copula_cdf.
        if abs(rho) == 1.0:
            rho = math.nextafter(rho, 0.0)
        return {"family": "gaussian", "rho": rho, "tau": tau, "lambda_lower": 0.0, "lambda_upper": 0.0}
    else:
        raise ValueError(f"Unsupported family: {family}")