Skip to content

"Vibe-Trading: Your Personal Trading Agent"

21.3 KB
Raw Blame
"""Tests for src.quantlib.eventstudy.

Two-sided throughout: a sample with no event effect must NOT be called
significant, and a sample with an injected effect must be.
"""

import numpy as np
import pandas as pd
import pytest

from src.quantlib.eventstudy import (
    DEFAULT_ESTIMATION_GAP,
    MIN_ESTIMATION_OBSERVATIONS,
    estimate_market_model,
    event_study,
)


def _panel(n_days=400, n_symbols=30, seed=0, beta=1.2, alpha=0.0002, vol=0.012):
    """Build a return frame generated by a known market model."""
    rng = np.random.default_rng(seed)
    index = pd.date_range("2020-01-01", periods=n_days, freq="B")
    market = pd.Series(rng.normal(0.0003, 0.009, n_days), index=index, name="market")
    symbols = [f"S{i:02d}" for i in range(n_symbols)]
    data = {
        s: alpha + beta * market.to_numpy() + rng.normal(0.0, vol, n_days)
        for s in symbols
    }
    return pd.DataFrame(data, index=index), market


# --- market model fitting ---


def test_market_model_recovers_known_alpha_and_beta():
    rng = np.random.default_rng(5)
    market = rng.normal(0.0, 0.01, 500)
    asset = 0.0005 + 1.4 * market + rng.normal(0.0, 0.002, 500)
    fit = estimate_market_model(asset, market)
    assert fit.beta == pytest.approx(1.4, abs=0.03)
    assert fit.alpha == pytest.approx(0.0005, abs=0.0003)
    assert fit.residual_std == pytest.approx(0.002, rel=0.15)
    assert fit.observations == 500


def test_market_adjusted_model_fixes_beta_at_one():
    rng = np.random.default_rng(6)
    market = rng.normal(0.0, 0.01, 200)
    asset = market + rng.normal(0.0, 0.001, 200)
    fit = estimate_market_model(asset, market, model="market_adjusted")
    assert fit.alpha == 0.0
    assert fit.beta == 1.0


def test_mean_adjusted_model_ignores_the_market():
    rng = np.random.default_rng(7)
    market = rng.normal(0.0, 0.01, 200)
    asset = 0.001 + rng.normal(0.0, 0.003, 200)
    fit = estimate_market_model(asset, market, model="mean_adjusted")
    assert fit.beta == 0.0
    assert fit.alpha == pytest.approx(asset.mean())


def test_short_estimation_window_is_an_error():
    with pytest.raises(ValueError, match="at least"):
        estimate_market_model(np.zeros(10), np.zeros(10))


def test_constant_market_leaves_beta_unidentified():
    rng = np.random.default_rng(8)
    with pytest.raises(ValueError, match="not identified"):
        estimate_market_model(rng.normal(0, 0.01, 100), np.zeros(100))


def test_unknown_model_rejected():
    with pytest.raises(ValueError, match="model must be one of"):
        estimate_market_model(np.zeros(100), np.zeros(100), model="cape")


# --- the null: no effect must not be called significant ---


def test_no_effect_sample_is_not_significant():
    returns, market = _panel(seed=101)
    events = [(s, returns.index[250]) for s in returns.columns]
    result = event_study(returns, market, events, event_window=(-2, 2))

    assert abs(result.caar_total) < 0.01
    assert result.bmp_p_value > 0.05
    assert result.t_p_value > 0.05


# --- an injected effect must be found, at the right size ---


def test_injected_event_day_jump_is_recovered_in_caar():
    returns, market = _panel(seed=202)
    event_row = 250
    jump = 0.05
    returns = returns.copy()
    returns.iloc[event_row] += jump

    events = [(s, returns.index[event_row]) for s in returns.columns]
    result = event_study(returns, market, events, event_window=(-2, 2))

    assert result.caar_total == pytest.approx(jump, abs=0.01)
    assert result.aar.loc[0] == pytest.approx(jump, abs=0.01)
    # Days either side of the event carry no injected effect.
    assert abs(result.aar.loc[-1]) < 0.01
    assert abs(result.aar.loc[1]) < 0.01
    assert result.bmp_p_value < 0.01
    assert result.patell_p_value < 0.01
    assert result.t_p_value < 0.01


def _clm_car_std_error(asset_est, market_est, market_window, model):
    """CAR standard error from the full prediction-error covariance matrix.

    Written as matrix algebra (Campbell, Lo & MacKinlay eq. 4.4.14), not the
    closed-form sums the module uses, so it checks the formula independently:
    ``Var(CAR) = s^2 * 1'(I + X*(X'X)^-1 X*')1`` with ``X`` the estimation
    design matrix and ``X*`` the event-window one.
    """
    n, days = len(asset_est), len(market_window)
    if model == "market":
        design = np.column_stack([np.ones(n), market_est])
        window = np.column_stack([np.ones(days), market_window])
        dof = n - 2
    elif model == "mean_adjusted":
        design = np.ones((n, 1))
        window = np.ones((days, 1))
        dof = n - 1
    else:
        resid = asset_est - market_est
        return float(np.sqrt(np.sum(resid**2) / n) * np.sqrt(days))
    coef, *_ = np.linalg.lstsq(design, asset_est, rcond=None)
    s2 = float(np.sum((asset_est - design @ coef) ** 2) / dof)
    covariance = s2 * (np.eye(days) + window @ np.linalg.inv(design.T @ design) @ window.T)
    return float(np.sqrt(np.ones(days) @ covariance @ np.ones(days)))


@pytest.mark.parametrize("model", ["market", "mean_adjusted", "market_adjusted"])
def test_car_std_error_includes_the_covariance_of_the_shared_prediction_error(model):
    """#1466: the window's days share one estimation error, so their variances do not just add."""
    returns, market = _panel(n_symbols=3, seed=31)
    event_row = 300
    result = event_study(
        returns,
        market,
        [("S01", returns.index[event_row])],
        event_window=(-5, 5),
        estimation_window=40,
        model=model,
    )
    outcome = result.events[0]
    est_end = event_row - 5 - DEFAULT_ESTIMATION_GAP
    expected = _clm_car_std_error(
        returns["S01"].iloc[est_end - 40 : est_end].to_numpy(),
        market.iloc[est_end - 40 : est_end].to_numpy(),
        market.iloc[event_row - 5 : event_row + 6].to_numpy(),
        model,
    )
    assert outcome.car_std_error == pytest.approx(expected, rel=1e-10)


@pytest.mark.parametrize("model", ["market", "mean_adjusted"])
def test_standardised_cars_are_unit_variance_under_the_null(model):
    """With a short estimation window the missing covariance inflated Var(z) to ~1.4.

    What remains is the t-distribution correction for an estimated residual
    variance, (dof) / (dof - 2), about 1.08 at 30 observations.
    """
    rng = np.random.default_rng(1466)
    n_rows, n_events, window = 120, 4000, 30
    index = pd.date_range("2020-01-01", periods=n_rows, freq="B")
    market = pd.Series(rng.normal(0.0, 0.012, n_rows), index=index)
    returns = pd.DataFrame(
        rng.normal(0.0, 0.01, (n_rows, n_events)),
        index=index,
        columns=[f"S{i}" for i in range(n_events)],
    )
    rows = rng.integers(window + DEFAULT_ESTIMATION_GAP + 5, n_rows - 6, n_events)
    result = event_study(
        returns,
        market,
        [(f"S{i}", index[row]) for i, row in enumerate(rows)],
        event_window=(-5, 5),
        estimation_window=window,
        model=model,
    )
    z = np.array([o.standardised_car for o in result.events])
    dof = window - (2 if model == "market" else 1)
    assert np.var(z) == pytest.approx(dof / (dof - 2), abs=0.07)


def test_car_is_exactly_the_sum_of_the_abnormal_returns():
    returns, market = _panel(seed=303)
    events = [(s, returns.index[250]) for s in returns.columns[:5]]
    result = event_study(returns, market, events, event_window=(-3, 3))
    for outcome in result.events:
        assert outcome.car == pytest.approx(float(outcome.abnormal_returns.sum()))


def test_caar_is_the_running_sum_of_aar():
    returns, market = _panel(seed=304)
    events = [(s, returns.index[250]) for s in returns.columns]
    result = event_study(returns, market, events, event_window=(-4, 4))
    assert result.caar.to_numpy() == pytest.approx(np.cumsum(result.aar.to_numpy()))
    assert result.caar_total == pytest.approx(result.caar.iloc[-1])


# --- the estimation window must not see the event ---


def test_estimation_window_excludes_the_event_window():
    returns, market = _panel(seed=404)
    event_row = 250
    contaminated = returns.copy()
    # A violent, sustained move confined to the event window. If the estimation
    # window overlapped it, beta would be dragged and the abnormal return would
    # shrink toward zero -- the study would under-report its own finding.
    contaminated.iloc[event_row - 5 : event_row + 6] += 0.25

    events = [(s, returns.index[event_row]) for s in returns.columns]
    clean = event_study(returns, market, events, event_window=(-5, 5))
    dirty = event_study(contaminated, market, events, event_window=(-5, 5))

    # The fitted betas are unchanged: the estimation window never saw the shock.
    for a, b in zip(clean.events, dirty.events):
        assert a.fit.beta == pytest.approx(b.fit.beta, rel=1e-12)
    # And the whole injected move shows up as abnormal return: 11 days x 0.25.
    assert dirty.caar_total == pytest.approx(clean.caar_total + 11 * 0.25, abs=0.02)


def test_estimation_gap_is_respected():
    returns, market = _panel(seed=405)
    event_row = 250
    contaminated = returns.copy()
    # Poison only the gap rows, which sit between the estimation and event
    # windows and must be used by neither.
    gap_start = event_row - 5 - DEFAULT_ESTIMATION_GAP
    contaminated.iloc[gap_start : event_row - 5] += 0.30

    events = [(s, returns.index[event_row]) for s in returns.columns]
    clean = event_study(returns, market, events, event_window=(-5, 5))
    dirty = event_study(contaminated, market, events, event_window=(-5, 5))

    for a, b in zip(clean.events, dirty.events):
        assert a.fit.beta == pytest.approx(b.fit.beta, rel=1e-12)
        assert a.car == pytest.approx(b.car, rel=1e-12)


# --- BMP vs Patell under event-induced variance ---


def test_bmp_survives_event_induced_variance_where_patell_over_rejects():
    # The null is true: no mean effect. But the event window is three times as
    # volatile as the estimation window, which is what real events do. Patell
    # assumes event-window variance equals estimation-window variance and
    # therefore rejects far too often; BMP takes the cross-sectional variance of
    # the standardised values and holds its size.
    rng = np.random.default_rng(909)
    patell_rejections = 0
    bmp_rejections = 0
    trials = 60

    for trial in range(trials):
        n_days, n_symbols = 320, 40
        index = pd.date_range("2020-01-01", periods=n_days, freq="B")
        market = pd.Series(rng.normal(0.0, 0.008, n_days), index=index)
        event_row = 250
        data = {}
        for i in range(n_symbols):
            noise = rng.normal(0.0, 0.01, n_days)
            noise[event_row - 2 : event_row + 3] *= 3.0  # variance, not mean
            data[f"S{i:02d}"] = 1.0 * market.to_numpy() + noise
        frame = pd.DataFrame(data, index=index)
        events = [(s, index[event_row]) for s in frame.columns]
        result = event_study(frame, market, events, event_window=(-2, 2))
        patell_rejections += result.patell_p_value < 0.05
        bmp_rejections += result.bmp_p_value < 0.05

    patell_rate = patell_rejections / trials
    bmp_rate = bmp_rejections / trials
    assert bmp_rate <= 0.15, f"BMP should hold its size, got {bmp_rate:.2%}"
    assert patell_rate > bmp_rate, (
        f"Patell should over-reject under event-induced variance "
        f"(patell {patell_rate:.2%} vs bmp {bmp_rate:.2%})"
    )


def test_patell_variance_uses_each_models_own_degrees_of_freedom():
    # The Patell correction is df/(df-2) with df = n - k, k being the
    # parameters the fitted model actually estimated: 2 for "market", 0 for
    # "market_adjusted", 1 for "mean_adjusted". n/(n-2) and (n-1)/(n-3) are
    # both smaller than (n-2)/(n-4), so using the "market" k=2 for every model
    # (the bug) over-stated the variance correction and left |patell_z|
    # slightly too small: the corrected |z| lands strictly above it.
    from src.quantlib.eventstudy import NORMAL_RETURN_MODELS, _MODEL_PARAMETER_COUNT

    assert set(_MODEL_PARAMETER_COUNT) == set(NORMAL_RETURN_MODELS)
    returns, market = _panel(seed=42)
    events = [(f"S{i:02d}", returns.index[300]) for i in range(returns.shape[1])]

    for model, k in (("market_adjusted", 0), ("mean_adjusted", 1)):
        result = event_study(
            returns,
            market,
            events,
            event_window=(-1, 1),
            estimation_window=MIN_ESTIMATION_OBSERVATIONS,
            model=model,
        )
        n = result.events[0].fit.observations
        assert all(o.fit.observations == n for o in result.events)

        df_correct = n - k
        correction_correct = df_correct / (df_correct - 2)
        correction_market_k = (n - 2) / (n - 4)
        assert correction_correct != pytest.approx(correction_market_k)
        assert correction_correct < correction_market_k

        scar_sum = sum(
            o.standardised_car for o in result.events if np.isfinite(o.standardised_car)
        )
        n_scored = sum(1 for o in result.events if np.isfinite(o.standardised_car))
        expected_patell_z = scar_sum / np.sqrt(n_scored * correction_correct)
        assert result.patell_z == pytest.approx(expected_patell_z)
        bugged_patell_z = scar_sum / np.sqrt(n_scored * correction_market_k)
        assert abs(result.patell_z) > abs(bugged_patell_z)


# --- dropped events are reported, never silently skipped ---


def test_unknown_symbol_is_dropped_with_a_reason():
    returns, market = _panel(seed=505)
    events = [("S00", returns.index[250]), ("NOPE", returns.index[250])]
    result = event_study(returns, market, events)
    assert len(result.events) == 1
    assert result.dropped == (("NOPE", returns.index[250], "symbol not in returns frame"),)


def test_event_too_early_for_an_estimation_window_is_dropped():
    returns, market = _panel(seed=506)
    events = [("S00", returns.index[5])]
    with pytest.raises(ValueError, match="no event could be measured"):
        event_study(returns, market, events)


def test_event_window_running_past_the_frame_is_dropped():
    returns, market = _panel(seed=507)
    events = [("S00", returns.index[250]), ("S01", returns.index[-2])]
    result = event_study(returns, market, events, event_window=(-1, 5))
    reasons = [r for _, _, r in result.dropped]
    assert reasons == ["event window runs past the frame end"]


def test_non_finite_event_window_is_dropped():
    returns, market = _panel(seed=508)
    returns = returns.copy()
    returns.iloc[250, returns.columns.get_loc("S00")] = np.nan
    events = [("S00", returns.index[250]), ("S01", returns.index[250])]
    result = event_study(returns, market, events, event_window=(-1, 1))
    assert [s for s, _, _ in result.dropped] == ["S00"]
    assert [o.symbol for o in result.events] == ["S01"]


# --- event-date anchoring ---


def test_non_trading_event_date_anchors_to_previous_session():
    returns, market = _panel(seed=509)
    friday_pos = next(
        pos for pos in range(200, len(returns) - 1) if returns.index[pos].weekday() == 4
    )
    friday = returns.index[friday_pos]
    saturday = friday + pd.Timedelta(days=1)
    assert saturday not in returns.index

    returns = returns.copy()
    returns.iloc[friday_pos, returns.columns.get_loc("S00")] += 0.10
    returns.iloc[friday_pos + 1, returns.columns.get_loc("S00")] -= 0.20

    result = event_study(
        returns,
        market,
        [("S00", saturday)],
        event_window=(0, 0),
        model="mean_adjusted",
    )

    outcome = result.events[0]
    expected = returns.loc[friday, "S00"] - outcome.fit.alpha
    assert outcome.event_date == friday
    assert outcome.abnormal_returns.loc[0] == pytest.approx(expected)


def test_exact_event_date_remains_on_that_session():
    returns, market = _panel(seed=510)
    event_date = returns.index[250]

    result = event_study(
        returns,
        market,
        [("S00", event_date)],
        event_window=(0, 0),
    )

    assert result.events[0].event_date == event_date


def test_event_before_first_session_is_dropped():
    returns, market = _panel(seed=511)
    events = [
        ("S00", returns.index[250]),
        ("S01", returns.index[0] - pd.Timedelta(days=1)),
    ]

    result = event_study(returns, market, events)

    assert [outcome.symbol for outcome in result.events] == ["S00"]
    assert result.dropped[0][2] == "event date is before the frame starts"


def test_event_after_last_session_is_dropped():
    returns, market = _panel(seed=512)
    events = [
        ("S00", returns.index[250]),
        ("S01", returns.index[-1] + pd.Timedelta(days=1)),
    ]

    result = event_study(returns, market, events)

    assert [outcome.symbol for outcome in result.events] == ["S00"]
    assert result.dropped[0][2] == "event date is after the frame ends"


# --- clustering disclosure ---


def test_shared_event_dates_are_flagged():
    returns, market = _panel(seed=606)
    same_day = returns.index[250]
    events = [(s, same_day) for s in returns.columns[:4]]
    result = event_study(returns, market, events)
    assert result.shared_event_dates == (same_day,)


def test_distinct_event_dates_are_not_flagged():
    returns, market = _panel(seed=607)
    events = [
        ("S00", returns.index[240]),
        ("S01", returns.index[250]),
        ("S02", returns.index[260]),
    ]
    result = event_study(returns, market, events)
    assert result.shared_event_dates == ()


# --- input validation ---


def test_inverted_event_window_rejected():
    returns, market = _panel(seed=707)
    with pytest.raises(ValueError, match="start must be <= end"):
        event_study(returns, market, [("S00", returns.index[250])], event_window=(3, -3))


def test_negative_estimation_gap_rejected():
    returns, market = _panel(seed=708)
    with pytest.raises(ValueError, match="estimation_gap must be >= 0"):
        event_study(returns, market, [("S00", returns.index[250])], estimation_gap=-1)


def test_too_short_estimation_window_rejected():
    returns, market = _panel(seed=709)
    with pytest.raises(ValueError, match="estimation_window must be at least"):
        event_study(
            returns,
            market,
            [("S00", returns.index[250])],
            estimation_window=MIN_ESTIMATION_OBSERVATIONS - 1,
        )


def test_empty_events_rejected():
    returns, market = _panel(seed=710)
    with pytest.raises(ValueError, match="events is empty"):
        event_study(returns, market, [])


def test_market_missing_labels_is_an_error():
    returns, market = _panel(seed=711)
    with pytest.raises(ValueError, match="missing"):
        event_study(returns, market.iloc[10:], [("S00", returns.index[250])])


def test_post_event_only_window_is_allowed():
    returns, market = _panel(seed=712)
    events = [(s, returns.index[250]) for s in returns.columns]
    result = event_study(returns, market, events, event_window=(1, 5))
    assert result.event_window == (1, 5)
    assert list(result.aar.index) == [1, 2, 3, 4, 5]

# --- non-parametric tests (Corrado rank and Cowan sign) ---


def test_corrado_rank_and_cowan_sign_detect_positive_reaction():
    returns, market = _panel(seed=801)
    event_day = returns.index[250]
    # Inject positive abnormal returns in the event window for all assets
    returns_injected = returns.copy()
    for col in returns_injected.columns:
        returns_injected.loc[event_day, col] += 0.05

    events = [(s, event_day) for s in returns.columns]
    result = event_study(returns_injected, market, events, event_window=(0, 2))

    assert result.positive_car_fraction == pytest.approx(1.0)
    assert result.cowan_sign_z > 2.0
    assert result.cowan_sign_p_value < 0.05
    assert result.corrado_rank_z > 2.0
    assert result.corrado_rank_p_value < 0.05


def test_corrado_rank_sk_spans_the_combined_estimation_and_event_days():
    from scipy.stats import rankdata

    returns, market = _panel(seed=804)
    position = 250
    returns.iloc[position] += 0.03
    events = [(s, returns.index[position]) for s in returns.columns]
    result = event_study(
        returns, market, events, event_window=(0, 2), estimation_window=120, estimation_gap=10
    )

    est_rows = slice(position - 10 - 120, position - 10)
    deviations = []
    for outcome in result.events:
        fit = outcome.fit
        residuals = (
            returns[outcome.symbol].iloc[est_rows] - (fit.alpha + fit.beta * market.iloc[est_rows])
        ).to_numpy()
        combined = np.concatenate([residuals, outcome.abnormal_returns.to_numpy()])
        deviations.append(rankdata(combined) - (len(combined) + 1) / 2)
    mean_dev = np.vstack(deviations).mean(axis=0)
    s_k = np.sqrt(np.mean(mean_dev**2))
    expected_z = mean_dev[-3:].sum() / (np.sqrt(3) * s_k)

    assert result.corrado_rank_z == pytest.approx(expected_z, rel=1e-9)


def test_corrado_rank_and_cowan_sign_single_event_safe_nan():
    returns, market = _panel(seed=802)
    event_day = returns.index[250]
    events = [("S00", event_day)]
    result = event_study(returns, market, events, event_window=(0, 2))

    assert np.isnan(result.corrado_rank_z)
    assert np.isnan(result.corrado_rank_p_value)
    assert np.isnan(result.cowan_sign_z)
    assert np.isnan(result.cowan_sign_p_value)
    assert 0.0 <= result.positive_car_fraction <= 1.0


def test_corrado_rank_and_cowan_sign_tolerate_nan_in_estimation_period():
    returns, market = _panel(seed=803)
    event_day = returns.index[250]
    # Insert scattered NaNs in the pre-event estimation window
    returns.iloc[50, 0] = np.nan
    market.iloc[60] = np.nan
    events = [(s, event_day) for s in returns.columns]
    result = event_study(returns, market, events, event_window=(0, 2))
    assert np.isfinite(result.positive_car_fraction)