diff --git a/src/market/abnormal.py b/src/market/abnormal.py new file mode 100644 index 0000000..2653118 --- /dev/null +++ b/src/market/abnormal.py @@ -0,0 +1,244 @@ +"""Market-model abnormal returns. + +One firm or portfolio series, factored by SPY and optionally XLV. +``returns`` is that series (date → simple return). ``factors`` is +ticker → series. Offsets count trading days on ``calendar``. The +event-window variance is Campbell, Lo and MacKinlay. A single CAR +uses a normal interval; a pooled mean uses the shared percentile +bootstrap. Every result is an association, not a causal estimate. +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +from datetime import date + +from pfs.event_study import bootstrap_draws, percentile_interval + +MODELS = {"market": ("SPY",), "sector": ("XLV",), "two-factor": ("SPY", "XLV")} +EST = (-250, -31) +MIN_EST = 120 +WINDOWS = ((0, 0), (-1, 1), (0, 1), (-5, 5), (0, 10)) +_ASSOC = "association, not a causal estimate" +_Z = 1.96 + + +@dataclass(frozen=True) +class Fit: + alpha: float + betas: tuple[float, ...] + sigma2: float + n: int + xtx_inv: tuple[tuple[float, ...], ...] + + +@dataclass(frozen=True) +class Car: + event_id: str + unit: str + ticker: str + model: str + window: tuple[int, int] + car: float | None + se: float | None + ci_low: float | None + ci_high: float | None + n_est: int + n_members: int + caveats: tuple[str, ...] + + +@dataclass(frozen=True) +class Pooled: + unit: str + model: str + window: tuple[int, int] + mean_car: float | None + ci_low: float | None + ci_high: float | None + n_events: int + caveats: tuple[str, ...] + + +def _columns(xs: Sequence) -> list[list[float]]: + """One factor is a series of numbers; several factors are a series of series.""" + if xs and isinstance(xs[0], (int, float)): + return [[float(v) for v in xs]] + return [[float(v) for v in col] for col in xs] + + +def fit(y: Sequence[float], xs: Sequence) -> Fit | None: + """OLS with an intercept. None when there are no degrees of freedom.""" + import numpy as np + + cols = _columns(xs) + n = len(y) + k = 1 + len(cols) + if n <= k: + return None + y_arr = np.asarray(y, dtype=float) + design = np.column_stack([np.ones(n), *cols]) + beta, *_ = np.linalg.lstsq(design, y_arr, rcond=None) + resid = y_arr - design @ beta + xtx_inv = np.linalg.inv(design.T @ design) + return Fit( + alpha=float(beta[0]), + betas=tuple(float(b) for b in beta[1:]), + sigma2=float(resid @ resid) / (n - k), + n=n, + xtx_inv=tuple(tuple(float(v) for v in row) for row in xtx_inv), + ) + + +def car_from_arrays( + fitted: Fit, y_win: Sequence[float], xs_win: Sequence +) -> tuple[float, float]: + """Cumulative abnormal return and its CLM standard error.""" + import numpy as np + + cols = _columns(xs_win) + y_arr = np.asarray(y_win, dtype=float) + length = len(y_arr) + design = np.column_stack([np.ones(length), *cols]) + coef = np.asarray([fitted.alpha, *fitted.betas], dtype=float) + car = float((y_arr - design @ coef).sum()) + iota = np.ones(length) + xtx_inv = np.asarray(fitted.xtx_inv, dtype=float) + leverage = float(iota @ design @ xtx_inv @ design.T @ iota) + se = float(np.sqrt(fitted.sigma2 * (length + leverage))) + return car, se + + +def _dates(calendar: Sequence[date], d0: date, lo: int, hi: int) -> list[date]: + i0 = list(calendar).index(d0) + return [calendar[i] for i in range(i0 + lo, i0 + hi + 1) if 0 <= i < len(calendar)] + + +def _complete( + days: Sequence[date], + returns: Mapping[date, float], + factors: Mapping[str, Mapping[date, float]], + names: Sequence[str], +) -> bool: + return all( + day in returns and all(day in factors.get(name, {}) for name in names) + for day in days + ) + + +def _result( + *, + event_id: str, + unit: str, + ticker: str, + model: str, + window: tuple[int, int], + car: float | None, + se: float | None, + n_est: int, + caveats: list[str], +) -> Car: + lo = hi = None + if car is not None and se is not None: + lo, hi = car - _Z * se, car + _Z * se + return Car( + event_id=event_id, + unit=unit, + ticker=ticker, + model=model, + window=window, + car=car, + se=se, + ci_low=lo, + ci_high=hi, + n_est=n_est, + n_members=1, + caveats=(*caveats, _ASSOC), + ) + + +def event_car( + returns: Mapping[date, float], + factors: Mapping[str, Mapping[date, float]], + calendar: Sequence[date], + d0: date, + *, + model: str = "market", + est: tuple[int, int] = EST, + window: tuple[int, int] = (-1, 1), + min_est: int = MIN_EST, + event_id: str = "", + unit: str = "", + ticker: str = "", + other_events: Sequence[date] = (), +) -> Car: + """CAR for one series. Missing estimation days shrink n; a missing window day drops the CAR.""" + names = MODELS[model] + est_days = _dates(calendar, d0, *est) + win_days = _dates(calendar, d0, *window) + caveats: list[str] = [] + covered = set(est_days) + for day in other_events: + if day in covered: + caveats.append(f"estimation window overlaps event on {day}") + if model in ("sector", "two-factor"): + caveats.append("sector index absorbs sector-wide effects") + + ys: list[float] = [] + cols: list[list[float]] = [[] for _ in names] + for day in est_days: + if not _complete((day,), returns, factors, names): + continue + ys.append(float(returns[day])) + for j, name in enumerate(names): + cols[j].append(float(factors[name][day])) + n = len(ys) + common = dict( + event_id=event_id, + unit=unit, + ticker=ticker, + model=model, + window=window, + n_est=n, + caveats=caveats, + ) + if n < min_est: + caveats.append(f"short estimation window (n={n})") + return _result(car=None, se=None, **common) + if not _complete(win_days, returns, factors, names): + caveats.append("missing returns in event window") + return _result(car=None, se=None, **common) + + fitted = fit(ys, cols[0] if len(names) == 1 else cols) + assert fitted is not None + y_win = [float(returns[day]) for day in win_days] + if len(names) == 1: + xs_win: Sequence = [float(factors[names[0]][day]) for day in win_days] + else: + xs_win = [[float(factors[name][day]) for day in win_days] for name in names] + car, se = car_from_arrays(fitted, y_win, xs_win) + return _result(car=car, se=se, **common) + + +def pooled(cars: Sequence[Car]) -> Pooled: + """Mean of the non-None CARs. The bootstrap interval needs two events.""" + head = cars[0] + vals = [c.car for c in cars if c.car is not None] + n = len(vals) + mean = sum(vals) / n if n else None + lo = hi = None + if n >= 2: + lo, hi = percentile_interval(bootstrap_draws(vals)) + caveats = ["fewer than 5 events"] if n < 5 else [] + caveats.append(_ASSOC) + return Pooled( + unit=head.unit, + model=head.model, + window=head.window, + mean_car=mean, + ci_low=lo, + ci_high=hi, + n_events=n, + caveats=tuple(caveats), + ) diff --git a/src/pfs/event_study.py b/src/pfs/event_study.py index 44d1fa9..f0c648d 100644 --- a/src/pfs/event_study.py +++ b/src/pfs/event_study.py @@ -16,6 +16,8 @@ notebook says so and the chat only links here. windows(year, available, pre, post) → (pre_years, post_years) log_change(series, pre, post) → log ratio of window means + bootstrap_draws(values) → resampled means + percentile_interval(draws) → 95% percentile interval did_effect(treated, controls, …) → Effect pre_post(series, year, …) → PrePost (single-series, no controls) utilization_panel(con, code, year, kind) → Panel over pfs.utilization @@ -112,6 +114,22 @@ def log_change( return math.log(b / a) +def bootstrap_draws( + values: Sequence[float], *, n_boot: int = _BOOT, seed: int = _SEED +) -> list[float]: + """Resampled means of *values*. The same seed always yields the same draws.""" + rng = random.Random(seed) + n = len(values) + return [sum(rng.choice(values) for _ in range(n)) / n for _ in range(n_boot)] + + +def percentile_interval(draws: Sequence[float]) -> tuple[float, float]: + """95% interval at ``sorted[int(0.025·B)]`` and ``sorted[int(0.975·B) - 1]``.""" + ordered = sorted(draws) + b = len(ordered) + return ordered[int(0.025 * b)], ordered[int(0.975 * b) - 1] + + def did_effect( treated: Mapping[int, float], controls: Mapping[str, Mapping[int, float]], @@ -137,14 +155,9 @@ def did_effect( t_change - c_change if t_change is not None and c_change is not None else None ) lo = hi = None - if effect is not None and len(changes) >= 2: - rng = random.Random(_SEED) - n = len(changes) - draws = sorted( - t_change - sum(rng.choice(changes) for _ in range(n)) / n - for _ in range(_BOOT) - ) - lo, hi = draws[int(0.025 * _BOOT)], draws[int(0.975 * _BOOT) - 1] + if effect is not None and len(changes) >= 2 and t_change is not None: + draws = [t_change - m for m in bootstrap_draws(changes)] + lo, hi = percentile_interval(draws) return Effect( code=code, year=year, diff --git a/tests/market/test_abnormal.py b/tests/market/test_abnormal.py new file mode 100644 index 0000000..e5fb432 --- /dev/null +++ b/tests/market/test_abnormal.py @@ -0,0 +1,224 @@ +"""market.abnormal — market-model CARs, CLM intervals, pooled bootstrap.""" + +from __future__ import annotations + +from datetime import date, timedelta + +import pytest + +from market.abnormal import Car, car_from_arrays, event_car, fit, pooled + +_ASSOC = "association, not a causal estimate" + + +def _weekdays(d0: date, n_before: int, n_after: int) -> list[date]: + back: list[date] = [] + day = d0 + while len(back) < n_before: + day -= timedelta(days=1) + if day.weekday() < 5: + back.append(day) + fwd: list[date] = [] + day = d0 + while len(fwd) < n_after: + day += timedelta(days=1) + if day.weekday() < 5: + fwd.append(day) + return [*reversed(back), d0, *fwd] + + +def _market(cal: list[date]) -> tuple[dict[date, float], dict[str, dict[date, float]]]: + """Firm equals SPY. SPY varies, so the market model is identified.""" + spy: dict[date, float] = {} + firm: dict[date, float] = {} + for i, day in enumerate(cal): + spy[day] = ((i % 5) - 2) * 0.01 + firm[day] = spy[day] + return firm, {"SPY": spy} + + +def _car(value: float | None, **kw: object) -> Car: + return Car( + event_id="e", + unit=kw.get("unit", "U"), + ticker="T", + model=kw.get("model", "market"), + window=kw.get("window", (-1, 1)), + car=value, + se=None if value is None else 0.01, + ci_low=None if value is None else value - 0.02, + ci_high=None if value is None else value + 0.02, + n_est=200, + n_members=1, + caveats=(_ASSOC,), + ) + + +def test_fit_recovers_alpha_beta(): + x = [i - 65 for i in range(130)] + y = [0.001 + 1.5 * xi for xi in x] + fitted = fit(y, x) + assert fitted.alpha == pytest.approx(0.001, abs=1e-12) + assert fitted.betas[0] == pytest.approx(1.5, abs=1e-12) + assert fitted.sigma2 == pytest.approx(0.0, abs=1e-12) + assert fit([1.0, 2.0], [1.0, 2.0]) is None + + +def test_car_variance_clm(): + fitted = fit([-0.9, -0.2, 1.1], [-1.0, 0.0, 1.0]) + assert fitted.alpha == pytest.approx(0.0, abs=1e-9) + assert fitted.betas[0] == pytest.approx(1.0, abs=1e-9) + assert fitted.sigma2 == pytest.approx(0.06) + car, se = car_from_arrays(fitted, [1.5, 2.0], [1.0, 2.0]) + assert car == pytest.approx(0.5) + assert se == pytest.approx(0.6855654600, abs=1e-9) + + d0 = date(2026, 1, 8) + cal = [ + date(2026, 1, 5), + date(2026, 1, 6), + date(2026, 1, 7), + d0, + date(2026, 1, 9), + date(2026, 1, 10), + ] + xs = { + date(2026, 1, 5): -1.0, + date(2026, 1, 6): 0.0, + date(2026, 1, 7): 1.0, + date(2026, 1, 9): 1.0, + date(2026, 1, 10): 2.0, + } + ys = { + date(2026, 1, 5): -0.9, + date(2026, 1, 6): -0.2, + date(2026, 1, 7): 1.1, + date(2026, 1, 9): 1.5, + date(2026, 1, 10): 2.0, + } + out = event_car( + ys, + {"SPY": xs}, + cal, + d0, + est=(-3, -1), + window=(1, 2), + min_est=3, + ) + assert out.car == pytest.approx(0.5) + assert out.se == pytest.approx(0.6855654600, abs=1e-9) + assert out.ci_low == pytest.approx(0.5 - 1.96 * 0.6855654600) + assert out.ci_high == pytest.approx(0.5 + 1.96 * 0.6855654600) + assert out.n_est == 3 + assert _ASSOC in out.caveats + + +def test_car_window_sum(): + d0 = date(2026, 11, 9) + cal = _weekdays(d0, 250, 2) + firm, factors = _market(cal) + firm[d0] = factors["SPY"][d0] + 0.02 + day = event_car(firm, factors, cal, d0, window=(0, 0)) + three = event_car(firm, factors, cal, d0, window=(-1, 1)) + assert day.car == pytest.approx(0.02) + assert three.car == pytest.approx(0.02) + assert _ASSOC in day.caveats and _ASSOC in three.caveats + + +def test_short_estimation_window_caveat(): + d0 = date(2026, 11, 9) + # 101 trading days fall in the default window; one has no firm return. + cal = _weekdays(d0, 131, 2) + firm, factors = _market(cal) + del firm[cal[cal.index(d0) - 131]] + out = event_car(firm, factors, cal, d0) + assert out.car is None and out.n_est == 100 + assert "short estimation window (n=100)" in out.caveats + assert _ASSOC in out.caveats + + +def test_missing_window_return(): + d0 = date(2026, 11, 9) + cal = _weekdays(d0, 250, 2) + firm, factors = _market(cal) + del firm[date(2026, 11, 10)] + out = event_car(firm, factors, cal, d0, window=(-1, 1)) + assert out.car is None + assert "missing returns in event window" in out.caveats + assert _ASSOC in out.caveats + + +def test_offsets_count_trading_days(): + d0 = date(2026, 11, 9) + cal = _weekdays(d0, 250, 3) + firm, factors = _market(cal) + shocks = { + date(2026, 11, 5): 0.50, # trading offset -2, outside (-1, 1) + date(2026, 11, 6): 0.01, # Friday + date(2026, 11, 9): 0.02, + date(2026, 11, 10): 0.04, # Tuesday + date(2026, 11, 11): 0.50, # trading offset +2, outside + } + for day, shock in shocks.items(): + firm[day] = factors["SPY"][day] + shock + out = event_car(firm, factors, cal, d0, window=(-1, 1)) + assert out.window == (-1, 1) + assert out.car == pytest.approx(0.07) + assert _ASSOC in out.caveats + + +def test_two_factor_and_sector_models(): + x1 = [((i % 5) - 2) * 0.01 for i in range(130)] + x2 = [((i % 7) - 3) * 0.01 for i in range(130)] + y = [0.2 * a + 0.3 * b for a, b in zip(x1, x2, strict=True)] + assert len(fit(y, [x1, x2]).betas) == 2 + assert len(fit(x2, x2).betas) == 1 + + d0 = date(2026, 11, 9) + cal = _weekdays(d0, 250, 2) + spy: dict[date, float] = {} + xlv: dict[date, float] = {} + firm: dict[date, float] = {} + for i, day in enumerate(cal): + spy[day] = ((i % 5) - 2) * 0.01 + xlv[day] = ((i % 7) - 3) * 0.01 + firm[day] = 0.2 * spy[day] + 0.3 * xlv[day] + factors = {"SPY": spy, "XLV": xlv} + sector = event_car(firm, factors, cal, d0, model="sector") + two = event_car(firm, factors, cal, d0, model="two-factor") + note = "sector index absorbs sector-wide effects" + assert note in sector.caveats and note in two.caveats + assert sector.model == "sector" and two.model == "two-factor" + assert _ASSOC in sector.caveats and _ASSOC in two.caveats + + +def test_estimation_overlap_caveat(): + d0 = date(2026, 11, 9) + cal = _weekdays(d0, 250, 2) + inside = cal[cal.index(d0) - 40] + outside = cal[cal.index(d0) - 10] + assert inside == date(2026, 9, 14) + assert outside == date(2026, 10, 26) + firm, factors = _market(cal) + out = event_car(firm, factors, cal, d0, other_events=(inside, outside)) + assert f"estimation window overlaps event on {inside}" in out.caveats + assert f"estimation window overlaps event on {outside}" not in out.caveats + assert out.car is not None + assert _ASSOC in out.caveats + + +def test_pooled_bootstrap_deterministic(): + cars = [_car(0.01), _car(0.03), _car(-0.02), _car(None)] + first = pooled(cars) + second = pooled(cars) + assert (first.ci_low, first.ci_high) == (second.ci_low, second.ci_high) + assert first.ci_low is not None and first.ci_high is not None + assert first.mean_car == pytest.approx((0.01 + 0.03 - 0.02) / 3) + assert first.n_events == 3 + assert first.unit == "U" and first.model == "market" + assert "fewer than 5 events" in first.caveats + assert _ASSOC in first.caveats + one = pooled([_car(0.05)]) + assert one.ci_low is None and one.ci_high is None + assert one.mean_car == pytest.approx(0.05) + assert one.n_events == 1 diff --git a/tests/market/test_imports.py b/tests/market/test_imports.py index 63ff3f1..1278652 100644 --- a/tests/market/test_imports.py +++ b/tests/market/test_imports.py @@ -18,6 +18,7 @@ MODULES = [ "market.districts", "market.footprint", "market.events", + "market.abnormal", ] _PROBE = """ diff --git a/tests/pfs/test_event_study.py b/tests/pfs/test_event_study.py index c62f4f6..64385a0 100644 --- a/tests/pfs/test_event_study.py +++ b/tests/pfs/test_event_study.py @@ -10,10 +10,13 @@ import pytest from pfs.codetables import ExposureRow, ensure_tables, write_exposures from pfs.event_study import ( + _BOOT, Effect, PrePost, + bootstrap_draws, did_effect, log_change, + percentile_interval, pre_post, utilization_panel, windows, @@ -46,6 +49,38 @@ class TestLogChange: ) # zero pre → undefined +def test_percentile_interval_indices(): + # 499..0, so a missing sort cannot land on (12, 486). + assert percentile_interval(list(range(499, -1, -1))) == (12, 486) + + +def test_bootstrap_draws_reproducible(): + values = [0.1, -0.2, 0.4, 0.0, 0.3] + assert bootstrap_draws(values) == bootstrap_draws(values) + small = bootstrap_draws(values, n_boot=4, seed=1) + assert small == bootstrap_draws(values, n_boot=4, seed=1) + assert len(bootstrap_draws(values)) == _BOOT + assert len(small) == 4 + assert min(values) <= min(small) <= max(small) <= max(values) + + +def test_did_effect_interval_unchanged_after_refactor(): + """Literals recorded from did_effect before bootstrap_draws was extracted.""" + treated = {2015: 100.0, 2016: 100.0, 2017: 150.0, 2018: 150.0} + controls = { + f"C{i:04d}": { + 2015: 100.0, + 2016: 100.0, + 2017: 100.0 * (1 + 0.1 + 0.01 * (i % 5)), + 2018: 100.0 * (1 + 0.1 + 0.01 * (i % 5)), + } + for i in range(10) + } + effect = did_effect(treated, controls, 2017, code="X", kind="k", outcome="o") + assert effect.ci_low == 0.2842075623165553 + assert effect.ci_high == 0.29939166235566306 + + class TestDidEffect: def _controls(self, n=20, growth=0.1): return {