bulltrackers-module 1.0.733 → 1.0.734

package/functions/computation-system-v2/rules/metrics.js

@@ -0,0 +1,304 @@
+/**
+ * @fileoverview Financial Metrics Business Rules
+ * 
+ * Single source of truth for financial metric calculations.
+ * These rules are automatically injected into computations.
+ * 
+ * Usage in computation:
+ * ```javascript
+ * const sharpe = rules.metrics.calculateSharpeRatio(returns, riskFreeRate);
+ * const sortino = rules.metrics.calculateSortinoRatio(returns, targetReturn);
+ * ```
+ */
+
+/**
+ * Calculate the mean (average) of an array of numbers.
+ * 
+ * @param {number[]} values - Array of numbers
+ * @returns {number} Mean value
+ */
+function mean(values) {
+    if (!Array.isArray(values) || values.length === 0) return 0;
+    return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+
+/**
+ * Calculate the standard deviation of an array of numbers.
+ * 
+ * @param {number[]} values - Array of numbers
+ * @param {boolean} [population=false] - Use population std dev (N) vs sample (N-1)
+ * @returns {number} Standard deviation
+ */
+function standardDeviation(values, population = false) {
+    if (!Array.isArray(values) || values.length < 2) return 0;
+    
+    const avg = mean(values);
+    const squaredDiffs = values.map(v => Math.pow(v - avg, 2));
+    const divisor = population ? values.length : values.length - 1;
+    
+    return Math.sqrt(squaredDiffs.reduce((sum, v) => sum + v, 0) / divisor);
+}
+
+/**
+ * Calculate the downside deviation (only negative returns).
+ * 
+ * @param {number[]} returns - Array of return values
+ * @param {number} [targetReturn=0] - Minimum acceptable return
+ * @returns {number} Downside deviation
+ */
+function downsideDeviation(returns, targetReturn = 0) {
+    if (!Array.isArray(returns) || returns.length === 0) return 0;
+    
+    const downsideReturns = returns
+        .filter(r => r < targetReturn)
+        .map(r => Math.pow(r - targetReturn, 2));
+    
+    if (downsideReturns.length === 0) return 0;
+    
+    return Math.sqrt(downsideReturns.reduce((sum, v) => sum + v, 0) / returns.length);
+}
+
+/**
+ * Calculate the Sharpe Ratio.
+ * Measures risk-adjusted return compared to risk-free rate.
+ * 
+ * Formula: (Mean Return - Risk-Free Rate) / Standard Deviation
+ * 
+ * @param {number[]} returns - Array of return values (as percentages)
+ * @param {number} [riskFreeRate=0] - Risk-free rate (annualized %)
+ * @param {number} [periodsPerYear=252] - Trading periods per year
+ * @returns {number} Sharpe ratio
+ */
+function calculateSharpeRatio(returns, riskFreeRate = 0, periodsPerYear = 252) {
+    if (!Array.isArray(returns) || returns.length < 2) return 0;
+    
+    const meanReturn = mean(returns);
+    const stdDev = standardDeviation(returns);
+    
+    if (stdDev === 0) return 0;
+    
+    // Convert risk-free rate to per-period rate
+    const periodRiskFree = riskFreeRate / periodsPerYear;
+    
+    // Calculate and annualize
+    const sharpe = (meanReturn - periodRiskFree) / stdDev;
+    return sharpe * Math.sqrt(periodsPerYear);
+}
+
+/**
+ * Calculate the Sortino Ratio.
+ * Like Sharpe but only penalizes downside volatility.
+ * 
+ * Formula: (Mean Return - Target Return) / Downside Deviation
+ * 
+ * @param {number[]} returns - Array of return values (as percentages)
+ * @param {number} [targetReturn=0] - Minimum acceptable return
+ * @param {number} [periodsPerYear=252] - Trading periods per year
+ * @returns {number} Sortino ratio
+ */
+function calculateSortinoRatio(returns, targetReturn = 0, periodsPerYear = 252) {
+    if (!Array.isArray(returns) || returns.length < 2) return 0;
+    
+    const meanReturn = mean(returns);
+    const downside = downsideDeviation(returns, targetReturn);
+    
+    if (downside === 0) {
+        // No downside deviation means all returns >= target
+        return meanReturn > targetReturn ? Infinity : 0;
+    }
+    
+    const sortino = (meanReturn - targetReturn) / downside;
+    return sortino * Math.sqrt(periodsPerYear);
+}
+
+/**
+ * Calculate the Maximum Drawdown.
+ * The largest peak-to-trough decline.
+ * 
+ * @param {number[]} values - Array of cumulative values or returns
+ * @returns {Object} { maxDrawdown, peakIndex, troughIndex }
+ */
+function calculateMaxDrawdown(values) {
+    if (!Array.isArray(values) || values.length < 2) {
+        return { maxDrawdown: 0, peakIndex: 0, troughIndex: 0 };
+    }
+    
+    let peak = values[0];
+    let peakIndex = 0;
+    let maxDrawdown = 0;
+    let maxDrawdownPeak = 0;
+    let maxDrawdownTrough = 0;
+    
+    for (let i = 1; i < values.length; i++) {
+        if (values[i] > peak) {
+            peak = values[i];
+            peakIndex = i;
+        }
+        
+        const drawdown = peak > 0 ? (peak - values[i]) / peak : 0;
+        
+        if (drawdown > maxDrawdown) {
+            maxDrawdown = drawdown;
+            maxDrawdownPeak = peakIndex;
+            maxDrawdownTrough = i;
+        }
+    }
+    
+    return {
+        maxDrawdown: maxDrawdown * 100,  // As percentage
+        peakIndex: maxDrawdownPeak,
+        troughIndex: maxDrawdownTrough
+    };
+}
+
+/**
+ * Calculate the Calmar Ratio.
+ * Annualized return divided by maximum drawdown.
+ * 
+ * @param {number[]} returns - Array of return values
+ * @param {number[]} values - Array of cumulative portfolio values
+ * @param {number} [periodsPerYear=252] - Trading periods per year
+ * @returns {number} Calmar ratio
+ */
+function calculateCalmarRatio(returns, values, periodsPerYear = 252) {
+    if (!Array.isArray(returns) || returns.length === 0) return 0;
+    
+    const annualizedReturn = mean(returns) * periodsPerYear;
+    const { maxDrawdown } = calculateMaxDrawdown(values);
+    
+    if (maxDrawdown === 0) return 0;
+    
+    return annualizedReturn / maxDrawdown;
+}
+
+/**
+ * Calculate Value at Risk (VaR).
+ * The maximum loss at a given confidence level.
+ * 
+ * @param {number[]} returns - Array of return values
+ * @param {number} [confidenceLevel=0.95] - Confidence level (e.g., 0.95 for 95%)
+ * @returns {number} VaR as positive number
+ */
+function calculateVaR(returns, confidenceLevel = 0.95) {
+    if (!Array.isArray(returns) || returns.length < 10) return 0;
+    
+    const sorted = [...returns].sort((a, b) => a - b);
+    const index = Math.floor((1 - confidenceLevel) * sorted.length);
+    
+    return -sorted[index];  // Return as positive number
+}
+
+/**
+ * Calculate information ratio.
+ * Measures return above benchmark per unit of tracking error.
+ * 
+ * @param {number[]} returns - Portfolio returns
+ * @param {number[]} benchmarkReturns - Benchmark returns
+ * @returns {number} Information ratio
+ */
+function calculateInformationRatio(returns, benchmarkReturns) {
+    if (!Array.isArray(returns) || !Array.isArray(benchmarkReturns)) return 0;
+    if (returns.length !== benchmarkReturns.length || returns.length < 2) return 0;
+    
+    const excessReturns = returns.map((r, i) => r - benchmarkReturns[i]);
+    const meanExcess = mean(excessReturns);
+    const trackingError = standardDeviation(excessReturns);
+    
+    if (trackingError === 0) return 0;
+    
+    return meanExcess / trackingError;
+}
+
+/**
+ * Calculate beta (systematic risk).
+ * 
+ * @param {number[]} returns - Asset returns
+ * @param {number[]} marketReturns - Market/benchmark returns
+ * @returns {number} Beta coefficient
+ */
+function calculateBeta(returns, marketReturns) {
+    if (!Array.isArray(returns) || !Array.isArray(marketReturns)) return 1;
+    if (returns.length !== marketReturns.length || returns.length < 2) return 1;
+    
+    const meanAsset = mean(returns);
+    const meanMarket = mean(marketReturns);
+    
+    let covariance = 0;
+    let marketVariance = 0;
+    
+    for (let i = 0; i < returns.length; i++) {
+        const assetDiff = returns[i] - meanAsset;
+        const marketDiff = marketReturns[i] - meanMarket;
+        
+        covariance += assetDiff * marketDiff;
+        marketVariance += marketDiff * marketDiff;
+    }
+    
+    if (marketVariance === 0) return 1;
+    
+    return covariance / marketVariance;
+}
+
+/**
+ * Calculate alpha (excess return over expected).
+ * 
+ * @param {number[]} returns - Asset returns
+ * @param {number[]} marketReturns - Market/benchmark returns
+ * @param {number} [riskFreeRate=0] - Risk-free rate
+ * @returns {number} Alpha
+ */
+function calculateAlpha(returns, marketReturns, riskFreeRate = 0) {
+    const beta = calculateBeta(returns, marketReturns);
+    const meanReturn = mean(returns);
+    const meanMarket = mean(marketReturns);
+    
+    // Alpha = R - [Rf + Beta * (Rm - Rf)]
+    return meanReturn - (riskFreeRate + beta * (meanMarket - riskFreeRate));
+}
+
+/**
+ * Round a number to specified decimal places.
+ * 
+ * @param {number} value - Value to round
+ * @param {number} [decimals=2] - Number of decimal places
+ * @returns {number} Rounded value
+ */
+function round(value, decimals = 2) {
+    if (typeof value !== 'number' || isNaN(value)) return 0;
+    return Number(value.toFixed(decimals));
+}
+
+/**
+ * Clamp a value between min and max.
+ * 
+ * @param {number} value - Value to clamp
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @returns {number} Clamped value
+ */
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+
+module.exports = {
+    // Basic statistics
+    mean,
+    standardDeviation,
+    downsideDeviation,
+    
+    // Risk-adjusted returns
+    calculateSharpeRatio,
+    calculateSortinoRatio,
+    calculateCalmarRatio,
+    calculateInformationRatio,
+    
+    // Risk metrics
+    calculateMaxDrawdown,
+    calculateVaR,
+    calculateBeta,
+    calculateAlpha,
+    
+    // Utilities
+    round,
+    clamp
+};