@ebowwa/quant-rust 0.1.0

package/src/risk/beta.rs

@@ -0,0 +1,257 @@
+//! Beta and Alpha Functions
+//!
+//! Market sensitivity (beta) and excess return (alpha) calculations.
+
+use crate::utils::{mean, variance};
+
+/// Calculate beta (market sensitivity)
+///
+/// Beta measures how much an asset moves relative to the market.
+/// - Beta > 1: More volatile than market
+/// - Beta < 1: Less volatile than market
+/// - Beta = 1: Same volatility as market
+///
+/// # Arguments
+/// * `asset_returns` - Array of asset periodic returns
+/// * `market_returns` - Array of market/benchmark periodic returns
+///
+/// # Returns
+/// Beta coefficient
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::beta::beta;
+/// let asset = vec![0.02, 0.03, -0.01, 0.04, -0.02];
+/// let market = vec![0.01, 0.02, -0.005, 0.02, -0.01];
+/// let b = beta(&asset, &market);
+/// assert!(b > 0.0);
+/// ```
+pub fn beta(asset_returns: &[f64], market_returns: &[f64]) -> f64 {
+    if asset_returns.len() != market_returns.len() || asset_returns.is_empty() {
+        return 0.0;
+    }
+
+    let n = asset_returns.len() as f64;
+    let avg_asset = mean(asset_returns);
+    let avg_market = mean(market_returns);
+
+    // Covariance
+    let cov: f64 = asset_returns
+        .iter()
+        .zip(market_returns.iter())
+        .map(|(a, m)| (a - avg_asset) * (m - avg_market))
+        .sum::<f64>()
+        / n;
+
+    // Market variance (population variance since we're using n in covariance)
+    let market_var = variance(market_returns, true);
+
+    if market_var == 0.0 {
+        return 0.0;
+    }
+
+    cov / market_var
+}
+
+/// Calculate alpha (excess return)
+///
+/// Alpha measures the excess return of an asset relative to its beta-adjusted
+/// expected return. Positive alpha indicates outperformance.
+///
+/// Uses the Capital Asset Pricing Model (CAPM):
+/// Alpha = Asset Return - (Risk-Free Rate + Beta * (Market Return - Risk-Free Rate))
+///
+/// # Arguments
+/// * `asset_returns` - Array of asset periodic returns
+/// * `market_returns` - Array of market/benchmark periodic returns
+/// * `risk_free_rate` - Annual risk-free rate
+/// * `periods_per_year` - Number of periods in a year
+///
+/// # Returns
+/// Annualized alpha
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::beta::alpha;
+/// let asset = vec![0.02, 0.03, -0.01, 0.04, -0.02];
+/// let market = vec![0.01, 0.02, -0.005, 0.02, -0.01];
+/// let a = alpha(&asset, &market, 0.04, 252);
+/// assert!(a.is_finite());
+/// ```
+pub fn alpha(
+    asset_returns: &[f64],
+    market_returns: &[f64],
+    risk_free_rate: f64,
+    periods_per_year: usize,
+) -> f64 {
+    if asset_returns.len() != market_returns.len() || asset_returns.is_empty() {
+        return 0.0;
+    }
+
+    let b = beta(asset_returns, market_returns);
+    let asset_return = mean(asset_returns) * periods_per_year as f64;
+    let market_return = mean(market_returns) * periods_per_year as f64;
+
+    // Jensen's alpha
+    asset_return - (risk_free_rate + b * (market_return - risk_free_rate))
+}
+
+/// Result of beta/alpha calculation
+#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
+pub struct BetaAlphaResult {
+    /// Beta coefficient
+    pub beta: f64,
+    /// Alpha (annualized excess return)
+    pub alpha: f64,
+    /// Correlation between asset and market
+    pub correlation: f64,
+    /// R-squared (coefficient of determination)
+    pub r_squared: f64,
+}
+
+/// Calculate comprehensive beta and alpha metrics
+///
+/// # Arguments
+/// * `asset_returns` - Array of asset periodic returns
+/// * `market_returns` - Array of market/benchmark periodic returns
+/// * `risk_free_rate` - Annual risk-free rate
+/// * `periods_per_year` - Number of periods in a year
+///
+/// # Returns
+/// BetaAlphaResult with beta, alpha, correlation, and R-squared
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::beta::calculate_beta_alpha;
+/// let asset = vec![0.02, 0.03, -0.01, 0.04, -0.02];
+/// let market = vec![0.01, 0.02, -0.005, 0.02, -0.01];
+/// let result = calculate_beta_alpha(&asset, &market, 0.04, 252);
+/// assert!(result.beta > 0.0);
+/// assert!(result.correlation >= -1.0 && result.correlation <= 1.0);
+/// ```
+pub fn calculate_beta_alpha(
+    asset_returns: &[f64],
+    market_returns: &[f64],
+    risk_free_rate: f64,
+    periods_per_year: usize,
+) -> BetaAlphaResult {
+    if asset_returns.len() != market_returns.len() || asset_returns.is_empty() {
+        return BetaAlphaResult {
+            beta: 0.0,
+            alpha: 0.0,
+            correlation: 0.0,
+            r_squared: 0.0,
+        };
+    }
+
+    let n = asset_returns.len() as f64;
+    let avg_asset = mean(asset_returns);
+    let avg_market = mean(market_returns);
+
+    // Calculate variances and covariance
+    let mut cov = 0.0;
+    let mut var_asset = 0.0;
+    let mut var_market = 0.0;
+
+    for i in 0..asset_returns.len() {
+        let d_asset = asset_returns[i] - avg_asset;
+        let d_market = market_returns[i] - avg_market;
+        cov += d_asset * d_market;
+        var_asset += d_asset * d_asset;
+        var_market += d_market * d_market;
+    }
+
+    cov /= n;
+    var_market /= n;
+
+    let b = if var_market > 0.0 { cov / var_market } else { 0.0 };
+
+    // Correlation
+    let std_asset = (var_asset / n).sqrt();
+    let std_market = var_market.sqrt();
+    let corr = if std_asset > 0.0 && std_market > 0.0 {
+        cov / (std_asset * std_market)
+    } else {
+        0.0
+    };
+
+    // R-squared = correlation squared
+    let r_squared = corr * corr;
+
+    // Alpha
+    let asset_return = avg_asset * periods_per_year as f64;
+    let market_return = avg_market * periods_per_year as f64;
+    let a = asset_return - (risk_free_rate + b * (market_return - risk_free_rate));
+
+    BetaAlphaResult {
+        beta: b,
+        alpha: a,
+        correlation: corr,
+        r_squared,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_beta() {
+        let asset = vec![0.02, 0.03, -0.01, 0.04, -0.02];
+        let market = vec![0.01, 0.02, -0.005, 0.02, -0.01];
+        let b = beta(&asset, &market);
+        assert!(b > 0.0);
+    }
+
+    #[test]
+    fn test_beta_equal_length() {
+        // Asset moves 2x market
+        let asset = vec![0.02, 0.04, -0.01, 0.02];
+        let market = vec![0.01, 0.02, -0.005, 0.01];
+        let b = beta(&asset, &market);
+        // Should be approximately 2
+        assert!((b - 2.0).abs() < 0.5);
+    }
+
+    #[test]
+    fn test_beta_empty() {
+        let b = beta(&[], &[]);
+        assert_eq!(b, 0.0);
+    }
+
+    #[test]
+    fn test_beta_mismatched() {
+        let asset = vec![0.02, 0.03];
+        let market = vec![0.01];
+        let b = beta(&asset, &market);
+        assert_eq!(b, 0.0);
+    }
+
+    #[test]
+    fn test_alpha() {
+        let asset = vec![0.02, 0.03, -0.01, 0.04, -0.02];
+        let market = vec![0.01, 0.02, -0.005, 0.02, -0.01];
+        let a = alpha(&asset, &market, 0.04, 252);
+        assert!(a.is_finite());
+    }
+
+    #[test]
+    fn test_calculate_beta_alpha() {
+        let asset = vec![0.02, 0.03, -0.01, 0.04, -0.02];
+        let market = vec![0.01, 0.02, -0.005, 0.02, -0.01];
+        let result = calculate_beta_alpha(&asset, &market, 0.04, 252);
+        assert!(result.beta > 0.0);
+        assert!(result.correlation >= -1.0 && result.correlation <= 1.0);
+        assert!(result.r_squared >= 0.0 && result.r_squared <= 1.0);
+        assert!(result.alpha.is_finite());
+    }
+
+    #[test]
+    fn test_calculate_beta_alpha_perfect_correlation() {
+        let asset = vec![0.01, 0.02, -0.01, 0.02];
+        let market = vec![0.01, 0.02, -0.01, 0.02];
+        let result = calculate_beta_alpha(&asset, &market, 0.04, 252);
+        assert!((result.correlation - 1.0).abs() < 1e-10);
+        assert!((result.r_squared - 1.0).abs() < 1e-10);
+    }
+}

package/src/risk/drawdown.rs

@@ -0,0 +1,256 @@
+//! Drawdown Analysis Functions
+//!
+//! Maximum drawdown, underwater periods, and drawdown analysis.
+
+use serde::{Deserialize, Serialize};
+
+use crate::utils::min;
+
+/// A single drawdown point in time
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DrawdownPoint {
+    /// Start index of the drawdown
+    pub start: usize,
+    /// End index of the drawdown (recovery point)
+    pub end: usize,
+    /// Trough (lowest) value during drawdown
+    pub trough: f64,
+    /// Drawdown magnitude as decimal (e.g., 0.25 = 25%)
+    pub drawdown: f64,
+}
+
+/// Result of drawdown analysis
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DrawdownResult {
+    /// Maximum drawdown as decimal (e.g., 0.25 = 25%)
+    pub max_drawdown: f64,
+    /// Duration of maximum drawdown in periods
+    pub max_drawdown_duration: usize,
+    /// Time to recover from maximum drawdown in periods
+    pub recovery_time: usize,
+    /// All drawdown periods identified
+    pub drawdowns: Vec<DrawdownPoint>,
+}
+
+/// Calculate maximum drawdown and related metrics
+///
+/// Analyzes an equity curve to find maximum drawdown, its duration,
+/// recovery time, and all drawdown periods.
+///
+/// # Arguments
+/// * `equity_curve` - Array of equity values over time
+///
+/// # Returns
+/// DrawdownResult with max drawdown, durations, and all drawdown periods
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::drawdown::calculate_drawdown;
+/// let equity = vec![100.0, 110.0, 105.0, 95.0, 100.0, 90.0, 95.0, 110.0];
+/// let result = calculate_drawdown(&equity);
+/// assert!(result.max_drawdown > 0.0);
+/// assert!(result.max_drawdown <= 1.0);
+/// ```
+pub fn calculate_drawdown(equity_curve: &[f64]) -> DrawdownResult {
+    if equity_curve.is_empty() {
+        return DrawdownResult {
+            max_drawdown: 0.0,
+            max_drawdown_duration: 0,
+            recovery_time: 0,
+            drawdowns: vec![],
+        };
+    }
+
+    let mut peak = equity_curve[0];
+    let mut max_drawdown = 0.0;
+    let mut max_drawdown_start = 0;
+    let mut max_drawdown_end = 0;
+    let mut current_drawdown_start: Option<usize> = None;
+    let mut drawdowns: Vec<DrawdownPoint> = Vec::new();
+
+    for (i, &equity) in equity_curve.iter().enumerate() {
+        if equity > peak {
+            // New peak - check if we had a drawdown
+            if let Some(start) = current_drawdown_start {
+                if start > 0 {
+                    let trough_slice = &equity_curve[start..i];
+                    let trough = min(trough_slice);
+                    let dd = (peak - trough) / peak;
+                    drawdowns.push(DrawdownPoint {
+                        start,
+                        end: i,
+                        trough,
+                        drawdown: dd,
+                    });
+                }
+            }
+            peak = equity;
+            current_drawdown_start = None;
+        } else {
+            if current_drawdown_start.is_none() {
+                current_drawdown_start = Some(i);
+            }
+            let dd = (peak - equity) / peak;
+            if dd > max_drawdown {
+                max_drawdown = dd;
+                max_drawdown_start = current_drawdown_start.unwrap_or(i);
+                max_drawdown_end = i;
+            }
+        }
+    }
+
+    // Handle any remaining drawdown at the end
+    if let Some(start) = current_drawdown_start {
+        if start > 0 && start < equity_curve.len() {
+            let trough_slice = &equity_curve[start..];
+            let trough = min(trough_slice);
+            let dd = (peak - trough) / peak;
+            drawdowns.push(DrawdownPoint {
+                start,
+                end: equity_curve.len() - 1,
+                trough,
+                drawdown: dd,
+            });
+        }
+    }
+
+    let max_drawdown_duration = max_drawdown_end.saturating_sub(max_drawdown_start);
+
+    // Calculate recovery time (time from trough to new peak)
+    let mut recovery_time = 0;
+    if max_drawdown > 0.0 && max_drawdown_start < equity_curve.len() {
+        let dd_slice = &equity_curve[max_drawdown_start..=max_drawdown_end.min(equity_curve.len() - 1)];
+        let trough = min(dd_slice);
+
+        // Find trough index
+        let trough_relative_idx = dd_slice.iter().position(|&x| x == trough).unwrap_or(0);
+        let trough_idx = max_drawdown_start + trough_relative_idx;
+
+        // Peak before drawdown
+        let peak_at_trough = if max_drawdown_start > 0 {
+            equity_curve[max_drawdown_start - 1]
+        } else {
+            equity_curve[0]
+        };
+
+        // Find recovery point
+        for i in trough_idx..equity_curve.len() {
+            if equity_curve[i] >= peak_at_trough {
+                recovery_time = i - trough_idx;
+                break;
+            }
+        }
+    }
+
+    DrawdownResult {
+        max_drawdown,
+        max_drawdown_duration,
+        recovery_time,
+        drawdowns,
+    }
+}
+
+/// Calculate underwater periods
+///
+/// Identifies periods where the equity curve is below its running maximum.
+///
+/// # Arguments
+/// * `equity_curve` - Array of equity values over time
+///
+/// # Returns
+/// Vector of (start_index, end_index) tuples representing underwater periods
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::drawdown::underwater_periods;
+/// let equity = vec![100.0, 110.0, 105.0, 95.0, 100.0, 90.0, 95.0, 110.0];
+/// let periods = underwater_periods(&equity);
+/// assert!(!periods.is_empty());
+/// ```
+pub fn underwater_periods(equity_curve: &[f64]) -> Vec<(usize, usize)> {
+    if equity_curve.is_empty() {
+        return vec![];
+    }
+
+    let mut periods: Vec<(usize, usize)> = Vec::new();
+    let mut peak = equity_curve[0];
+    let mut underwater = false;
+    let mut start_idx = 0;
+
+    for (i, &equity) in equity_curve.iter().enumerate() {
+        if equity < peak {
+            if !underwater {
+                underwater = true;
+                start_idx = i;
+            }
+        } else if equity >= peak {
+            if underwater {
+                periods.push((start_idx, i));
+                underwater = false;
+            }
+            peak = equity;
+        }
+    }
+
+    // Handle case where we're still underwater at the end
+    if underwater {
+        periods.push((start_idx, equity_curve.len() - 1));
+    }
+
+    periods
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_calculate_drawdown() {
+        let equity = vec![100.0, 110.0, 105.0, 95.0, 100.0, 90.0, 95.0, 110.0];
+        let result = calculate_drawdown(&equity);
+        // Max drawdown: from 110 to 90 = 18.18%
+        assert!(result.max_drawdown > 0.0);
+        assert!(result.max_drawdown <= 1.0);
+        assert!(!result.drawdowns.is_empty());
+    }
+
+    #[test]
+    fn test_calculate_drawdown_empty() {
+        let result = calculate_drawdown(&[]);
+        assert_eq!(result.max_drawdown, 0.0);
+        assert_eq!(result.max_drawdown_duration, 0);
+    }
+
+    #[test]
+    fn test_calculate_drawdown_single() {
+        let result = calculate_drawdown(&[100.0]);
+        assert_eq!(result.max_drawdown, 0.0);
+    }
+
+    #[test]
+    fn test_calculate_drawdown_no_drawdown() {
+        let equity = vec![100.0, 110.0, 120.0, 130.0];
+        let result = calculate_drawdown(&equity);
+        assert_eq!(result.max_drawdown, 0.0);
+    }
+
+    #[test]
+    fn test_underwater_periods() {
+        let equity = vec![100.0, 110.0, 105.0, 95.0, 100.0, 90.0, 95.0, 110.0];
+        let periods = underwater_periods(&equity);
+        assert!(!periods.is_empty());
+    }
+
+    #[test]
+    fn test_underwater_periods_empty() {
+        let periods = underwater_periods(&[]);
+        assert!(periods.is_empty());
+    }
+
+    #[test]
+    fn test_underwater_periods_no_underwater() {
+        let equity = vec![100.0, 110.0, 120.0, 130.0];
+        let periods = underwater_periods(&equity);
+        assert!(periods.is_empty());
+    }
+}

package/src/risk/leverage.rs

@@ -0,0 +1,201 @@
+//! Leverage and Margin Functions
+//!
+//! Liquidation prices, effective leverage, and margin requirements.
+
+use serde::{Deserialize, Serialize};
+
+/// Position side for leverage calculations
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
+pub enum PositionSide {
+    /// Long position
+    Long,
+    /// Short position
+    Short,
+}
+
+/// Result of margin calculation
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+pub struct MarginResult {
+    /// Price at which position will be liquidated
+    pub liquidation_price: f64,
+    /// Effective leverage ratio
+    pub effective_leverage: f64,
+    /// Margin required to open position
+    pub margin_required: f64,
+}
+
+/// Calculate liquidation price for a leveraged position
+///
+/// Determines the price at which the position will be forcibly closed
+/// due to insufficient margin.
+///
+/// # Arguments
+/// * `entry_price` - Entry price of the position
+/// * `leverage` - Leverage ratio (e.g., 10.0 for 10x)
+/// * `side` - Position side (Long or Short)
+/// * `maintenance_margin` - Maintenance margin requirement (default: 0.05)
+///
+/// # Returns
+/// Liquidation price
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::leverage::{liquidation_price, PositionSide};
+/// let liq_price = liquidation_price(100.0, 10.0, PositionSide::Long, 0.05);
+/// assert!(liq_price < 100.0);
+/// ```
+pub fn liquidation_price(
+    entry_price: f64,
+    leverage: f64,
+    side: PositionSide,
+    maintenance_margin: f64,
+) -> f64 {
+    if leverage <= 0.0 {
+        return entry_price;
+    }
+
+    match side {
+        PositionSide::Long => entry_price * (1.0 - (1.0 - maintenance_margin) / leverage),
+        PositionSide::Short => entry_price * (1.0 + (1.0 - maintenance_margin) / leverage),
+    }
+}
+
+/// Calculate effective leverage
+///
+/// The actual leverage being used based on position size and equity.
+///
+/// # Arguments
+/// * `position_value` - Total value of the position
+/// * `equity` - Account equity
+///
+/// # Returns
+/// Effective leverage ratio
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::leverage::effective_leverage;
+/// let lev = effective_leverage(10000.0, 2000.0);
+/// assert!((lev - 5.0).abs() < 1e-10);
+/// ```
+pub fn effective_leverage(position_value: f64, equity: f64) -> f64 {
+    if equity == 0.0 {
+        return f64::INFINITY;
+    }
+    position_value / equity
+}
+
+/// Calculate margin requirement
+///
+/// The amount of collateral needed to open a position.
+///
+/// # Arguments
+/// * `position_value` - Total value of the position
+/// * `initial_margin` - Initial margin requirement (e.g., 0.10 for 10%)
+///
+/// # Returns
+/// Margin required
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::leverage::margin_requirement;
+/// let margin = margin_requirement(10000.0, 0.10);
+/// assert!((margin - 1000.0).abs() < 1e-10);
+/// ```
+pub fn margin_requirement(position_value: f64, initial_margin: f64) -> f64 {
+    position_value * initial_margin
+}
+
+/// Calculate comprehensive margin metrics
+///
+/// # Arguments
+/// * `entry_price` - Entry price of the position
+/// * `leverage` - Leverage ratio
+/// * `side` - Position side
+/// * `position_value` - Total value of the position
+/// * `equity` - Account equity
+/// * `initial_margin` - Initial margin requirement
+/// * `maintenance_margin` - Maintenance margin requirement
+///
+/// # Returns
+/// MarginResult with all metrics
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::leverage::{calculate_margin, PositionSide};
+/// let result = calculate_margin(100.0, 10.0, PositionSide::Long, 10000.0, 2000.0, 0.10, 0.05);
+/// assert!(result.liquidation_price > 0.0);
+/// assert!((result.effective_leverage - 5.0).abs() < 1e-10);
+/// assert!((result.margin_required - 1000.0).abs() < 1e-10);
+/// ```
+pub fn calculate_margin(
+    entry_price: f64,
+    leverage: f64,
+    side: PositionSide,
+    position_value: f64,
+    equity: f64,
+    initial_margin: f64,
+    maintenance_margin: f64,
+) -> MarginResult {
+    MarginResult {
+        liquidation_price: liquidation_price(entry_price, leverage, side, maintenance_margin),
+        effective_leverage: effective_leverage(position_value, equity),
+        margin_required: margin_requirement(position_value, initial_margin),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_liquidation_price_long() {
+        let liq_price = liquidation_price(100.0, 10.0, PositionSide::Long, 0.05);
+        // Long position: liquidation below entry
+        assert!(liq_price < 100.0);
+        // 100 * (1 - 0.95/10) = 100 * 0.905 = 90.5
+        assert!((liq_price - 90.5).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_liquidation_price_short() {
+        let liq_price = liquidation_price(100.0, 10.0, PositionSide::Short, 0.05);
+        // Short position: liquidation above entry
+        assert!(liq_price > 100.0);
+        // 100 * (1 + 0.95/10) = 100 * 1.095 = 109.5
+        assert!((liq_price - 109.5).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_effective_leverage() {
+        let lev = effective_leverage(10000.0, 2000.0);
+        assert!((lev - 5.0).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_effective_leverage_zero_equity() {
+        let lev = effective_leverage(10000.0, 0.0);
+        assert!(lev.is_infinite());
+    }
+
+    #[test]
+    fn test_margin_requirement() {
+        let margin = margin_requirement(10000.0, 0.10);
+        assert!((margin - 1000.0).abs() < 1e-10);
+    }
+
+    #[test]
+    fn test_calculate_margin() {
+        let result = calculate_margin(
+            100.0,
+            10.0,
+            PositionSide::Long,
+            10000.0,
+            2000.0,
+            0.10,
+            0.05,
+        );
+        assert!((result.liquidation_price - 90.5).abs() < 1e-10);
+        assert!((result.effective_leverage - 5.0).abs() < 1e-10);
+        assert!((result.margin_required - 1000.0).abs() < 1e-10);
+    }
+}