Skip to content

"Vibe-Trading: Your Personal Trading Agent"

7.7 KB
Raw Blame
"""Market microstructure signals: VPIN, Roll's effective spread, and Amihud illiquidity.

Implements institutional market microstructure indicators:
  1. Volume-Synchronized Probability of Toxicity (VPIN - Easley et al. 2012)
  2. Roll's (1984) effective bid-ask spread estimator from serial covariance
  3. Amihud's (2002) price impact / illiquidity ratio
  4. Kyle's (1985) price impact lambda
"""

from __future__ import annotations

import math
from typing import Sequence

import numpy as np
import pandas as pd

__all__ = [
    "amihud_illiquidity",
    "kyles_lambda",
    "roll_effective_spread",
    "vpin",
]


def roll_effective_spread(prices: Sequence[float] | np.ndarray | pd.Series) -> float:
    """Calculate Roll's (1984) effective spread estimator from serial price changes.

    Roll's model: s = 2 * sqrt(-cov(ΔP_t, ΔP_{t-1})) if cov < 0, else 0.0.

    Args:
        prices: Sequence of transaction or closing prices.

    Returns:
        Estimated effective dollar spread (non-negative float).

    Raises:
        ValueError: Fewer than 4 prices, or a price that is NaN or infinite.
            A non-finite price used to come back as a ``0.0`` spread.
    """
    p = np.asarray(prices, dtype=float)
    if len(p) < 4:
        raise ValueError(
            "prices sequence must have at least 4 points to compute serial covariance"
        )
    if not np.isfinite(p).all():
        raise ValueError("prices must contain only finite values")
    dp = np.diff(p)
    dp_t = dp[1:]
    dp_t_minus_1 = dp[:-1]
    cov = float(np.cov(dp_t, dp_t_minus_1)[0, 1])
    if cov < 0.0:
        return float(2.0 * math.sqrt(-cov))
    return 0.0


def amihud_illiquidity(
    returns: Sequence[float] | np.ndarray | pd.Series,
    dollar_volumes: Sequence[float] | np.ndarray | pd.Series,
) -> float:
    """Calculate Amihud's (2002) illiquidity ratio: mean(|R_t| / DollarVolume_t).

    Measures the average price response per dollar of trading volume.

    Args:
        returns: Array of asset returns (decimal).
        dollar_volumes: Array of traded dollar volumes (> 0).

    Returns:
        Amihud illiquidity metric (positive float). Rows whose return or volume
        is NaN or infinite, or whose volume is not positive, are dropped; NaN
        when no row is left.

    Raises:
        ValueError: Empty inputs or mismatched shapes.
    """
    r = np.asarray(returns, dtype=float)
    v = np.asarray(dollar_volumes, dtype=float)
    if r.shape != v.shape or len(r) == 0:
        raise ValueError(
            "returns and dollar_volumes must be non-empty and have matching shapes"
        )
    valid_mask = (v > 0.0) & np.isfinite(r) & np.isfinite(v)
    if not np.any(valid_mask):
        return float("nan")
    ratios = np.abs(r[valid_mask]) / v[valid_mask]
    return float(np.mean(ratios))


def kyles_lambda(
    price_changes: Sequence[float] | np.ndarray | pd.Series,
    signed_order_flow: Sequence[float] | np.ndarray | pd.Series,
) -> float:
    """Estimate Kyle's (1985) price impact coefficient lambda from linear regression.

    ΔP_t = alpha + lambda * OrderFlow_t + epsilon_t

    Fits with an intercept, per the estimation procedure this implements
    (market-microstructure skill: "Regress ΔP = α + λ × OrderFlow"). Signed
    order flow is rarely mean-zero over a real window, and forcing the fit
    through the origin then biases the slope by alpha * mean(flow) / var(flow).

    Args:
        price_changes: Array of price differences ΔP_t.
        signed_order_flow: Array of signed trade volumes (+ for buy, - for sell).

    Returns:
        Kyle's lambda price impact slope; ``0.0`` when the order flow does not
        vary (all zero, or one constant value), where no slope is identified.

    Raises:
        ValueError: Mismatched shapes, fewer than 2 observations, or a value
            that is NaN or infinite.
    """
    dp = np.asarray(price_changes, dtype=float)
    flow = np.asarray(signed_order_flow, dtype=float)
    if dp.shape != flow.shape or len(dp) < 2:
        raise ValueError(
            "price_changes and signed_order_flow must match with >= 2 observations"
        )
    if not np.isfinite(dp).all() or not np.isfinite(flow).all():
        raise ValueError(
            "price_changes and signed_order_flow must contain only finite values"
        )
    flow_centered = flow - flow.mean()
    denom = float(np.sum(flow_centered**2))
    if denom == 0.0:
        return 0.0
    return float(np.sum(flow_centered * (dp - dp.mean())) / denom)


def vpin(
    buy_volume: Sequence[float] | np.ndarray,
    sell_volume: Sequence[float] | np.ndarray,
    bucket_size: float,
    n_buckets: int = 50,
) -> np.ndarray:
    """Compute Volume-Synchronized Probability of Toxicity (VPIN - Easley et al. 2012).

    VPIN = sum_{i=t-N+1}^t |V_B,i - V_S,i| / (N * V)
    aggregating trade volume into standardized constant-volume buckets of size V.

    Args:
        buy_volume: Array of buy trade volumes per time bar.
        sell_volume: Array of sell trade volumes per time bar.
        bucket_size: Standardized volume bucket size V (> 0).
        n_buckets: Number of volume buckets N in rolling window (default=50).

    Returns:
        1-D ndarray of VPIN values in [0, 1] for completed volume buckets.

    Raises:
        ValueError: Mismatched or empty volumes, a volume that is negative, NaN
            or infinite, or a ``bucket_size`` / ``n_buckets`` that is not
            positive.
    """
    vb = np.asarray(buy_volume, dtype=float)
    vs = np.asarray(sell_volume, dtype=float)
    if vb.shape != vs.shape or len(vb) == 0:
        raise ValueError(
            "buy_volume and sell_volume must have matching non-empty shapes"
        )
    if not np.isfinite(vb).all() or not np.isfinite(vs).all():
        raise ValueError("buy_volume and sell_volume must contain only finite values")
    if np.any(vb < 0.0) or np.any(vs < 0.0):
        raise ValueError("buy_volume and sell_volume must be non-negative")
    if not np.isfinite(bucket_size) or bucket_size <= 0.0:
        raise ValueError(f"bucket_size must be positive, got {bucket_size}")
    if n_buckets <= 0:
        raise ValueError(f"n_buckets must be positive, got {n_buckets}")

    bucket_imbalances: list[float] = []
    curr_buy = 0.0
    curr_sell = 0.0

    for b, s in zip(vb, vs):
        rem_b = float(b)
        rem_s = float(s)

        while (rem_b + rem_s) > 0.0:
            curr_filled = curr_buy + curr_sell
            space = bucket_size - curr_filled
            total_bar = rem_b + rem_s

            if total_bar <= space:
                curr_buy += rem_b
                curr_sell += rem_s
                rem_b = 0.0
                rem_s = 0.0
            else:
                frac_b = rem_b / total_bar
                frac_s = rem_s / total_bar
                take_b = space * frac_b
                take_s = space * frac_s

                curr_buy += take_b
                curr_sell += take_s
                rem_b -= take_b
                rem_s -= take_s

            # Completion tolerance must scale with the volume unit. An absolute
            # epsilon admitted unfinished fractional-volume buckets.
            filled = curr_buy + curr_sell
            if filled >= bucket_size or math.isclose(
                filled, bucket_size, rel_tol=1e-12, abs_tol=0.0
            ):
                bucket_imbalances.append(abs(curr_buy - curr_sell))
                curr_buy = 0.0
                curr_sell = 0.0

    if not bucket_imbalances:
        return np.array([], dtype=float)

    imbalances = pd.Series(bucket_imbalances)
    rolling_imb = imbalances.rolling(window=n_buckets, min_periods=1).sum()
    denom = (
        pd.Series(range(1, len(bucket_imbalances) + 1)).clip(upper=n_buckets)
        * bucket_size
    )
    vpin_series = rolling_imb / denom
    return np.clip(vpin_series.to_numpy(), 0.0, 1.0)