A regime-aware framework for measuring information propagation, residual underreaction, and reversal across financial markets.
The research question is simple but demanding: do related securities absorb common market, sector, and cross-asset shocks at different speeds, and does the shortfall between a model-implied response and an observed response predict subsequent market-neutral returns? This repository tests that mechanism with leakage-safe rolling factor models, a transparent Shock Coherence filter, chronological validation, next-open execution, costs, risk controls, and reproducible reports.
Result discipline: committed code and deterministic synthetic fixtures demonstrate mechanics, not alpha. The disclosed ETF model is a falsification baseline and should not be interpreted as a profitable strategy.
| Test | Reported result | Interpretation |
|---|---|---|
| Combined public baseline | Rank IC −0.00592; approximately flat before costs | No useful cross-sectional forecasting signal |
| Transaction-cost scenarios | Performance becomes materially negative after costs | The disclosed signal is not economically viable |
| Within-date randomized signal | Empirical two-sided p = 0.299 | The observed result is not unusual relative to randomized ranks |
| Standalone Absorption Gap | No robust predictive evidence | Residual gaps may reflect noise or reversal rather than diffusion |
| Shock-Coherence conditioning | No robust improvement | Market-state filtering does not rescue the public baseline |
| Machine-learning extensions | No robust out-of-sample improvement | Additional model complexity does not establish public alpha |
The table summarises the corrected public specification over 24 ETFs from 4 January 2010 through 28 August 2026. The complete methodology, diagnostics, and limitations are archived in the Zenodo working paper. Citation metadata is available in CITATION.cff, and the author record is linked through ORCID.
flowchart LR
A[Adjusted public OHLCV] --> B[Validation + Parquet cache]
B --> C[Return decomposition]
C --> D[Rolling factor model<br/>estimated through t-1]
D --> E[Absorption Gap]
C --> F[Shock Coherence]
E --> G[Propagation / reversal research]
F --> G
G --> H[Cross-sectional ranking]
H --> I[Portfolio construction]
I --> J[Open t+1 execution]
J --> K[Costs + risk + attribution]
K --> L[Walk-forward evaluation + report]
A common shock need not reach every related security simultaneously. For asset i, a rolling model estimates the response implied by traded factors. The Absorption Gap is expected common-factor move − observed move; its standardized, shock-direction-adjusted form is positive when an asset has underreacted in the common shock's direction. Shock Coherence asks whether the event is broad, large, confirmed by volume and intraday structure, and consistent across related assets. Because SC is identical for every asset on a date, the public baseline uses it only as a positive-state activation filter; it does not change within-date cross-sectional ranks.
The critical falsification is reversal: a gap may be idiosyncratic noise rather than delayed propagation. The package therefore separates predictive diagnostics from executable portfolio economics and includes simple statistical and nonlinear research models without treating classifier accuracy as trading performance.
Information through close t may form a signal after that close. Target weights become executable only at open t+1. A one-day strategy return is open t+1 → open t+2. Rolling betas, volatility, medians, and robust z-scores used on t end at t−1. Tests enforce these conventions; there is no close-t signal/close-t execution shortcut.
The default universe is a fixed collection of liquid market, sector, rates, credit, commodity, dollar, and international ETFs. Yahoo adjusted OHLCV is cached locally in ignored Parquet files; cache metadata must match the requested date range and adjustment mode. Optional equities come from configs/universe_equities.csv; without point-in-time constituents their results are explicitly not survivorship-free. PointInTimeUniverse accepts dated membership data when available. FRED is optional and never required; macro observations must be lagged or vintage-aware.
The default model is shockdiff.signals.baseline:BaselineAlphaModel, with signal = signed_AG when SC > 0 and zero otherwise. It is intentionally simple, fully disclosed, and useful for testing the research mechanism. In the current daily ETF sample its ranking is weak and frequent rebalancing makes the net result materially worse. The repository therefore presents it as an auditable negative result and a foundation for prospective research—not as deployable alpha.
Main evaluation is chronological. Expanding walk-forward folds support purging and embargo when forward labels overlap. The complete historical sample has already been inspected, so no genuinely untouched historical holdout remains; fold results are temporal diagnostics, not fresh validation. The transparent portfolio ranks every active cross-section, takes long and short tails, requires both sides, targets dollar neutrality and 1.0 gross exposure when the position cap permits it, and applies hard caps. Optional periodic rebalancing is available only as an implementation diagnostic. A convex constructor adds risk and turnover penalties but never replaces the simple baseline.
Costs are proportional to turnover with 0/2/5/10/20/50 bps scenarios. Optional square-root participation impact and ADV20 are explicitly liquidity/capacity proxies—not exchange execution or institutional capacity estimates. A candidate signal that disappears under modest costs is not economically robust.
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
# Offline, deterministic integration run (not empirical evidence)
shockdiff pipeline run --config configs/default.yaml --synthetic
# Public Yahoo run
shockdiff pipeline run --config configs/etf_research.yamlUseful commands are make test, make lint, make typecheck, make sample, make data, and make all. The CLI also provides data download, data validate, features build, research run, backtest run, and report build.
- A model-implied gap can represent residual reversal rather than diffusion.
- Daily bars hide intraday ordering, bid/ask spreads, market impact, queueing, and borrow constraints.
- Static ETF and equity lists retain product-selection and survivorship limitations.
- Yahoo adjustments and volume are public-data approximations; corporate-action jumps are flagged.
- Cross-sectional dependence, overlapping labels, multiple comparisons, and regime changes reduce effective sample size.
- Broad-factor proxies can leave omitted-factor beta in residuals.
- Parameter stability matters more than an isolated optimum; a narrow peak is treated as fragile.
- Better classifier AUC need not produce better rank IC, turnover, or net P&L.
Negative and conditional findings are valid outcomes. The framework never labels backtests as live performance and never asserts profitable alpha without net untouched-holdout evidence.
src/shockdiff/data: providers, cache, validation, universes, deterministic fixturessrc/shockdiff/featuresandfactors: timed transformations and rolling modelssrc/shockdiff/signalsandmodels: public alpha contract and propagation researchsrc/shockdiff/portfolio,backtest,risk: construction, execution, costs, accountingsrc/shockdiff/validation: chronological splits, purging, HAC and block bootstrapsrc/shockdiff/reporting: consistent figures and generated reportsnotebooks: three executable tutorials covering data/timing, signal diagnostics, and portfolio costsdocs: architecture, methodology, feature definitions, leakage protocol, and limitationstests: synthetic leakage traps and accounting/constraint tests
Research and educational use only. This repository is not investment advice, an offer, or an execution system.