169 lines
6.6 KiB
Markdown
169 lines
6.6 KiB
Markdown
# Institutional-Grade Options Flow Analytics
|
|
|
|
This document describes the institutional-grade enhancements to the options flow pipeline.
|
|
|
|
## Overview
|
|
|
|
The pipeline has been refactored to convert static retail-style flow detection into dynamic, dealer-aware, time-sequenced signals suitable for intraday momentum and 1-5 day swing trades.
|
|
|
|
## New Analytics Modules
|
|
|
|
### 1. Relative Premium Scoring (`relative_premium_scorer.py`)
|
|
|
|
**Purpose**: Replace static premium filter (minPremium = $80K) with context-aware relative scoring.
|
|
|
|
**New Fields**:
|
|
- `premium_zscore`: Z-score of premium relative to 20-day rolling window per ticker
|
|
- `premium_percentile_intraday`: Percentile rank within same-day flow
|
|
- `relative_premium_score`: Composite score (0-100) combining z-score, intraday percentile, and median normalization
|
|
|
|
**Usage**: Premium of $80K might be significant for AAPL but noise for TSLA. This module computes relative significance.
|
|
|
|
### 2. Signal Component Scoring (`signal_component_scorer.py`)
|
|
|
|
**Purpose**: Convert binary badge logic (💎 ⭐ 🟢 🔴) into continuous numeric signal components.
|
|
|
|
**New Fields**:
|
|
- `aggression_score`: Measures trade aggression (ITM premiums, ask-side trades)
|
|
- `size_concentration_score`: Measures size concentration (single large trade vs many small ones)
|
|
- `repeat_trade_velocity`: Measures repeat trade frequency (urgency building)
|
|
- `strike_clustering_score`: Measures strike clustering (laddering patterns)
|
|
- `signal_strength`: Composite score = 0.30 * aggression + 0.30 * size_concentration + 0.20 * repeat_velocity + 0.20 * strike_clustering
|
|
|
|
**Note**: Badges remain display-only. Signal strength is computed from components.
|
|
|
|
### 3. Tier-0 Noise Rejection (`noise_rejector.py`)
|
|
|
|
**Purpose**: Reject low-quality signals before enrichment to reduce processing overhead.
|
|
|
|
**New Fields**:
|
|
- `early_noise_reject`: Boolean flag indicating if signal should be rejected as noise
|
|
|
|
**Rejection Criteria**:
|
|
- Single isolated trade (no repeat activity within 30 minutes)
|
|
- Far OTM weekly lottos (>15% OTM with <7 days to expiry)
|
|
- Delta-adjusted premium below threshold (<$50K)
|
|
|
|
### 4. Time-Sequenced Flow Analysis (`time_sequenced_analyzer.py`)
|
|
|
|
**Purpose**: Analyze flow patterns over time to detect urgency, distribution, and continuation.
|
|
|
|
**New Fields**:
|
|
- `flow_acceleration`: Change in premium per minute (Δ premium / minute)
|
|
- `time_between_hits`: Average time between consecutive trades (minutes)
|
|
- `follow_on_ratio`: Fraction of trades in same direction after initial trade (0-1)
|
|
- `strike_laddering_detected`: Boolean indicating sequential strike accumulation
|
|
|
|
**Interpretation**:
|
|
- Escalating premium + decreasing time gaps = urgency
|
|
- Flat premium + widening gaps = distribution
|
|
|
|
### 5. Intent Classification (`intent_classifier.py`)
|
|
|
|
**Purpose**: Replace naive direction (BULL/BEAR) with nuanced volatility and hedging intent.
|
|
|
|
**New Fields**:
|
|
- `delta_exposure`: Delta exposure (contracts * delta * 100 * spot_price)
|
|
- `gamma_exposure`: Gamma exposure (contracts * gamma * 100 * spot_price^2)
|
|
- `volatility_intent`: Enum (LONG_VOL, SHORT_VOL, DIRECTIONAL, HEDGE_UNWIND)
|
|
|
|
**Note**: Direction (BULL/BEAR) becomes secondary metadata.
|
|
|
|
### 6. Dealer-Aware Flow Context (`dealer_flow_context.py`)
|
|
|
|
**Purpose**: Track dealer hedging pressure and gamma exposure.
|
|
|
|
**New Fields**:
|
|
- `net_gamma_exposure_per_symbol`: Sum of gamma exposures for symbol (positive = long gamma, negative = short gamma)
|
|
- `gamma_flip_proximity`: Proximity to gamma flip point (-1 to 1)
|
|
- `dealer_hedge_pressure_score`: Dealer hedge pressure score (0-100)
|
|
|
|
**Usage**: Validates flow continuation, flow reversals, and gamma squeeze setups.
|
|
|
|
### 7. Market Regime Detection (`market_regime_detector.py`)
|
|
|
|
**Purpose**: Identify market regime to gate trade signal generation.
|
|
|
|
**New Fields**:
|
|
- `market_regime`: Enum (TREND, RANGE, HIGH_VOL_EVENT)
|
|
|
|
**Trade Signal Gating**:
|
|
- Trend → continuation bias
|
|
- Range → fade or vol-sell bias
|
|
- Event → volatility expansion bias
|
|
|
|
### 8. Flow Decay & Reversal Validation (`flow_decay_validator.py`)
|
|
|
|
**Purpose**: Validate flow decay/reversal signals with anchors.
|
|
|
|
**New Fields**:
|
|
- `flow_state`: Enum (ACTIONABLE, INFORMATIONAL)
|
|
|
|
**Validation Criteria**: Flow decay/reversal is actionable ONLY IF:
|
|
- Premium contracts (relative_premium_score >= 60)
|
|
- Dealer hedge pressure decreases
|
|
- Price fails near VWAP / opening range / key level
|
|
- Otherwise marked as INFORMATIONAL
|
|
|
|
### 9. Institutional Confidence Metrics (`institutional_confidence.py`)
|
|
|
|
**Purpose**: Calculate confidence scores for institutional flow signals.
|
|
|
|
**New Fields**:
|
|
- `confidence_score`: Overall confidence score (0-100)
|
|
- `institutional_likelihood`: Likelihood flow is institutional (0-1)
|
|
- `dealer_pain_level`: Dealer pain level (0-100)
|
|
- `expected_move_vs_implied`: Expected move vs implied move ratio
|
|
|
|
## Integration
|
|
|
|
All modules are integrated into the main processing pipeline in `main.py`:
|
|
|
|
1. Basic flow processing (normalization, badges, rocket score)
|
|
2. Price context enrichment
|
|
3. Alert matching
|
|
4. **Institutional analytics pipeline** (NEW):
|
|
- Tier-0 noise rejection
|
|
- Relative premium scoring
|
|
- Signal component scoring
|
|
- Time-sequenced analysis
|
|
- Intent classification
|
|
- Dealer flow context
|
|
- Market regime detection
|
|
- Flow decay validation
|
|
- Confidence metrics
|
|
5. Filtering (premium, relative premium, badges, direction)
|
|
6. Output formatting
|
|
|
|
## Filtering Changes
|
|
|
|
**Before**:
|
|
- Static premium filter: `premium_num > 80000`
|
|
- Badge requirements: 🟢/🔴 + 💎 + ⭐
|
|
|
|
**After**:
|
|
- Static premium filter: `premium_num > min_premium` (still applied)
|
|
- **Relative premium filter**: `relative_premium_score >= 60.0` (NEW)
|
|
- **Noise rejection filter**: `early_noise_reject == False` (NEW)
|
|
- Badge requirements: 🟢/🔴 + 💎 + ⭐ (still applied, but badges are now display-only)
|
|
|
|
## API Response
|
|
|
|
All new fields are included in the API response. The response maintains backward compatibility - existing fields remain unchanged, new fields are additive.
|
|
|
|
## Design Philosophy
|
|
|
|
1. **Flow represents pressure, not prediction**: Signals indicate who is forced to act next (dealers hedging)
|
|
2. **Institutions trade urgency and forced hedging**: Focus on dealer pain and gamma exposure
|
|
3. **Fewer, higher-quality signals > more alerts**: Noise rejection and relative premium filtering reduce false positives
|
|
4. **Every signal must answer**: "Who is forced to act next?"
|
|
|
|
## Success Criteria
|
|
|
|
If implemented correctly:
|
|
- Signal count decreases (noise filtered out)
|
|
- Average signal quality increases (relative premium, signal strength)
|
|
- False positives reduce (noise rejection, dealer context validation)
|
|
- Trades align with intraday momentum and short-term swing horizons (time-sequenced analysis)
|
|
|