rusty_backtest/features/

queue.rs

//! Queue Analysis - Queue imbalance and position modeling
//!
//! Implements queue-based microstructural features for order book analysis.

use super::{Level, decimal_to_f64_or_nan};
use rust_decimal::prelude::*;
use smallvec::SmallVec;

/// Calculate basic queue imbalance at best bid/ask
///
/// Returns normalized imbalance (-1.0 to 1.0) where:
/// - Positive values indicate bid quantity dominance
/// - Negative values indicate ask quantity dominance
#[inline(always)]
pub fn calculate_queue_imbalance(
    bids: &SmallVec<[Level; 25]>,
    asks: &SmallVec<[Level; 25]>,
) -> f64 {
    if let (Some(best_bid), Some(best_ask)) = (bids.first(), asks.first()) {
        let total_qty = best_bid.quantity + best_ask.quantity;
        if total_qty > Decimal::ZERO {
            decimal_to_f64_or_nan((best_bid.quantity - best_ask.quantity) / total_qty)
        } else {
            0.0
        }
    } else {
        0.0
    }
}

/// Calculate weighted queue imbalance across multiple levels
///
/// Uses distance-based weighting where closer levels have higher impact.
#[inline(always)]
pub fn calculate_weighted_queue_imbalance(
    bids: &SmallVec<[Level; 25]>,
    asks: &SmallVec<[Level; 25]>,
    max_levels: usize,
) -> f64 {
    let levels = max_levels.min(bids.len()).min(asks.len());
    if levels == 0 {
        return 0.0;
    }

    let mut weighted_bid_qty = 0.0;
    let mut weighted_ask_qty = 0.0;
    let mut _total_weight = 0.0;

    for i in 0..levels {
        let weight = 1.0 / (i as f64 + 1.0); // Decreasing weight by distance
        weighted_bid_qty += decimal_to_f64_or_nan(bids[i].quantity) * weight;
        weighted_ask_qty += decimal_to_f64_or_nan(asks[i].quantity) * weight;
        _total_weight += weight;
    }

    let total_weighted_qty = weighted_bid_qty + weighted_ask_qty;
    if total_weighted_qty > 0.0 {
        (weighted_bid_qty - weighted_ask_qty) / total_weighted_qty
    } else {
        0.0
    }
}

/// Queue Analyzer for comprehensive queue metrics
pub struct QueueAnalyzer {
    imbalance_history: Vec<f64>,
    window_size: usize,
}

impl QueueAnalyzer {
    /// Create new queue analyzer
    #[must_use]
    pub fn new(window_size: usize) -> Self {
        Self {
            imbalance_history: Vec::with_capacity(window_size * 2),
            window_size,
        }
    }

    /// Add queue imbalance measurement
    pub fn add_measurement(&mut self, imbalance: f64) {
        self.imbalance_history.push(imbalance);

        // Maintain window size
        if self.imbalance_history.len() > self.window_size * 2 {
            let drain_count = self.window_size;
            self.imbalance_history.drain(0..drain_count);
        }
    }

    /// Get average imbalance over window
    pub fn get_average_imbalance(&self) -> f64 {
        if self.imbalance_history.is_empty() {
            return 0.0;
        }

        let recent_window = &self.imbalance_history[self
            .imbalance_history
            .len()
            .saturating_sub(self.window_size)..];
        recent_window.iter().sum::<f64>() / recent_window.len() as f64
    }

    /// Get imbalance volatility (standard deviation)
    pub fn get_imbalance_volatility(&self) -> f64 {
        if self.imbalance_history.len() < 2 {
            return 0.0;
        }

        let recent_window = &self.imbalance_history[self
            .imbalance_history
            .len()
            .saturating_sub(self.window_size)..];
        let mean = self.get_average_imbalance();

        let variance = recent_window
            .iter()
            .map(|&x| (x - mean).powi(2))
            .sum::<f64>()
            / recent_window.len() as f64;

        variance.sqrt()
    }
}

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

    #[test]
    fn test_queue_imbalance_balanced() {
        let bids = smallvec::smallvec![Level {
            price: dec!(49999),
            quantity: dec!(10.0),
            order_count: 1
        }];
        let asks = smallvec::smallvec![Level {
            price: dec!(50001),
            quantity: dec!(10.0),
            order_count: 1
        }];

        let imbalance = calculate_queue_imbalance(&bids, &asks);
        assert_eq!(imbalance, 0.0); // Balanced should give 0
    }

    #[test]
    fn test_queue_imbalance_bid_heavy() {
        let bids = smallvec::smallvec![Level {
            price: dec!(49999),
            quantity: dec!(15.0),
            order_count: 1
        }];
        let asks = smallvec::smallvec![Level {
            price: dec!(50001),
            quantity: dec!(5.0),
            order_count: 1
        }];

        let imbalance = calculate_queue_imbalance(&bids, &asks);
        assert_eq!(imbalance, 0.5); // (15-5)/(15+5) = 0.5
    }

    #[test]
    fn test_queue_imbalance_ask_heavy() {
        let bids = smallvec::smallvec![Level {
            price: dec!(49999),
            quantity: dec!(5.0),
            order_count: 1
        }];
        let asks = smallvec::smallvec![Level {
            price: dec!(50001),
            quantity: dec!(15.0),
            order_count: 1
        }];

        let imbalance = calculate_queue_imbalance(&bids, &asks);
        assert_eq!(imbalance, -0.5); // (5-15)/(5+15) = -0.5
    }

    #[test]
    fn test_weighted_queue_imbalance_single_level() {
        let bids = smallvec::smallvec![Level {
            price: dec!(49999),
            quantity: dec!(10.0),
            order_count: 1
        }];
        let asks = smallvec::smallvec![Level {
            price: dec!(50001),
            quantity: dec!(10.0),
            order_count: 1
        }];

        let imbalance = calculate_weighted_queue_imbalance(&bids, &asks, 1);
        assert_eq!(imbalance, 0.0); // Balanced at first level
    }

    #[test]
    fn test_weighted_queue_imbalance_multi_level() {
        let bids = smallvec::smallvec![
            Level {
                price: dec!(49999),
                quantity: dec!(10.0),
                order_count: 1
            },
            Level {
                price: dec!(49998),
                quantity: dec!(20.0),
                order_count: 2
            },
            Level {
                price: dec!(49997),
                quantity: dec!(30.0),
                order_count: 3
            }
        ];
        let asks = smallvec::smallvec![
            Level {
                price: dec!(50001),
                quantity: dec!(10.0),
                order_count: 1
            },
            Level {
                price: dec!(50002),
                quantity: dec!(20.0),
                order_count: 2
            },
            Level {
                price: dec!(50003),
                quantity: dec!(30.0),
                order_count: 3
            }
        ];

        let imbalance = calculate_weighted_queue_imbalance(&bids, &asks, 3);
        assert_eq!(imbalance, 0.0); // Symmetric book should be balanced
    }

    #[test]
    fn test_weighted_queue_imbalance_bid_heavy() {
        let bids = smallvec::smallvec![
            Level {
                price: dec!(49999),
                quantity: dec!(20.0),
                order_count: 1
            },
            Level {
                price: dec!(49998),
                quantity: dec!(30.0),
                order_count: 2
            }
        ];
        let asks = smallvec::smallvec![
            Level {
                price: dec!(50001),
                quantity: dec!(10.0),
                order_count: 1
            },
            Level {
                price: dec!(50002),
                quantity: dec!(15.0),
                order_count: 2
            }
        ];

        let imbalance = calculate_weighted_queue_imbalance(&bids, &asks, 2);
        // Weight 1: 20 * 1.0 = 20, 10 * 1.0 = 10
        // Weight 0.5: 30 * 0.5 = 15, 15 * 0.5 = 7.5
        // Total bid: 35, Total ask: 17.5
        // (35 - 17.5) / (35 + 17.5) = 17.5 / 52.5 = 0.333...
        assert!((imbalance - 0.333_333_333_333_333_3).abs() < 1e-10);
    }

    #[test]
    fn test_weighted_queue_imbalance_empty_book() {
        let bids: SmallVec<[Level; 25]> = smallvec::smallvec![];
        let asks: SmallVec<[Level; 25]> = smallvec::smallvec![];

        let imbalance = calculate_weighted_queue_imbalance(&bids, &asks, 5);
        assert_eq!(imbalance, 0.0); // Empty book returns 0
    }

    #[test]
    fn test_weighted_queue_imbalance_one_sided() {
        let bids = smallvec::smallvec![Level {
            price: dec!(49999),
            quantity: dec!(10.0),
            order_count: 1
        }];
        let asks: SmallVec<[Level; 25]> = smallvec::smallvec![];

        let imbalance = calculate_weighted_queue_imbalance(&bids, &asks, 1);
        assert_eq!(imbalance, 0.0); // One-sided book returns 0
    }

    #[test]
    fn test_weighted_queue_imbalance_max_levels_exceeds_book() {
        let bids = smallvec::smallvec![Level {
            price: dec!(49999),
            quantity: dec!(10.0),
            order_count: 1
        }];
        let asks = smallvec::smallvec![Level {
            price: dec!(50001),
            quantity: dec!(20.0),
            order_count: 1
        }];

        // Request 10 levels but only have 1
        let imbalance = calculate_weighted_queue_imbalance(&bids, &asks, 10);
        // Should only use available level: (10 - 20) / (10 + 20) = -10/30 = -0.333...
        assert!((imbalance - (-0.333_333_333_333_333_3)).abs() < 1e-10);
    }
}