orderflow_backtest/docs/modules/metrics.md

# Module: Metrics Calculation System

## Purpose

The metrics calculation system provides high-performance computation of Order Book Imbalance (OBI) and Cumulative Volume Delta (CVD) indicators for cryptocurrency trading analysis. It processes orderbook snapshots and trade data to generate financial metrics with per-snapshot granularity.

## Public Interface

### Classes

#### `Metric` (dataclass)
Represents calculated metrics for a single orderbook snapshot.

```python
@dataclass(slots=True)
class Metric:
    snapshot_id: int        # Reference to source snapshot
    timestamp: int          # Unix timestamp
    obi: float             # Order Book Imbalance [-1, 1]
    cvd: float             # Cumulative Volume Delta
    best_bid: float | None # Best bid price
    best_ask: float | None # Best ask price
```

#### `MetricCalculator` (static class)
Provides calculation methods for financial metrics.

```python
class MetricCalculator:
    @staticmethod
    def calculate_obi(snapshot: BookSnapshot) -> float
    
    @staticmethod
    def calculate_volume_delta(trades: List[Trade]) -> float
    
    @staticmethod  
    def calculate_cvd(previous_cvd: float, volume_delta: float) -> float
    
    @staticmethod
    def get_best_bid_ask(snapshot: BookSnapshot) -> tuple[float | None, float | None]
```

### Functions

#### Order Book Imbalance (OBI) Calculation
```python
def calculate_obi(snapshot: BookSnapshot) -> float:
    """
    Calculate Order Book Imbalance using the standard formula.
    
    Formula: OBI = (Vb - Va) / (Vb + Va)
    Where:
        Vb = Total volume on bid side
        Va = Total volume on ask side
    
    Args:
        snapshot: BookSnapshot containing bids and asks data
        
    Returns:
        float: OBI value between -1 and 1, or 0.0 if no volume
        
    Example:
        >>> snapshot = BookSnapshot(bids={50000.0: OrderbookLevel(...)}, ...)
        >>> obi = MetricCalculator.calculate_obi(snapshot)
        >>> print(f"OBI: {obi:.3f}")
        OBI: 0.333
    """
```

#### Volume Delta Calculation
```python
def calculate_volume_delta(trades: List[Trade]) -> float:
    """
    Calculate Volume Delta for a list of trades.
    
    Volume Delta = Buy Volume - Sell Volume
    - Buy trades (side = "buy"): positive contribution
    - Sell trades (side = "sell"): negative contribution
    
    Args:
        trades: List of Trade objects for specific timestamp
        
    Returns:
        float: Net volume delta (positive = buy pressure, negative = sell pressure)
        
    Example:
        >>> trades = [
        ...     Trade(side="buy", size=10.0, ...),
        ...     Trade(side="sell", size=3.0, ...)
        ... ]
        >>> vd = MetricCalculator.calculate_volume_delta(trades)
        >>> print(f"Volume Delta: {vd}")
        Volume Delta: 7.0
    """
```

#### Cumulative Volume Delta (CVD) Calculation
```python
def calculate_cvd(previous_cvd: float, volume_delta: float) -> float:
    """
    Calculate Cumulative Volume Delta with incremental support.
    
    Formula: CVD_t = CVD_{t-1} + Volume_Delta_t
    
    Args:
        previous_cvd: Previous CVD value (use 0.0 for reset)
        volume_delta: Current volume delta to add
        
    Returns:
        float: New cumulative volume delta value
        
    Example:
        >>> cvd = 0.0  # Starting value
        >>> cvd = MetricCalculator.calculate_cvd(cvd, 10.0)  # First trade
        >>> cvd = MetricCalculator.calculate_cvd(cvd, -5.0)  # Second trade
        >>> print(f"CVD: {cvd}")
        CVD: 5.0
    """
```

## Usage Examples

### Basic OBI Calculation
```python
from models import MetricCalculator, BookSnapshot, OrderbookLevel

# Create sample orderbook snapshot
snapshot = BookSnapshot(
    id=1,
    timestamp=1640995200,
    bids={
        50000.0: OrderbookLevel(price=50000.0, size=10.0, liquidation_count=0, order_count=1),
        49999.0: OrderbookLevel(price=49999.0, size=5.0, liquidation_count=0, order_count=1),
    },
    asks={
        50001.0: OrderbookLevel(price=50001.0, size=3.0, liquidation_count=0, order_count=1),
        50002.0: OrderbookLevel(price=50002.0, size=2.0, liquidation_count=0, order_count=1),
    }
)

# Calculate OBI
obi = MetricCalculator.calculate_obi(snapshot)
print(f"OBI: {obi:.3f}")  # Output: OBI: 0.500
# Explanation: (15 - 5) / (15 + 5) = 10/20 = 0.5
```

### CVD Calculation with Reset
```python
from models import MetricCalculator, Trade

# Simulate trading session
cvd = 0.0  # Reset CVD at session start

# Process trades for first timestamp
trades_t1 = [
    Trade(id=1, trade_id=1.0, price=50000.0, size=8.0, side="buy", timestamp=1000),
    Trade(id=2, trade_id=2.0, price=50001.0, size=3.0, side="sell", timestamp=1000),
]

vd_t1 = MetricCalculator.calculate_volume_delta(trades_t1)  # 8.0 - 3.0 = 5.0
cvd = MetricCalculator.calculate_cvd(cvd, vd_t1)           # 0.0 + 5.0 = 5.0

# Process trades for second timestamp
trades_t2 = [
    Trade(id=3, trade_id=3.0, price=49999.0, size=2.0, side="buy", timestamp=1001),
    Trade(id=4, trade_id=4.0, price=50000.0, size=7.0, side="sell", timestamp=1001),
]

vd_t2 = MetricCalculator.calculate_volume_delta(trades_t2)  # 2.0 - 7.0 = -5.0
cvd = MetricCalculator.calculate_cvd(cvd, vd_t2)           # 5.0 + (-5.0) = 0.0

print(f"Final CVD: {cvd}")  # Output: Final CVD: 0.0
```

### Complete Metrics Processing
```python
from models import MetricCalculator, Metric

def process_snapshot_metrics(snapshot, trades, previous_cvd=0.0):
    """Process complete metrics for a single snapshot."""
    
    # Calculate OBI
    obi = MetricCalculator.calculate_obi(snapshot)
    
    # Calculate volume delta and CVD
    volume_delta = MetricCalculator.calculate_volume_delta(trades)
    cvd = MetricCalculator.calculate_cvd(previous_cvd, volume_delta)
    
    # Extract best bid/ask
    best_bid, best_ask = MetricCalculator.get_best_bid_ask(snapshot)
    
    # Create metric record
    metric = Metric(
        snapshot_id=snapshot.id,
        timestamp=snapshot.timestamp,
        obi=obi,
        cvd=cvd,
        best_bid=best_bid,
        best_ask=best_ask
    )
    
    return metric, cvd

# Usage in processing loop
current_cvd = 0.0
for snapshot, trades in snapshot_trade_pairs:
    metric, current_cvd = process_snapshot_metrics(snapshot, trades, current_cvd)
    # Store metric to database...
```

## Dependencies

### Internal
- `models.BookSnapshot`: Orderbook state data
- `models.Trade`: Individual trade execution data
- `models.OrderbookLevel`: Price level information

### External
- **Python Standard Library**: `typing` for type hints
- **No external packages required**

## Performance Characteristics

### Computational Complexity
- **OBI Calculation**: O(n) where n = number of price levels
- **Volume Delta**: O(m) where m = number of trades
- **CVD Calculation**: O(1) - simple addition
- **Best Bid/Ask**: O(n) for min/max operations

### Memory Usage
- **Static Methods**: No instance state, minimal memory overhead
- **Calculations**: Process data in-place without copying
- **Results**: Lightweight `Metric` objects with slots optimization

### Typical Performance
```python
# Benchmark results (approximate)
Snapshot with 50 price levels:     ~0.1ms per OBI calculation
Timestamp with 20 trades:          ~0.05ms per volume delta
CVD update:                        ~0.001ms per calculation
Complete metric processing:        ~0.2ms per snapshot
```

## Error Handling

### Edge Cases Handled
```python
# Empty orderbook
empty_snapshot = BookSnapshot(bids={}, asks={})
obi = MetricCalculator.calculate_obi(empty_snapshot)  # Returns 0.0

# No trades
empty_trades = []
vd = MetricCalculator.calculate_volume_delta(empty_trades)  # Returns 0.0

# Zero volume scenario
zero_vol_snapshot = BookSnapshot(
    bids={50000.0: OrderbookLevel(price=50000.0, size=0.0, ...)},
    asks={50001.0: OrderbookLevel(price=50001.0, size=0.0, ...)}
)
obi = MetricCalculator.calculate_obi(zero_vol_snapshot)  # Returns 0.0
```

### Validation
- **OBI Range**: Results automatically bounded to [-1, 1]
- **Division by Zero**: Handled gracefully with 0.0 return
- **Invalid Data**: Empty collections handled without errors

## Testing

### Test Coverage
- **Unit Tests**: `tests/test_metric_calculator.py`
- **Integration Tests**: Included in storage and strategy tests
- **Edge Cases**: Empty data, zero volume, boundary conditions

### Running Tests
```bash
# Run metric calculator tests specifically
uv run pytest tests/test_metric_calculator.py -v

# Run all tests with metrics
uv run pytest -k "metric" -v

# Performance tests
uv run pytest tests/test_metric_calculator.py::test_calculate_obi_performance
```

## Known Issues

### Current Limitations
- **Precision**: Floating-point arithmetic limitations for very small numbers
- **Scale**: No optimization for extremely large orderbooks (>10k levels)
- **Currency**: No multi-currency support (assumes single denomination)

### Planned Enhancements
- **Decimal Precision**: Consider `decimal.Decimal` for high-precision calculations
- **Vectorization**: NumPy integration for batch calculations
- **Additional Metrics**: Volume Profile, Liquidity metrics, Delta Flow

---

The metrics calculation system provides a robust foundation for financial analysis with clean interfaces, comprehensive error handling, and optimal performance for high-frequency trading data.