H1 — Price Absorption: Design & Repository Assessment

Status: frozen design — awaiting go-ahead before implementation.

Question owner: (you)

Scope: H1 only (price absorption). H2–H6 are not implemented here.

Related: reports/spot_cvd_divergence_study.md (completed negative result), reports/spot_cvd_divergence_results.md.

Part A — Repository assessment

A.1 What already exists and is reusable

Data layer (src/quant_lab/data/)

• storage.py — DatasetKey, read_dataset (lazy Parquet scan, date-filtered, predicate push-down), write_partition, monthly partition layout.
• resample.py::resample_bars — canonical OHLCV aggregation; volume, quote_volume, taker_buy_* are summed, timestamp is the bucket open. This is exactly what H1 needs to go 1m→1h.
• sources/binance.py, build.py — resumable bulk downloader/normalizer.
• universe.py — top-N by live volume, is_non_crypto, cross_market_universe.
• cvd.py — volume_delta/cvd construction + monthly partitions.
• validate.py — data-quality report.

Feature layer (src/quant_lab/features/)

• core.py — sma, ema, atr, rsi, vwap, returns, rolling_volume, realized_volatility, zscore, roc, stdev, rolling_max/min, momentum, true_range, price_range + safe_div.
• market.py — volume_delta, cvd, cvd_change, open_interest_change, funding_rate, basis, relative_volume, range_expansion, trade_imbalance.
• compute_features(frame, [FeatureSpec(...)]) registry.

Analytics layer (src/quant_lab/analytics/)

• splits.py — chronological_split, split_by_dates, walk_forward_splits.
• excursions.py::analyze_excursions — post-signal time-to-reversion, max-favourable-move, excursion-to-reversion; close/touch basis. H1 reuses the path-outcome machinery (MFE/MAE-style).
• robustness.py — bootstrap_returns (block bootstrap), monte_carlo_trades, parameter_sensitivity, metrics_from_returns.
• regimes.py — causal trend×vol classifier (classify_regimes, attach_regimes, evaluate_by_regime), shifted one bar.
• confluence.py — signal labelling, design/validate evaluation, enrich_frame (as-of joins of spot/funding/OI), default_filters.
• divergence.py (added this session) — build_divergence_panel plus reusable estimators: pooled_ic, cross_sectional_ic, decile_table, event_study, block_bootstrap_ic (vectorised). H1 reuses these directly.

Reporting / execution

• reporting/report.py (summary.md/json + plots + tearsheet); analytics/* expose to_markdown().
• backtest/ (VectorBT engine, metrics, explicit assumptions). Execution defaults in configs/default.toml: fees 4 bps, slippage 2 bps per side → ~12 bps round-trip.
• CLI quantlab analyze …, thin scripts in scripts/.
• Tests: tests/conftest.py fixtures (bars, small_bars, tmp_root); strong existing emphasis on causality / lookahead tests.

A.2 What does not exist (must be built)

• No swing/pivot detection (relevant to H2, not H1).
• No price-impact / absorption / flow-effectiveness model — H1 is new.
• No rolling price-impact regression or Kyle-lambda / Amihud estimator.
• No regime-conditional regression helper.
• AlphaFlow (Rust) is a separate project and is not present in this repo.

A.3 Data coverage (the binding constraint)

Measured from data/normalized/binance (this repo):

Implication. Any H1 test on the current universe is single-regime, in-sample 2026 and must be labelled exploratory — the same limitation called out in the divergence study. The only genuine multi-regime cross-check is BTCUSDT (2024–2026), and to a lesser extent ETHUSDT. This is stated in every pass/fail claim; we will not assert generality across regimes we did not observe.

A.4 Data caveats carried into H1

• Base vs quote units: H1 works in quote (USDT) units throughout.
• delta = 2*taker_buy_volume − volume; per-bar flow is net taker flow, not the full book — absorption is a proxy, not a proven mechanism.
• Contemporaneous vs predictive: the same-bar price impact is an observable conditioning feature (known at bar close); it must never enter the forward window (start at t+1).
• Missing bars / abnormal volume: drop bars with nulls; normalize flow by trailing activity so outliers are relative, not absolute.
• Tick data is not required and not authorized; 1m bars suffice.

Part B — Frozen H1 specification

B.1 Hypothesis and economic rationale

Question. Does the effectiveness of aggressive flow in moving price carry information about subsequent price behaviour?

H1. When aggressive selling produces unusually little downward price movement (absorption), price subsequently outperforms comparable strong-selling events. Symmetric: absorbed aggressive buying (little upward movement) precedes underperformance.

Rationale (a proxy, not a mechanism). If large aggressive flow moves price much less than a trailing model predicts, resting/passive liquidity likely opposed it. If that passive side is persistent, price should later move against the aggressor. Alternative explanation: low impact simply means low-information flow, which may mean-revert. H1 tests whether the residual is informative, net of volatility, trend and flow magnitude.

Directional definition (fixed).

• Predicted direction d_t = −sign(f_t) (absorbed selling → up; absorbed buying → down).
• Oriented forward return y_t = d_t · fwd_ret_t. H1 predicts y_t > 0 when absorption is high.

B.2 Event definitions and formulas (all causal, trailing only)

Per symbol, on 1h bars (resampled from 1m):

qd_t      = 2 * taker_buy_quote_volume - quote_volume        # signed taker flow, USDT
r_t       = log(close_t / close_{t-1})                        # bar log return
adv_t     = mean(quote_volume, 20)  (trailing, min_periods=20)  # activity scale
f_t       = qd_t / adv_t             (guard: null if adv_t == 0)  # normalized flow

Expected impact (regression-based, not a naive ratio). A rolling OLS of the bar return on normalized flow over a trailing window W (primary W = 720 ≈ 30d), intercept included, using only bars ≤ t:

r_i ≈ alpha_t + beta_t * f_i          for i in (t-W, t]
rhat_t = alpha_t + beta_t * f_t       # expected same-bar impact
s_t    = r_t - rhat_t                 # impact residual (signed surprise)

This replaces the unstable r/qd ratio with a conditional estimate, per the brief. Bars where the denominator would explode are excluded, not divided.

Absorption score (the signal):

A_t = -sign(f_t) * s_t                     # >0 = aggressor absorbed
A_t = A_t / std_W(A)   (trailing std)      # scale-free z-score, per symbol

Strong-flow event: |f_t| ≥ q90(|f|) where q90 is the trailing 90th percentile of |f| over W (self-normalising; no absolute threshold). Primary tests are within strong-flow events; A_t is also tested continuously.

Execution delay. Signals are evaluated at the close of t; all outcomes begin at t+1.

B.3 Required input data

Perp 1m klines for the universe (already on disk for 2026). Columns used: timestamp, open, high, low, close, volume, quote_volume, taker_buy_volume, taker_buy_quote_volume. No spot, funding or OI is required for H1's primary test; funding/OI/regimes are controls, so partial OI coverage (20 symbols) limits only the robustness slice, not the primary test.

B.4 Baselines and matched controls

1. Price-action-only baseline — strong-flow events with no absorption conditioning: unconditional oriented forward return.
2. Flow-only baseline — condition only on |f_t| (and sign(f_t)), ignoring the impact residual. If absorption adds nothing over “big flow”, H1 fails.
3. Matched controls — each absorbed event is compared with non-absorbed strong-flow events matched on trailing buckets of: realized vol, trailing return (trend), |f_t|, and regime label. Pairwise within-cell difference is reported alongside the pooled view.

B.5 Primary outcome and horizon

• Primary: oriented forward return over h = 4h (entry close t+1, exit close t+1+h), pooled across the universe.
• Secondary: MFE/MAE of the oriented return; directional hit rate.
• Robustness horizons: 15m, 1h, 24h, 3d. Reported in full.

B.6 Confounders and leakage

• Mechanical vol dependence — residual is smaller when vol is low; normalize flow and residual by trailing activity/vol; match on realized vol.
• Mean reversion / trend — absorbed events may follow large moves; control and match on trailing return; regime stratification.
• Liquidity — normalize flow by trailing ADV; match on |f|.
• Contemporaneous→predictive — s_t uses only bar t; forward window starts t+1; explicit alignment test.
• Look-ahead in the regression/quantiles — all rolling windows trailing, W/q90 computed from past bars only; causality test on shifted inputs.
• Multiple testing — one primary spec; sweeps reported with Benjamini–Hochberg FDR.

B.7 Statistical evaluation & cost assumptions

• Pooled rank IC of A_t vs y_t (headline), plus within-strong-flow IC.
• Block bootstrap (blocks ≈ horizon) for CIs — respects overlapping windows.
• Decile / quantile monotonicity of y_t across A_t.
• Matched-control paired difference (absorbed − control), with CI.
• Regression: y_t ~ A_t + past_ret + realized_vol + |f_t| + regime FE, clustered by symbol×day; report the A_t coefficient and bootstrap CI.
• Costs: ~12 bps round-trip; a tradable claim must clear it.
• Stability: per-symbol and per-regime tables; chronological design/test.

B.8 Pass/fail criteria (preregistered)

Declare an edge iff ALL hold on the test period:

Anything short of all seven → H0 (no edge). Thresholds frozen before results. No parameter is chosen on the test period.

B.9 Feasibility with existing data

Yes. 1m perp bars (2026) → 1h via resample_bars; rolling OLS and trailing quantiles in Polars/NumPy; estimators reuse analytics/divergence.py. No new data download and no tick data required. The binding limitation is regime breadth (2026 only), which forces the exploratory label.

Part C — Frozen primary specification

C.1 Implementation plan (after approval)

• New module src/quant_lab/analytics/absorption.py: normalized_flow, rolling_impact_model (returns alpha,beta), absorption_signal, strong_flow_events, match_controls, event_outcomes, run_absorption_study.
• Reuse analytics/divergence.py estimators (pooled_ic, decile_table, event_study, block_bootstrap_ic) and analytics/regimes.attach_regimes.
• New tests tests/test_absorption.py: formula correctness, causality (appending future bars must not change past A_t), rolling-OLS equals a hand-computed window, forward-return alignment/no-leakage, synthetic edge and no-edge fixtures.
• New script scripts/absorption_study.py (reproducible CLI); writes reports/cvd_absorption_results.md + machine-readable outputs under experiments/reports/absorption/.
• No existing reports overwritten; no existing research code changed. If a shared helper is needed, it is imported, not duplicated.

Part D — Explicit non-goals

• Not implementing H2–H6 in this pass.
• Not tuning H1 parameters to find a positive result; the sweep is reported whole.
• Not using tick/aggTrade data.
• Not claiming cross-regime generality from a 2026-only sample.

← All reports · source (.md)