feat(market): market-model abnormal returns with CLM intervals; shared bootstrap helpers in pfs.event_study
All checks were successful
CI / lint (push) Successful in 31s
CI / test (push) Successful in 4m1s
CI / notebooks-smoke (push) Successful in 1m25s
Deploy / changes (push) Successful in 13s
Infra CI / notebooks (push) Successful in 1m6s
Infra CI / zotero (push) Successful in 16s
Infra CI / docs (push) Successful in 1m16s
Infra CI / api (push) Successful in 1m13s
Infra CI / bcda (push) Successful in 2m23s
Infra CI / mc (push) Successful in 15s
Deploy / notebooks (push) Has been skipped
Deploy / zotero (push) Has been skipped
Deploy / docs (push) Has been skipped
Infra CI / llm (push) Successful in 57s
Deploy / api (push) Successful in 1m17s
Deploy / bcda (push) Successful in 1m48s
Deploy / mc (push) Has been skipped
Deploy / llm (push) Successful in 1m25s
Deploy / report (push) Successful in 13s
Renovate / renovate (push) Successful in 2m2s
LLM Golden / llm-golden (push) Successful in 23m11s

This commit is contained in:
kert
2026-11-16 22:27:37 -05:00
parent fe52e513f9
commit 82246dcc58
5 changed files with 525 additions and 8 deletions

244
src/market/abnormal.py Normal file
View File

@@ -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),
)

View File

@@ -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,

View File

@@ -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

View File

@@ -18,6 +18,7 @@ MODULES = [
"market.districts",
"market.footprint",
"market.events",
"market.abnormal",
]
_PROBE = """

View File

@@ -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 {