rusty_backtest/features/

asymmetry.rs

//! Asymmetry Index for Order Book Skewness Analysis
//!
//! Implements various asymmetry metrics to detect directional pressure
//! and potential price movements based on order book imbalances.

use super::{OrderBookSnapshot, decimal_to_f64_or_nan};

/// Asymmetry Index calculator for order book skewness
///
/// Measures the asymmetry between bid and ask sides of the order book
/// to identify potential directional pressure and price movements.
#[derive(Debug, Clone)]
pub struct AsymmetryIndexCalculator {
    /// Number of price levels to consider
    max_levels: usize,
    /// Use volume-weighted calculation
    #[allow(dead_code)]
    volume_weighted: bool,
    /// Price distance weighting decay factor (0-1)
    distance_decay: f64,
    /// Rolling window for smoothing
    window_size: usize,
    /// Historical asymmetry values
    history: Vec<f64>,
    /// Current position in circular buffer
    buffer_position: usize,
    /// Number of samples collected
    samples_count: usize,
}

impl AsymmetryIndexCalculator {
    /// Create a new asymmetry index calculator
    ///
    /// # Arguments
    /// * `max_levels` - Maximum number of price levels to analyze
    /// * `volume_weighted` - Whether to weight by volume
    /// * `distance_decay` - Decay factor for price distance weighting (0-1)
    /// * `window_size` - Size of rolling window for smoothing
    #[must_use]
    pub fn new(
        max_levels: usize,
        volume_weighted: bool,
        distance_decay: f64,
        window_size: usize,
    ) -> Self {
        Self {
            max_levels,
            volume_weighted,
            distance_decay: distance_decay.clamp(0.0, 1.0),
            window_size,
            history: vec![0.0; window_size],
            buffer_position: 0,
            samples_count: 0,
        }
    }

    /// Calculate asymmetry index from order book snapshot
    pub fn calculate(&mut self, snapshot: &OrderBookSnapshot) -> AsymmetryMetrics {
        // Calculate basic asymmetry
        let basic_asymmetry = self.calculate_basic_asymmetry(snapshot);

        // Calculate weighted asymmetry
        let weighted_asymmetry = self.calculate_weighted_asymmetry(snapshot);

        // Calculate volume-weighted asymmetry
        let volume_asymmetry = self.calculate_volume_asymmetry(snapshot);

        // Calculate order count asymmetry
        let order_count_asymmetry = self.calculate_order_count_asymmetry(snapshot);

        // Store in history for smoothing
        self.history[self.buffer_position] = weighted_asymmetry;
        self.buffer_position = (self.buffer_position + 1) % self.window_size;
        self.samples_count = self.samples_count.saturating_add(1).min(self.window_size);

        // Calculate smoothed asymmetry
        let smoothed_asymmetry = if self.samples_count > 0 {
            self.history.iter().take(self.samples_count).sum::<f64>() / self.samples_count as f64
        } else {
            weighted_asymmetry
        };

        AsymmetryMetrics {
            basic_asymmetry,
            weighted_asymmetry,
            volume_asymmetry,
            order_count_asymmetry,
            smoothed_asymmetry,
            directional_pressure: self.calculate_directional_pressure(smoothed_asymmetry),
        }
    }

    /// Calculate basic price-level asymmetry
    fn calculate_basic_asymmetry(&self, snapshot: &OrderBookSnapshot) -> f64 {
        let levels = self
            .max_levels
            .min(snapshot.bids.len())
            .min(snapshot.asks.len());
        if levels == 0 {
            return 0.0;
        }

        let mid_price = decimal_to_f64_or_nan(snapshot.mid_price());
        if mid_price <= 0.0 {
            return 0.0;
        }

        let mut bid_score = 0.0;
        let mut ask_score = 0.0;

        for i in 0..levels {
            let bid_price = decimal_to_f64_or_nan(snapshot.bids[i].price);
            let ask_price = decimal_to_f64_or_nan(snapshot.asks[i].price);

            // Calculate price distances from mid
            let bid_distance = (mid_price - bid_price).abs() / mid_price;
            let ask_distance = (ask_price - mid_price).abs() / mid_price;

            // Equal weight for each level
            bid_score += 1.0 / (1.0 + bid_distance);
            ask_score += 1.0 / (1.0 + ask_distance);
        }

        // Normalize to [-1, 1]
        (bid_score - ask_score) / (bid_score + ask_score)
    }

    /// Calculate weighted asymmetry with distance decay
    fn calculate_weighted_asymmetry(&self, snapshot: &OrderBookSnapshot) -> f64 {
        let levels = self
            .max_levels
            .min(snapshot.bids.len())
            .min(snapshot.asks.len());
        if levels == 0 {
            return 0.0;
        }

        let mid_price = decimal_to_f64_or_nan(snapshot.mid_price());
        if mid_price <= 0.0 {
            return 0.0;
        }

        let mut bid_weighted_volume = 0.0;
        let mut ask_weighted_volume = 0.0;

        for i in 0..levels {
            let bid = &snapshot.bids[i];
            let ask = &snapshot.asks[i];

            let bid_price = decimal_to_f64_or_nan(bid.price);
            let ask_price = decimal_to_f64_or_nan(ask.price);

            // Calculate price distances
            let bid_distance = ((mid_price - bid_price) / mid_price).abs();
            let ask_distance = ((ask_price - mid_price) / mid_price).abs();

            // Apply distance decay
            let bid_weight = self.distance_decay.powf(bid_distance * 100.0);
            let ask_weight = self.distance_decay.powf(ask_distance * 100.0);

            bid_weighted_volume += decimal_to_f64_or_nan(bid.quantity) * bid_weight;
            ask_weighted_volume += decimal_to_f64_or_nan(ask.quantity) * ask_weight;
        }

        if bid_weighted_volume + ask_weighted_volume == 0.0 {
            return 0.0;
        }

        // Normalize to [-1, 1]
        (bid_weighted_volume - ask_weighted_volume) / (bid_weighted_volume + ask_weighted_volume)
    }

    /// Calculate pure volume asymmetry
    fn calculate_volume_asymmetry(&self, snapshot: &OrderBookSnapshot) -> f64 {
        let levels = self
            .max_levels
            .min(snapshot.bids.len())
            .min(snapshot.asks.len());
        if levels == 0 {
            return 0.0;
        }

        let mut total_bid_volume = 0.0;
        let mut total_ask_volume = 0.0;

        for i in 0..levels {
            total_bid_volume += decimal_to_f64_or_nan(snapshot.bids[i].quantity);
            total_ask_volume += decimal_to_f64_or_nan(snapshot.asks[i].quantity);
        }

        if total_bid_volume + total_ask_volume == 0.0 {
            return 0.0;
        }

        (total_bid_volume - total_ask_volume) / (total_bid_volume + total_ask_volume)
    }

    /// Calculate order count asymmetry
    fn calculate_order_count_asymmetry(&self, snapshot: &OrderBookSnapshot) -> f64 {
        let levels = self
            .max_levels
            .min(snapshot.bids.len())
            .min(snapshot.asks.len());
        if levels == 0 {
            return 0.0;
        }

        let mut total_bid_orders = 0u32;
        let mut total_ask_orders = 0u32;

        for i in 0..levels {
            total_bid_orders += snapshot.bids[i].order_count;
            total_ask_orders += snapshot.asks[i].order_count;
        }

        if total_bid_orders + total_ask_orders == 0 {
            return 0.0;
        }

        let bid_orders = total_bid_orders as f64;
        let ask_orders = total_ask_orders as f64;

        (bid_orders - ask_orders) / (bid_orders + ask_orders)
    }

    /// Calculate directional pressure indicator
    fn calculate_directional_pressure(&self, smoothed_asymmetry: f64) -> DirectionalPressure {
        if smoothed_asymmetry > 0.3 {
            DirectionalPressure::StrongBullish
        } else if smoothed_asymmetry > 0.1 {
            DirectionalPressure::WeakBullish
        } else if smoothed_asymmetry < -0.3 {
            DirectionalPressure::StrongBearish
        } else if smoothed_asymmetry < -0.1 {
            DirectionalPressure::WeakBearish
        } else {
            DirectionalPressure::Neutral
        }
    }

    /// Reset the calculator
    pub fn reset(&mut self) {
        self.history.fill(0.0);
        self.buffer_position = 0;
        self.samples_count = 0;
    }
}

/// Asymmetry metrics output
#[derive(Debug, Clone, Copy)]
pub struct AsymmetryMetrics {
    /// Basic price-level asymmetry [-1, 1]
    pub basic_asymmetry: f64,
    /// Distance-weighted asymmetry [-1, 1]
    pub weighted_asymmetry: f64,
    /// Pure volume asymmetry [-1, 1]
    pub volume_asymmetry: f64,
    /// Order count asymmetry [-1, 1]
    pub order_count_asymmetry: f64,
    /// Smoothed asymmetry over window [-1, 1]
    pub smoothed_asymmetry: f64,
    /// Directional pressure indicator
    pub directional_pressure: DirectionalPressure,
}

/// Directional pressure levels
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum DirectionalPressure {
    /// Strong buying pressure detected (asymmetry > 0.3)
    StrongBullish,
    /// Weak buying pressure detected (asymmetry > 0.1)
    WeakBullish,
    /// Balanced market with no clear direction
    Neutral,
    /// Weak selling pressure detected (asymmetry < -0.1)
    WeakBearish,
    /// Strong selling pressure detected (asymmetry < -0.3)
    StrongBearish,
}

/// Multi-timeframe asymmetry analyzer
#[derive(Debug, Clone)]
pub struct MultiTimeframeAsymmetry {
    /// Short-term calculator (e.g., 10 samples)
    short_term: AsymmetryIndexCalculator,
    /// Medium-term calculator (e.g., 50 samples)
    medium_term: AsymmetryIndexCalculator,
    /// Long-term calculator (e.g., 200 samples)
    long_term: AsymmetryIndexCalculator,
}

impl MultiTimeframeAsymmetry {
    /// Create a new multi-timeframe analyzer
    #[must_use]
    pub fn new(max_levels: usize, distance_decay: f64) -> Self {
        Self {
            short_term: AsymmetryIndexCalculator::new(max_levels, true, distance_decay, 10),
            medium_term: AsymmetryIndexCalculator::new(max_levels, true, distance_decay, 50),
            long_term: AsymmetryIndexCalculator::new(max_levels, true, distance_decay, 200),
        }
    }

    /// Update all timeframes and get composite signal
    pub fn update(&mut self, snapshot: &OrderBookSnapshot) -> MultiTimeframeMetrics {
        let short_metrics = self.short_term.calculate(snapshot);
        let medium_metrics = self.medium_term.calculate(snapshot);
        let long_metrics = self.long_term.calculate(snapshot);

        // Calculate divergence between timeframes
        let short_medium_divergence =
            (short_metrics.smoothed_asymmetry - medium_metrics.smoothed_asymmetry).abs();
        let medium_long_divergence =
            (medium_metrics.smoothed_asymmetry - long_metrics.smoothed_asymmetry).abs();

        // Determine trend alignment
        let trend_aligned = short_metrics.smoothed_asymmetry.signum()
            == medium_metrics.smoothed_asymmetry.signum()
            && medium_metrics.smoothed_asymmetry.signum()
                == long_metrics.smoothed_asymmetry.signum();

        MultiTimeframeMetrics {
            short_term: short_metrics,
            medium_term: medium_metrics,
            long_term: long_metrics,
            short_medium_divergence,
            medium_long_divergence,
            trend_aligned,
            composite_signal: self.calculate_composite_signal(
                &short_metrics,
                &medium_metrics,
                &long_metrics,
            ),
        }
    }

    /// Calculate composite signal from all timeframes
    fn calculate_composite_signal(
        &self,
        short: &AsymmetryMetrics,
        medium: &AsymmetryMetrics,
        long: &AsymmetryMetrics,
    ) -> f64 {
        // Weight: 50% short, 30% medium, 20% long
        0.5 * short.smoothed_asymmetry
            + 0.3 * medium.smoothed_asymmetry
            + 0.2 * long.smoothed_asymmetry
    }
}

/// Multi-timeframe metrics
#[derive(Debug, Clone)]
pub struct MultiTimeframeMetrics {
    /// Short-term asymmetry metrics (10 samples)
    pub short_term: AsymmetryMetrics,
    /// Medium-term asymmetry metrics (50 samples)
    pub medium_term: AsymmetryMetrics,
    /// Long-term asymmetry metrics (200 samples)
    pub long_term: AsymmetryMetrics,
    /// Absolute divergence between short and medium term signals
    pub short_medium_divergence: f64,
    /// Absolute divergence between medium and long term signals
    pub medium_long_divergence: f64,
    /// Whether all timeframes show the same directional bias
    pub trend_aligned: bool,
    /// Weighted composite signal from all timeframes
    pub composite_signal: f64,
}

/// Calculate simple asymmetry index
pub fn calculate_asymmetry_index(snapshot: &OrderBookSnapshot, levels: usize) -> f64 {
    let n_levels = levels.min(snapshot.bids.len()).min(snapshot.asks.len());
    if n_levels == 0 {
        return 0.0;
    }

    let mut bid_volume = 0.0;
    let mut ask_volume = 0.0;

    for i in 0..n_levels {
        bid_volume += decimal_to_f64_or_nan(snapshot.bids[i].quantity);
        ask_volume += decimal_to_f64_or_nan(snapshot.asks[i].quantity);
    }

    if bid_volume + ask_volume == 0.0 {
        return 0.0;
    }

    (bid_volume - ask_volume) / (bid_volume + ask_volume)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::features::Level;
    use rust_decimal_macros::dec;
    use smallvec::smallvec;

    fn create_test_snapshot() -> OrderBookSnapshot {
        OrderBookSnapshot {
            symbol: "TEST".into(),
            timestamp_ns: 1_000_000_000,
            bids: smallvec![
                Level {
                    price: dec!(99.9),
                    quantity: dec!(100.0),
                    order_count: 5
                },
                Level {
                    price: dec!(99.8),
                    quantity: dec!(150.0),
                    order_count: 7
                },
                Level {
                    price: dec!(99.7),
                    quantity: dec!(200.0),
                    order_count: 10
                },
            ],
            asks: smallvec![
                Level {
                    price: dec!(100.1),
                    quantity: dec!(80.0),
                    order_count: 4
                },
                Level {
                    price: dec!(100.2),
                    quantity: dec!(120.0),
                    order_count: 6
                },
                Level {
                    price: dec!(100.3),
                    quantity: dec!(180.0),
                    order_count: 9
                },
            ],
        }
    }

    #[test]
    fn test_basic_asymmetry() {
        let mut calculator = AsymmetryIndexCalculator::new(3, false, 0.95, 10);
        let snapshot = create_test_snapshot();

        let metrics = calculator.calculate(&snapshot);

        // With more bid volume (450 vs 380), should be positive
        assert!(metrics.volume_asymmetry > 0.0);

        // More bid orders (22 vs 19), should be positive
        assert!(metrics.order_count_asymmetry > 0.0);
    }

    #[test]
    fn test_directional_pressure() {
        let mut calculator = AsymmetryIndexCalculator::new(3, true, 0.95, 10);

        // Create strongly bullish snapshot
        let mut snapshot = create_test_snapshot();
        snapshot.bids[0].quantity = dec!(500.0);
        snapshot.bids[1].quantity = dec!(400.0);

        let metrics = calculator.calculate(&snapshot);
        assert!(matches!(
            metrics.directional_pressure,
            DirectionalPressure::StrongBullish
        ));
    }

    #[test]
    fn test_multi_timeframe() {
        let mut analyzer = MultiTimeframeAsymmetry::new(3, 0.95);
        let snapshot = create_test_snapshot();

        let mtf_metrics = analyzer.update(&snapshot);

        // All timeframes should initially show similar values
        assert!(
            (mtf_metrics.short_term.volume_asymmetry - mtf_metrics.medium_term.volume_asymmetry)
                .abs()
                < 0.1
        );
    }

    #[test]
    fn test_simple_asymmetry_function() {
        let snapshot = create_test_snapshot();
        let asymmetry = calculate_asymmetry_index(&snapshot, 3);

        // Bid volume: 450, Ask volume: 380
        // Expected: (450 - 380) / (450 + 380) ≈ 0.084
        assert!((asymmetry - 0.084).abs() < 0.01);
    }
}