quantmllibrary 0.1.0__py3-none-any.whl

quantml/training/alpha_eval.py

@@ -0,0 +1,203 @@
+"""
+Alpha evaluation framework for signal quality assessment.
+
+This module provides tools for evaluating alpha signals, including
+Information Coefficient (IC), turnover analysis, decay analysis, and more.
+"""
+
+from typing import List, Optional, Dict, Any, Union
+from quantml.training.metrics import information_coefficient, rank_ic, turnover
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+class AlphaEvaluator:
+    """
+    Alpha signal quality evaluator.
+    
+    This class provides comprehensive evaluation of alpha signals,
+    including IC analysis, turnover, decay, and factor exposure.
+    
+    Attributes:
+        predictions: List of predictions/signals
+        actuals: List of actual/realized values
+        timestamps: Optional timestamps for time-based analysis
+    
+    Examples:
+        >>> evaluator = AlphaEvaluator(predictions, actuals)
+        >>> metrics = evaluator.evaluate()
+        >>> print(f"IC: {metrics['ic']}, Rank IC: {metrics['rank_ic']}")
+    """
+    
+    def __init__(
+        self,
+        predictions: List[float],
+        actuals: List[float],
+        timestamps: Optional[List] = None
+    ):
+        """
+        Initialize alpha evaluator.
+        
+        Args:
+            predictions: Predicted values/signals
+            actuals: Actual/realized values
+            timestamps: Optional timestamps for time-based analysis
+        """
+        if len(predictions) != len(actuals):
+            raise ValueError("predictions and actuals must have same length")
+        
+        self.predictions = predictions
+        self.actuals = actuals
+        self.timestamps = timestamps if timestamps else list(range(len(predictions)))
+        self.n = len(predictions)
+    
+    def evaluate(self) -> Dict[str, Any]:
+        """
+        Perform comprehensive alpha evaluation.
+        
+        Returns:
+            Dictionary with evaluation metrics
+        """
+        metrics = {}
+        
+        # Basic IC metrics
+        metrics['ic'] = information_coefficient(self.predictions, self.actuals)
+        metrics['rank_ic'] = rank_ic(self.predictions, self.actuals)
+        
+        # Turnover analysis
+        metrics['turnover'] = turnover(self.predictions)
+        
+        # Decay analysis
+        decay_metrics = self.decay_analysis()
+        metrics.update(decay_metrics)
+        
+        # Hit rate
+        from quantml.training.metrics import hit_rate
+        metrics['hit_rate'] = hit_rate(self.predictions, self.actuals)
+        
+        # Signal statistics
+        metrics['signal_mean'] = sum(self.predictions) / len(self.predictions)
+        metrics['signal_std'] = self._std(self.predictions)
+        
+        return metrics
+    
+    def decay_analysis(self, max_lag: int = 5) -> Dict[str, Any]:
+        """
+        Analyze signal decay over time (how long signal remains predictive).
+        
+        Args:
+            max_lag: Maximum lag to analyze
+        
+        Returns:
+            Dictionary with decay metrics
+        """
+        decay_ics = []
+        
+        for lag in range(max_lag + 1):
+            if lag == 0:
+                # Current IC
+                ic = information_coefficient(self.predictions, self.actuals)
+            else:
+                # IC at lag
+                if lag < len(self.predictions):
+                    pred_lag = self.predictions[:-lag] if lag > 0 else self.predictions
+                    actual_lag = self.actuals[lag:]
+                    if len(pred_lag) == len(actual_lag) and len(pred_lag) > 0:
+                        ic = information_coefficient(pred_lag, actual_lag)
+                    else:
+                        ic = 0.0
+                else:
+                    ic = 0.0
+            decay_ics.append(ic)
+        
+        # Calculate half-life (lag where IC drops to half)
+        initial_ic = abs(decay_ics[0]) if decay_ics else 0.0
+        half_ic = initial_ic / 2.0
+        
+        half_life = max_lag
+        for i, ic in enumerate(decay_ics):
+            if abs(ic) <= half_ic:
+                half_life = i
+                break
+        
+        return {
+            'decay_ics': decay_ics,
+            'half_life': half_life,
+            'initial_ic': initial_ic,
+            'decay_rate': (decay_ics[0] - decay_ics[-1]) / max_lag if max_lag > 0 else 0.0
+        }
+    
+    def rolling_ic(self, window: int = 21) -> List[float]:
+        """
+        Calculate rolling Information Coefficient.
+        
+        Args:
+            window: Rolling window size
+        
+        Returns:
+            List of rolling IC values
+        """
+        rolling_ics = []
+        
+        for i in range(window, len(self.predictions)):
+            pred_window = self.predictions[i-window:i]
+            actual_window = self.actuals[i-window:i]
+            ic = information_coefficient(pred_window, actual_window)
+            rolling_ics.append(ic)
+        
+        return rolling_ics
+    
+    def factor_exposure(self, factors: Dict[str, List[float]]) -> Dict[str, float]:
+        """
+        Calculate factor exposure of predictions.
+        
+        Args:
+            factors: Dictionary of factor name -> factor values
+        
+        Returns:
+            Dictionary of factor exposures (correlations)
+        """
+        exposures = {}
+        
+        for factor_name, factor_values in factors.items():
+            if len(factor_values) != len(self.predictions):
+                continue
+            exposure = information_coefficient(self.predictions, factor_values)
+            exposures[factor_name] = exposure
+        
+        return exposures
+    
+    def _std(self, values: List[float]) -> float:
+        """Calculate standard deviation."""
+        if len(values) == 0:
+            return 0.0
+        mean_val = sum(values) / len(values)
+        variance = sum((v - mean_val) ** 2 for v in values) / len(values)
+        return variance ** 0.5
+
+
+def evaluate_alpha_signals(
+    predictions: List[float],
+    actuals: List[float],
+    timestamps: Optional[List] = None
+) -> Dict[str, Any]:
+    """
+    Convenience function for alpha evaluation.
+    
+    Args:
+        predictions: Predicted values
+        actuals: Actual values
+        timestamps: Optional timestamps
+    
+    Returns:
+        Evaluation metrics dictionary
+    """
+    evaluator = AlphaEvaluator(predictions, actuals, timestamps)
+    return evaluator.evaluate()
+

quantml/training/backtest.py

@@ -0,0 +1,280 @@
+"""
+Backtesting engine for strategy evaluation.
+
+This module provides a backtesting framework for evaluating trading strategies
+with position sizing, transaction costs, and performance metrics.
+"""
+
+from typing import List, Optional, Callable, Dict, Any
+from quantml.training.metrics import (
+    sharpe_ratio, sortino_ratio, calmar_ratio, max_drawdown
+)
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+class BacktestEngine:
+    """
+    Backtesting engine for strategy evaluation.
+    
+    This class simulates trading a strategy on historical data, tracking
+    positions, P&L, and performance metrics.
+    
+    Attributes:
+        initial_capital: Starting capital
+        commission: Commission per trade (as fraction)
+        slippage: Slippage per trade (as fraction)
+        position_sizing: Position sizing function
+    
+    Examples:
+        >>> engine = BacktestEngine(initial_capital=100000)
+        >>> signals = [0.5, -0.3, 0.8, ...]  # Trading signals
+        >>> prices = [100, 101, 102, ...]   # Price data
+        >>> results = engine.run(signals, prices)
+    """
+    
+    def __init__(
+        self,
+        initial_capital: float = 100000.0,
+        commission: float = 0.001,  # 0.1%
+        slippage: float = 0.0005,   # 0.05%
+        position_sizing: Optional[Callable] = None
+    ):
+        """
+        Initialize backtesting engine.
+        
+        Args:
+            initial_capital: Starting capital
+            commission: Commission rate per trade
+            slippage: Slippage rate per trade
+            position_sizing: Function to determine position size from signal
+                            Default: signal * capital (simple)
+        """
+        self.initial_capital = initial_capital
+        self.commission = commission
+        self.slippage = slippage
+        self.position_sizing = position_sizing if position_sizing else self._default_position_sizing
+    
+    def _default_position_sizing(self, signal: float, capital: float, price: float) -> float:
+        """Default position sizing: signal * capital / price."""
+        return signal * capital / price if price > 0 else 0.0
+    
+    def run(
+        self,
+        signals: List[float],
+        prices: List[float],
+        volumes: Optional[List[float]] = None
+    ) -> Dict[str, Any]:
+        """
+        Run backtest on signals and prices.
+        
+        Args:
+            signals: Trading signals (-1 to 1, or position sizes)
+            prices: Price data
+            volumes: Optional volume data (for VWAP execution)
+        
+        Returns:
+            Dictionary with backtest results and metrics
+        """
+        if len(signals) != len(prices):
+            raise ValueError("signals and prices must have same length")
+        
+        n = len(signals)
+        capital = self.initial_capital
+        position = 0.0  # Current position (number of shares)
+        equity_curve = [capital]
+        trades = []
+        returns = []
+        
+        for i in range(n):
+            signal = signals[i]
+            price = prices[i]
+            
+            # Determine target position
+            target_position_value = self.position_sizing(signal, capital, price)
+            target_position = target_position_value / price if price > 0 else 0.0
+            
+            # Calculate trade
+            trade_size = target_position - position
+            
+            if abs(trade_size) > 1e-6:  # Only trade if significant
+                # Apply slippage
+                execution_price = price * (1 + self.slippage * (1 if trade_size > 0 else -1))
+                
+                # Calculate costs
+                trade_value = abs(trade_size * execution_price)
+                commission_cost = trade_value * self.commission
+                slippage_cost = abs(trade_size * price * self.slippage)
+                total_cost = commission_cost + slippage_cost
+                
+                # Update capital
+                capital -= trade_size * execution_price + total_cost
+                
+                # Update position
+                position = target_position
+                
+                trades.append({
+                    'index': i,
+                    'price': price,
+                    'execution_price': execution_price,
+                    'size': trade_size,
+                    'cost': total_cost
+                })
+            
+            # Update equity
+            current_value = capital + position * price
+            equity_curve.append(current_value)
+            
+            # Calculate return
+            if i > 0:
+                prev_value = equity_curve[-2]
+                ret = (current_value - prev_value) / prev_value if prev_value > 0 else 0.0
+                returns.append(ret)
+        
+        # Calculate metrics
+        final_value = equity_curve[-1]
+        total_return = (final_value - self.initial_capital) / self.initial_capital
+        
+        # Performance metrics
+        sharpe = sharpe_ratio(returns) if returns else 0.0
+        sortino = sortino_ratio(returns) if returns else 0.0
+        calmar = calmar_ratio(returns) if returns else 0.0
+        max_dd = max_drawdown(returns) if returns else 0.0
+        
+        # Calculate trade-level P&L
+        completed_trades = []
+        open_trade = None
+        
+        for i, trade in enumerate(trades):
+            if open_trade is None:
+                # Open new trade
+                open_trade = {
+                    'entry_index': trade['index'],
+                    'entry_price': trade['execution_price'],
+                    'entry_size': trade['size'],
+                    'direction': 1 if trade['size'] > 0 else -1
+                }
+            else:
+                # Check if trade closes position
+                if (open_trade['direction'] > 0 and trade['size'] < 0) or \
+                   (open_trade['direction'] < 0 and trade['size'] > 0):
+                    # Close trade
+                    exit_price = trade['execution_price']
+                    exit_size = abs(trade['size'])
+                    entry_size = abs(open_trade['entry_size'])
+                    
+                    # Calculate P&L
+                    if open_trade['direction'] > 0:  # Long
+                        pnl = (exit_price - open_trade['entry_price']) * min(entry_size, exit_size)
+                    else:  # Short
+                        pnl = (open_trade['entry_price'] - exit_price) * min(entry_size, exit_size)
+                    
+                    pnl -= trade['cost']  # Subtract exit cost
+                    
+                    completed_trades.append({
+                        'entry_index': open_trade['entry_index'],
+                        'exit_index': trade['index'],
+                        'entry_price': open_trade['entry_price'],
+                        'exit_price': exit_price,
+                        'size': min(entry_size, exit_size),
+                        'direction': open_trade['direction'],
+                        'pnl': pnl,
+                        'duration': trade['index'] - open_trade['entry_index'],
+                        'return_pct': pnl / (open_trade['entry_price'] * min(entry_size, exit_size)) if open_trade['entry_price'] > 0 else 0.0
+                    })
+                    
+                    # Update open trade if partial close
+                    if exit_size < entry_size:
+                        open_trade['entry_size'] = open_trade['entry_size'] - (exit_size if open_trade['direction'] > 0 else -exit_size)
+                    else:
+                        open_trade = None
+        
+        # Trade statistics
+        n_trades = len(trades)
+        n_completed_trades = len(completed_trades)
+        winning_trades = [t for t in completed_trades if t['pnl'] > 0]
+        losing_trades = [t for t in completed_trades if t['pnl'] <= 0]
+        
+        win_rate = len(winning_trades) / n_completed_trades if n_completed_trades > 0 else 0.0
+        avg_win = sum(t['pnl'] for t in winning_trades) / len(winning_trades) if winning_trades else 0.0
+        avg_loss = sum(t['pnl'] for t in losing_trades) / len(losing_trades) if losing_trades else 0.0
+        profit_factor = abs(sum(t['pnl'] for t in winning_trades) / sum(t['pnl'] for t in losing_trades)) if losing_trades and sum(t['pnl'] for t in losing_trades) != 0 else float('inf') if winning_trades else 0.0
+        
+        avg_duration = sum(t['duration'] for t in completed_trades) / n_completed_trades if n_completed_trades > 0 else 0.0
+        
+        return {
+            'initial_capital': self.initial_capital,
+            'final_value': final_value,
+            'total_return': total_return,
+            'equity_curve': equity_curve,
+            'returns': returns,
+            'trades': trades,
+            'completed_trades': completed_trades,
+            'n_trades': n_trades,
+            'n_completed_trades': n_completed_trades,
+            'win_rate': win_rate,
+            'avg_win': avg_win,
+            'avg_loss': avg_loss,
+            'profit_factor': profit_factor,
+            'avg_duration': avg_duration,
+            'sharpe_ratio': sharpe,
+            'sortino_ratio': sortino,
+            'calmar_ratio': calmar,
+            'max_drawdown': max_dd
+        }
+    
+    def run_with_predictions(
+        self,
+        predictions: List[float],
+        prices: List[float],
+        targets: Optional[List[float]] = None
+    ) -> Dict[str, Any]:
+        """
+        Run backtest using model predictions as signals.
+        
+        Args:
+            predictions: Model predictions (can be returns, prices, or signals)
+            prices: Price data
+            targets: Optional target returns (for comparison)
+        
+        Returns:
+            Backtest results dictionary
+        """
+        # Convert predictions to signals (normalize to -1 to 1)
+        if HAS_NUMPY:
+            try:
+                pred_arr = np.array(predictions)
+                # Normalize to [-1, 1]
+                pred_min, pred_max = np.min(pred_arr), np.max(pred_arr)
+                if pred_max > pred_min:
+                    signals = 2 * (pred_arr - pred_min) / (pred_max - pred_min) - 1
+                else:
+                    signals = pred_arr * 0  # All zeros
+                signals = signals.tolist()
+            except (ValueError, TypeError):
+                signals = predictions
+        else:
+            # Pure Python normalization
+            pred_min = min(predictions)
+            pred_max = max(predictions)
+            if pred_max > pred_min:
+                signals = [2 * (p - pred_min) / (pred_max - pred_min) - 1 for p in predictions]
+            else:
+                signals = [0.0] * len(predictions)
+        
+        results = self.run(signals, prices)
+        
+        if targets is not None:
+            # Add prediction accuracy metrics
+            from quantml.training.metrics import information_coefficient, hit_rate
+            results['ic'] = information_coefficient(predictions, targets)
+            results['hit_rate'] = hit_rate(predictions, targets)
+        
+        return results
+

quantml/training/backtest_analysis.py

@@ -0,0 +1,168 @@
+"""
+Backtest analysis and visualization utilities.
+
+Provides trade-level analysis, performance heatmaps, and regime-based breakdowns.
+"""
+
+from typing import List, Dict, Any, Optional
+from collections import defaultdict
+
+
+def analyze_trades(completed_trades: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+    Analyze completed trades for detailed statistics.
+    
+    Args:
+        completed_trades: List of completed trade dictionaries
+    
+    Returns:
+        Dictionary with trade analysis
+    """
+    if not completed_trades:
+        return {
+            'n_trades': 0,
+            'win_rate': 0.0,
+            'avg_win': 0.0,
+            'avg_loss': 0.0,
+            'profit_factor': 0.0,
+            'avg_duration': 0.0
+        }
+    
+    winning_trades = [t for t in completed_trades if t.get('pnl', 0) > 0]
+    losing_trades = [t for t in completed_trades if t.get('pnl', 0) <= 0]
+    
+    win_rate = len(winning_trades) / len(completed_trades)
+    avg_win = sum(t['pnl'] for t in winning_trades) / len(winning_trades) if winning_trades else 0.0
+    avg_loss = sum(t['pnl'] for t in losing_trades) / len(losing_trades) if losing_trades else 0.0
+    
+    total_win = sum(t['pnl'] for t in winning_trades)
+    total_loss = abs(sum(t['pnl'] for t in losing_trades))
+    profit_factor = total_win / total_loss if total_loss > 0 else float('inf') if total_win > 0 else 0.0
+    
+    avg_duration = sum(t.get('duration', 0) for t in completed_trades) / len(completed_trades)
+    
+    # Largest win/loss
+    largest_win = max((t['pnl'] for t in winning_trades), default=0.0)
+    largest_loss = min((t['pnl'] for t in losing_trades), default=0.0)
+    
+    return {
+        'n_trades': len(completed_trades),
+        'win_rate': win_rate,
+        'avg_win': avg_win,
+        'avg_loss': avg_loss,
+        'profit_factor': profit_factor,
+        'avg_duration': avg_duration,
+        'largest_win': largest_win,
+        'largest_loss': largest_loss,
+        'total_pnl': sum(t['pnl'] for t in completed_trades)
+    }
+
+
+def create_performance_heatmap(
+    trades: List[Dict[str, Any]],
+    prices: List[float],
+    regimes: Optional[List[int]] = None,
+    time_of_day: Optional[List[int]] = None
+) -> Dict[str, Any]:
+    """
+    Create performance heatmap by regime and time of day.
+    
+    Args:
+        trades: List of trades
+        prices: Price data
+        regimes: Regime labels (0=low, 1=normal, 2=high)
+        time_of_day: Hour of day (0-23)
+    
+    Returns:
+        Dictionary with heatmap data
+    """
+    if not trades:
+        return {}
+    
+    # Group trades by regime and time
+    heatmap_data = defaultdict(lambda: {'pnl': 0.0, 'count': 0})
+    
+    for trade in trades:
+        idx = trade.get('index', 0)
+        
+        regime = regimes[idx] if regimes and idx < len(regimes) else 1  # Default to normal
+        hour = time_of_day[idx] if time_of_day and idx < len(time_of_day) else 12  # Default to noon
+        
+        key = f"regime_{regime}_hour_{hour}"
+        heatmap_data[key]['pnl'] += trade.get('pnl', 0.0)
+        heatmap_data[key]['count'] += 1
+    
+    # Convert to structured format
+    result = {}
+    for key, data in heatmap_data.items():
+        result[key] = {
+            'pnl': data['pnl'],
+            'count': data['count'],
+            'avg_pnl': data['pnl'] / data['count'] if data['count'] > 0 else 0.0
+        }
+    
+    return result
+
+
+def analyze_by_regime(
+    completed_trades: List[Dict[str, Any]],
+    regimes: List[int]
+) -> Dict[int, Dict[str, Any]]:
+    """
+    Analyze performance by volatility/volume regime.
+    
+    Args:
+        completed_trades: Completed trades
+        regimes: Regime labels for each time period
+    
+    Returns:
+        Dictionary mapping regime -> statistics
+    """
+    regime_trades = defaultdict(list)
+    
+    for trade in completed_trades:
+        entry_idx = trade.get('entry_index', 0)
+        if entry_idx < len(regimes):
+            regime = regimes[entry_idx]
+            regime_trades[regime].append(trade)
+    
+    results = {}
+    for regime, trades in regime_trades.items():
+        results[regime] = analyze_trades(trades)
+        results[regime]['regime'] = regime
+        results[regime]['n_trades'] = len(trades)
+    
+    return results
+
+
+def create_trade_summary(completed_trades: List[Dict[str, Any]]) -> str:
+    """
+    Create human-readable trade summary.
+    
+    Args:
+        completed_trades: Completed trades
+    
+    Returns:
+        Formatted summary string
+    """
+    if not completed_trades:
+        return "No completed trades."
+    
+    analysis = analyze_trades(completed_trades)
+    
+    summary = f"""
+Trade Summary
+=============
+Total Trades: {analysis['n_trades']}
+Win Rate: {analysis['win_rate']*100:.2f}%
+Average Win: ${analysis['avg_win']:.2f}
+Average Loss: ${analysis['avg_loss']:.2f}
+Profit Factor: {analysis['profit_factor']:.2f}
+Average Duration: {analysis['avg_duration']:.1f} periods
+Largest Win: ${analysis['largest_win']:.2f}
+Largest Loss: ${analysis['largest_loss']:.2f}
+Total P&L: ${analysis['total_pnl']:.2f}
+"""
+    
+    return summary
+