@ebowwa/quant-rust 0.1.0

package/src/risk/mod.rs

@@ -0,0 +1,388 @@
+//! Risk Management Module
+//!
+//! Comprehensive risk metrics including VaR, CVaR, Sharpe ratio, drawdown analysis,
+//! position sizing, portfolio risk, leverage/margin, and beta/alpha calculations.
+//!
+//! ## Modules
+//! - `sizing`: Position sizing (fixed fractional, volatility-based, Kelly)
+//! - `var`: Value at Risk (historical, parametric, expected shortfall)
+//! - `drawdown`: Drawdown analysis (max drawdown, underwater periods)
+//! - `ratios`: Risk-adjusted return ratios (Sharpe, Sortino, Calmar, Treynor, Information)
+//! - `portfolio`: Portfolio risk (volatility, covariance, diversification)
+//! - `leverage`: Leverage and margin (liquidation price, effective leverage)
+//! - `beta`: Beta and alpha calculations
+
+pub mod beta;
+pub mod drawdown;
+pub mod leverage;
+pub mod portfolio;
+pub mod ratios;
+pub mod sizing;
+pub mod var;
+
+// Re-export types and functions from submodules
+
+// Position Sizing
+pub use sizing::{
+    fixed_fractional_size,
+    kelly_size,
+    volatility_based_size,
+    PositionSizeResult,
+};
+
+// Value at Risk
+pub use var::{
+    calculate_var,
+    historical_var,
+    parametric_var,
+    VaRConfig,
+    VaRResult,
+};
+
+// Drawdown
+pub use drawdown::{
+    calculate_drawdown,
+    underwater_periods,
+    DrawdownPoint,
+    DrawdownResult,
+};
+
+// Risk-Adjusted Ratios
+pub use ratios::{
+    calmar_ratio,
+    calculate_risk_adjusted_metrics,
+    information_ratio,
+    sharpe_ratio,
+    sortino_ratio,
+    treynor_ratio,
+    RiskAdjustedMetrics,
+};
+
+// Portfolio Risk
+pub use portfolio::{
+    covariance,
+    covariance_matrix,
+    diversification_ratio,
+    portfolio_volatility,
+    risk_contribution,
+};
+
+// Leverage & Margin
+pub use leverage::{
+    calculate_margin,
+    effective_leverage,
+    liquidation_price,
+    margin_requirement,
+    MarginResult,
+    PositionSide,
+};
+
+// Beta & Alpha
+pub use beta::{
+    alpha,
+    beta,
+    calculate_beta_alpha,
+    BetaAlphaResult,
+};
+
+// ============================================================================
+// Legacy Functions (for backward compatibility)
+// ============================================================================
+
+use serde::{Deserialize, Serialize};
+
+/// Value at Risk (VaR) and Expected Shortfall (CVaR) result (legacy)
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+pub struct LegacyVaRResult {
+    /// Value at Risk at the given confidence level
+    pub var: f64,
+    /// Conditional VaR (Expected Shortfall)
+    pub cvar: f64,
+    /// Confidence level used
+    pub confidence_level: f64,
+}
+
+/// Drawdown analysis result (legacy)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LegacyDrawdownResult {
+    /// Maximum drawdown (as decimal, e.g., 0.25 = 25%)
+    pub max_drawdown: f64,
+    /// Maximum drawdown duration in periods
+    pub max_duration: usize,
+    /// Current drawdown
+    pub current_drawdown: f64,
+    /// Recovery factor (total return / max drawdown)
+    pub recovery_factor: f64,
+}
+
+/// Sharpe ratio result (legacy)
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+pub struct SharpeResult {
+    /// Sharpe ratio
+    pub sharpe_ratio: f64,
+    /// Annualized Sharpe ratio
+    pub annualized_sharpe: f64,
+    /// Risk-free rate used
+    pub risk_free_rate: f64,
+    /// Average return
+    pub avg_return: f64,
+    /// Standard deviation of returns
+    pub std_dev: f64,
+}
+
+/// Calculate Value at Risk using historical simulation (legacy)
+pub fn calculate_var_legacy(returns: &[f64], confidence_level: f64) -> LegacyVaRResult {
+    if returns.is_empty() {
+        return LegacyVaRResult {
+            var: 0.0,
+            cvar: 0.0,
+            confidence_level,
+        };
+    }
+
+    let mut sorted_returns = returns.to_vec();
+    sorted_returns.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
+
+    let index = ((1.0 - confidence_level) * returns.len() as f64).floor() as usize;
+    let index = index.min(sorted_returns.len() - 1);
+
+    let var = -sorted_returns[index];
+
+    // CVaR is the average of returns below VaR
+    let tail_returns: Vec<f64> = sorted_returns.iter().take(index + 1).cloned().collect();
+
+    let cvar = if tail_returns.is_empty() {
+        var
+    } else {
+        -tail_returns.iter().sum::<f64>() / tail_returns.len() as f64
+    };
+
+    LegacyVaRResult {
+        var,
+        cvar,
+        confidence_level,
+    }
+}
+
+/// Calculate maximum drawdown from equity curve (legacy)
+pub fn calculate_drawdown_legacy(equity_curve: &[f64]) -> LegacyDrawdownResult {
+    if equity_curve.len() < 2 {
+        return LegacyDrawdownResult {
+            max_drawdown: 0.0,
+            max_duration: 0,
+            current_drawdown: 0.0,
+            recovery_factor: 0.0,
+        };
+    }
+
+    let mut max_drawdown = 0.0;
+    let mut max_duration = 0;
+    let mut peak = equity_curve[0];
+    let mut last_peak_idx = 0;
+
+    for (i, &equity) in equity_curve.iter().enumerate() {
+        if equity > peak {
+            peak = equity;
+            last_peak_idx = i;
+        } else {
+            let duration = i - last_peak_idx;
+            let drawdown = (peak - equity) / peak;
+            if drawdown > max_drawdown {
+                max_drawdown = drawdown;
+                max_duration = duration;
+            }
+        }
+    }
+
+    let current_drawdown = if peak > 0.0 {
+        (peak - equity_curve[equity_curve.len() - 1]) / peak
+    } else {
+        0.0
+    };
+
+    let total_return = if equity_curve[0] > 0.0 {
+        (equity_curve[equity_curve.len() - 1] - equity_curve[0]) / equity_curve[0]
+    } else {
+        0.0
+    };
+
+    let recovery_factor = if max_drawdown > 0.0 {
+        total_return / max_drawdown
+    } else {
+        f64::INFINITY
+    };
+
+    LegacyDrawdownResult {
+        max_drawdown,
+        max_duration,
+        current_drawdown,
+        recovery_factor,
+    }
+}
+
+/// Calculate Sharpe ratio (legacy)
+pub fn calculate_sharpe_ratio(
+    returns: &[f64],
+    risk_free_rate: f64,
+    periods_per_year: usize,
+) -> SharpeResult {
+    if returns.is_empty() {
+        return SharpeResult {
+            sharpe_ratio: 0.0,
+            annualized_sharpe: 0.0,
+            risk_free_rate,
+            avg_return: 0.0,
+            std_dev: 0.0,
+        };
+    }
+
+    let n = returns.len() as f64;
+    let avg_return = returns.iter().sum::<f64>() / n;
+
+    let variance: f64 = returns
+        .iter()
+        .map(|r| (r - avg_return).powi(2))
+        .sum::<f64>()
+        / n;
+
+    let std_dev = variance.sqrt();
+
+    if std_dev == 0.0 {
+        return SharpeResult {
+            sharpe_ratio: 0.0,
+            annualized_sharpe: 0.0,
+            risk_free_rate,
+            avg_return,
+            std_dev,
+        };
+    }
+
+    // Periodic Sharpe
+    let excess_return = avg_return - risk_free_rate / periods_per_year as f64;
+    let sharpe_ratio = excess_return / std_dev;
+
+    // Annualized Sharpe
+    let annualized_sharpe = sharpe_ratio * (periods_per_year as f64).sqrt();
+
+    SharpeResult {
+        sharpe_ratio,
+        annualized_sharpe,
+        risk_free_rate,
+        avg_return,
+        std_dev,
+    }
+}
+
+/// Calculate Sortino ratio (only penalizes downside volatility) (legacy)
+pub fn calculate_sortino_ratio(
+    returns: &[f64],
+    risk_free_rate: f64,
+    periods_per_year: usize,
+) -> f64 {
+    sortino_ratio(returns, risk_free_rate, periods_per_year)
+}
+
+/// Calculate beta and alpha against benchmark (legacy)
+pub fn calculate_beta_alpha_legacy(asset_returns: &[f64], benchmark_returns: &[f64]) -> (f64, f64) {
+    if asset_returns.is_empty()
+        || benchmark_returns.is_empty()
+        || asset_returns.len() != benchmark_returns.len()
+    {
+        return (0.0, 0.0);
+    }
+
+    let n = asset_returns.len() as f64;
+    let avg_asset = crate::utils::mean(asset_returns);
+    let avg_bench = crate::utils::mean(benchmark_returns);
+
+    // Covariance
+    let cov: f64 = asset_returns
+        .iter()
+        .zip(benchmark_returns.iter())
+        .map(|(a, b)| (a - avg_asset) * (b - avg_bench))
+        .sum::<f64>()
+        / n;
+
+    // Benchmark variance
+    let var_bench: f64 = benchmark_returns
+        .iter()
+        .map(|r| (r - avg_bench).powi(2))
+        .sum::<f64>()
+        / n;
+
+    if var_bench == 0.0 {
+        return (0.0, 0.0);
+    }
+
+    let beta = cov / var_bench;
+    let alpha = avg_asset - beta * avg_bench;
+
+    (beta, alpha)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_var_calculation() {
+        let returns = vec![-0.05, -0.02, 0.01, 0.03, 0.02, -0.04, 0.05, -0.01, 0.02, 0.01];
+        let result = calculate_var_legacy(&returns, 0.95);
+        assert!(result.var > 0.0);
+        assert!(result.cvar >= result.var);
+    }
+
+    #[test]
+    fn test_drawdown_calculation() {
+        let equity = vec![100.0, 110.0, 105.0, 95.0, 100.0, 90.0, 95.0, 110.0];
+        let result = calculate_drawdown_legacy(&equity);
+        assert!(result.max_drawdown > 0.0);
+        assert!(result.max_drawdown <= 1.0);
+    }
+
+    #[test]
+    fn test_sharpe_ratio() {
+        let returns = vec![0.01, 0.02, -0.01, 0.03, -0.02, 0.01, 0.02, 0.01, -0.01, 0.02];
+        let result = calculate_sharpe_ratio(&returns, 0.02, 252);
+        // Should be positive for these returns
+        assert!(result.sharpe_ratio.is_finite());
+    }
+
+    #[test]
+    fn test_position_sizing() {
+        let result = fixed_fractional_size(100000.0, 0.02, 50.0, 45.0);
+        assert_eq!(result.shares, 400);
+        assert_eq!(result.risk_amount, 2000.0);
+    }
+
+    #[test]
+    fn test_var_new() {
+        let returns = vec![-0.05, -0.02, 0.01, 0.03, 0.02, -0.04, 0.05, -0.01, 0.02, 0.01];
+        let result = calculate_var(&returns, VaRConfig::default());
+        assert!(result.var95 > 0.0);
+        assert!(result.var99 >= result.var95);
+    }
+
+    #[test]
+    fn test_drawdown_new() {
+        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);
+    }
+
+    #[test]
+    fn test_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);
+    }
+
+    #[test]
+    fn test_leverage() {
+        let liq_price = liquidation_price(100.0, 10.0, PositionSide::Long, 0.05);
+        assert!((liq_price - 90.5).abs() < 1e-10);
+    }
+}

package/src/risk/portfolio.rs

@@ -0,0 +1,287 @@
+//! Portfolio Risk Functions
+//!
+//! Portfolio volatility, covariance matrices, diversification, and risk contribution.
+
+use crate::utils::mean;
+
+/// Calculate portfolio volatility
+///
+/// Computes the standard deviation of portfolio returns using weights
+/// and the covariance matrix.
+///
+/// # Arguments
+/// * `weights` - Array of position weights (should sum to 1.0)
+/// * `cov_matrix` - Covariance matrix of asset returns
+///
+/// # Returns
+/// Portfolio volatility (standard deviation)
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::portfolio::portfolio_volatility;
+/// let weights = vec![0.6, 0.4];
+/// let cov_matrix = vec![vec![0.04, 0.01], vec![0.01, 0.09]];
+/// let vol = portfolio_volatility(&weights, &cov_matrix);
+/// assert!(vol > 0.0);
+/// ```
+pub fn portfolio_volatility(weights: &[f64], cov_matrix: &[Vec<f64>]) -> f64 {
+    let n = weights.len();
+    if n == 0 || cov_matrix.len() != n {
+        return 0.0;
+    }
+
+    let mut variance = 0.0;
+
+    for i in 0..n {
+        for j in 0..n {
+            if cov_matrix[i].len() > j {
+                variance += weights[i] * weights[j] * cov_matrix[i][j];
+            }
+        }
+    }
+
+    variance.sqrt()
+}
+
+/// Calculate covariance between two return series
+///
+/// # Arguments
+/// * `x` - First return series
+/// * `y` - Second return series
+///
+/// # Returns
+/// Covariance (sample covariance using n-1)
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::portfolio::covariance;
+/// let x = vec![0.01, 0.02, -0.01, 0.03];
+/// let y = vec![0.02, 0.01, -0.02, 0.04];
+/// let cov = covariance(&x, &y);
+/// assert!(cov.is_finite());
+/// ```
+pub fn covariance(x: &[f64], y: &[f64]) -> f64 {
+    if x.len() != y.len() || x.len() < 2 {
+        return 0.0;
+    }
+
+    let n = x.len();
+    let mean_x = mean(x);
+    let mean_y = mean(y);
+
+    let mut sum = 0.0;
+    for i in 0..n {
+        sum += (x[i] - mean_x) * (y[i] - mean_y);
+    }
+
+    sum / (n - 1) as f64
+}
+
+/// Calculate covariance matrix from multiple return series
+///
+/// # Arguments
+/// * `returns_series` - Array of return series (one per asset)
+///
+/// # Returns
+/// Covariance matrix
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::portfolio::covariance_matrix;
+/// let returns_series = vec![
+///     vec![0.01, 0.02, -0.01, 0.03],
+///     vec![0.02, 0.01, -0.02, 0.04],
+/// ];
+/// let cov_matrix = covariance_matrix(&returns_series);
+/// assert_eq!(cov_matrix.len(), 2);
+/// ```
+pub fn covariance_matrix(returns_series: &[Vec<f64>]) -> Vec<Vec<f64>> {
+    let n = returns_series.len();
+    if n == 0 {
+        return vec![];
+    }
+
+    let mut matrix: Vec<Vec<f64>> = vec![vec![0.0; n]; n];
+
+    for i in 0..n {
+        for j in 0..n {
+            matrix[i][j] = covariance(&returns_series[i], &returns_series[j]);
+        }
+    }
+
+    matrix
+}
+
+/// Calculate diversification ratio
+///
+/// Measures how much risk is reduced through diversification.
+/// Ratio > 1 indicates diversification benefit.
+///
+/// # Arguments
+/// * `weights` - Position weights
+/// * `volatilities` - Individual asset volatilities
+/// * `corr_matrix` - Correlation matrix
+///
+/// # Returns
+/// Diversification ratio
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::portfolio::diversification_ratio;
+/// let weights = vec![0.5, 0.5];
+/// let volatilities = vec![0.2, 0.3];
+/// let corr_matrix = vec![vec![1.0, 0.5], vec![0.5, 1.0]];
+/// let ratio = diversification_ratio(&weights, &volatilities, &corr_matrix);
+/// assert!(ratio > 1.0);
+/// ```
+pub fn diversification_ratio(
+    weights: &[f64],
+    volatilities: &[f64],
+    corr_matrix: &[Vec<f64>],
+) -> f64 {
+    let n = weights.len();
+    if n == 0 || volatilities.len() != n || corr_matrix.len() != n {
+        return 1.0;
+    }
+
+    // Weighted average volatility
+    let mut weighted_vol = 0.0;
+    for i in 0..n {
+        weighted_vol += weights[i] * volatilities[i];
+    }
+
+    // Portfolio volatility
+    let mut port_var = 0.0;
+    for i in 0..n {
+        for j in 0..n {
+            if corr_matrix[i].len() > j {
+                port_var += weights[i]
+                    * weights[j]
+                    * volatilities[i]
+                    * volatilities[j]
+                    * corr_matrix[i][j];
+            }
+        }
+    }
+    let port_vol = port_var.sqrt();
+
+    if port_vol > 0.0 {
+        weighted_vol / port_vol
+    } else {
+        1.0
+    }
+}
+
+/// Calculate risk contribution of each asset
+///
+/// Decomposes portfolio risk into contributions from each asset.
+///
+/// # Arguments
+/// * `weights` - Position weights
+/// * `cov_matrix` - Covariance matrix
+///
+/// # Returns
+/// Vector of risk contributions (sums to portfolio volatility)
+///
+/// # Example
+/// ```
+/// use quant_rust::risk::portfolio::risk_contribution;
+/// let weights = vec![0.6, 0.4];
+/// let cov_matrix = vec![vec![0.04, 0.01], vec![0.01, 0.09]];
+/// let contributions = risk_contribution(&weights, &cov_matrix);
+/// assert_eq!(contributions.len(), 2);
+/// ```
+pub fn risk_contribution(weights: &[f64], cov_matrix: &[Vec<f64>]) -> Vec<f64> {
+    let n = weights.len();
+    if n == 0 || cov_matrix.len() != n {
+        return vec![];
+    }
+
+    let port_vol = portfolio_volatility(weights, cov_matrix);
+    if port_vol == 0.0 {
+        return vec![0.0; n];
+    }
+
+    let mut contributions: Vec<f64> = Vec::with_capacity(n);
+
+    for i in 0..n {
+        let mut marginal_contrib = 0.0;
+        for j in 0..n {
+            if cov_matrix[i].len() > j {
+                marginal_contrib += weights[j] * cov_matrix[i][j];
+            }
+        }
+        contributions.push((weights[i] * marginal_contrib) / port_vol);
+    }
+
+    contributions
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_portfolio_volatility() {
+        let weights = vec![0.6, 0.4];
+        let cov_matrix = vec![vec![0.04, 0.01], vec![0.01, 0.09]];
+        let vol = portfolio_volatility(&weights, &cov_matrix);
+        assert!(vol > 0.0);
+    }
+
+    #[test]
+    fn test_portfolio_volatility_empty() {
+        let vol = portfolio_volatility(&[], &[]);
+        assert_eq!(vol, 0.0);
+    }
+
+    #[test]
+    fn test_covariance() {
+        let x = vec![0.01, 0.02, -0.01, 0.03];
+        let y = vec![0.02, 0.01, -0.02, 0.04];
+        let cov = covariance(&x, &y);
+        assert!(cov.is_finite());
+        assert!(cov > 0.0); // Should be positive for these correlated returns
+    }
+
+    #[test]
+    fn test_covariance_mismatched() {
+        let x = vec![0.01, 0.02];
+        let y = vec![0.02];
+        let cov = covariance(&x, &y);
+        assert_eq!(cov, 0.0);
+    }
+
+    #[test]
+    fn test_covariance_matrix() {
+        let returns_series = vec![
+            vec![0.01, 0.02, -0.01, 0.03],
+            vec![0.02, 0.01, -0.02, 0.04],
+        ];
+        let cov_matrix = covariance_matrix(&returns_series);
+        assert_eq!(cov_matrix.len(), 2);
+        assert_eq!(cov_matrix[0].len(), 2);
+    }
+
+    #[test]
+    fn test_diversification_ratio() {
+        let weights = vec![0.5, 0.5];
+        let volatilities = vec![0.2, 0.3];
+        let corr_matrix = vec![vec![1.0, 0.5], vec![0.5, 1.0]];
+        let ratio = diversification_ratio(&weights, &volatilities, &corr_matrix);
+        // With less than perfect correlation, diversification ratio > 1
+        assert!(ratio > 1.0);
+    }
+
+    #[test]
+    fn test_risk_contribution() {
+        let weights = vec![0.6, 0.4];
+        let cov_matrix = vec![vec![0.04, 0.01], vec![0.01, 0.09]];
+        let contributions = risk_contribution(&weights, &cov_matrix);
+        assert_eq!(contributions.len(), 2);
+        // Sum should approximately equal portfolio volatility
+        let port_vol = portfolio_volatility(&weights, &cov_matrix);
+        let sum: f64 = contributions.iter().sum();
+        assert!((sum - port_vol).abs() < 1e-10);
+    }
+}