quantmllibrary 0.1.0__py3-none-any.whl

quantml/training/metrics.py

@@ -0,0 +1,376 @@
+"""
+Financial and prediction metrics for quant model evaluation.
+
+This module provides metrics commonly used in quantitative trading,
+including Sharpe ratio, Information Coefficient (IC), drawdown, and more.
+"""
+
+from typing import List, Optional, Union
+import math
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+def sharpe_ratio(returns: Union[List, any], risk_free_rate: float = 0.0, annualize: bool = True) -> float:
+    """
+    Calculate Sharpe ratio: (mean(returns) - risk_free_rate) / std(returns)
+    
+    Args:
+        returns: List of returns
+        risk_free_rate: Risk-free rate (default: 0.0)
+        annualize: Whether to annualize (multiply by sqrt(252))
+    
+    Returns:
+        Sharpe ratio
+    """
+    if len(returns) == 0:
+        return 0.0
+    
+    if HAS_NUMPY:
+        try:
+            ret_arr = np.array(returns, dtype=np.float64)
+            mean_ret = np.mean(ret_arr)
+            std_ret = np.std(ret_arr)
+            if std_ret == 0:
+                return 0.0
+            sharpe = (mean_ret - risk_free_rate) / std_ret
+            if annualize:
+                sharpe *= math.sqrt(252)
+            return float(sharpe)
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    mean_ret = sum(returns) / len(returns)
+    variance = sum((r - mean_ret) ** 2 for r in returns) / len(returns)
+    std_ret = math.sqrt(variance) if variance > 0 else 0.0
+    
+    if std_ret == 0:
+        return 0.0
+    
+    sharpe = (mean_ret - risk_free_rate) / std_ret
+    if annualize:
+        sharpe *= math.sqrt(252)
+    return sharpe
+
+
+def sortino_ratio(returns: Union[List, any], risk_free_rate: float = 0.0, annualize: bool = True) -> float:
+    """
+    Calculate Sortino ratio: (mean(returns) - risk_free_rate) / downside_std(returns)
+    
+    Args:
+        returns: List of returns
+        risk_free_rate: Risk-free rate
+        annualize: Whether to annualize
+    
+    Returns:
+        Sortino ratio
+    """
+    if len(returns) == 0:
+        return 0.0
+    
+    if HAS_NUMPY:
+        try:
+            ret_arr = np.array(returns, dtype=np.float64)
+            mean_ret = np.mean(ret_arr)
+            # Downside deviation: only negative returns
+            downside = ret_arr[ret_arr < 0]
+            if len(downside) == 0:
+                return float('inf') if mean_ret > risk_free_rate else 0.0
+            downside_std = np.std(downside)
+            if downside_std == 0:
+                return 0.0
+            sortino = (mean_ret - risk_free_rate) / downside_std
+            if annualize:
+                sortino *= math.sqrt(252)
+            return float(sortino)
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    mean_ret = sum(returns) / len(returns)
+    downside = [r for r in returns if r < 0]
+    if len(downside) == 0:
+        return float('inf') if mean_ret > risk_free_rate else 0.0
+    
+    downside_mean = sum(downside) / len(downside)
+    downside_var = sum((d - downside_mean) ** 2 for d in downside) / len(downside)
+    downside_std = math.sqrt(downside_var) if downside_var > 0 else 0.0
+    
+    if downside_std == 0:
+        return 0.0
+    
+    sortino = (mean_ret - risk_free_rate) / downside_std
+    if annualize:
+        sortino *= math.sqrt(252)
+    return sortino
+
+
+def calmar_ratio(returns: Union[List, any], annualize: bool = True) -> float:
+    """
+    Calculate Calmar ratio: annual_return / max_drawdown
+    
+    Args:
+        returns: List of returns
+        annualize: Whether to annualize returns
+    
+    Returns:
+        Calmar ratio
+    """
+    if len(returns) == 0:
+        return 0.0
+    
+    annual_return = sum(returns) / len(returns)
+    if annualize:
+        annual_return *= 252
+    
+    max_dd = max_drawdown(returns)
+    if max_dd == 0:
+        return 0.0
+    
+    return abs(annual_return / max_dd)
+
+
+def max_drawdown(returns: Union[List, any]) -> float:
+    """
+    Calculate maximum drawdown.
+    
+    Args:
+        returns: List of returns
+    
+    Returns:
+        Maximum drawdown (as positive value)
+    """
+    if len(returns) == 0:
+        return 0.0
+    
+    if HAS_NUMPY:
+        try:
+            ret_arr = np.array(returns, dtype=np.float64)
+            # Cumulative returns
+            cum_ret = np.cumprod(1 + ret_arr)
+            # Running maximum
+            running_max = np.maximum.accumulate(cum_ret)
+            # Drawdown
+            drawdown = (cum_ret - running_max) / running_max
+            return float(abs(np.min(drawdown)))
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    cum_ret = 1.0
+    running_max = 1.0
+    max_dd = 0.0
+    
+    for ret in returns:
+        cum_ret *= (1 + ret)
+        running_max = max(running_max, cum_ret)
+        dd = (cum_ret - running_max) / running_max
+        max_dd = min(max_dd, dd)
+    
+    return abs(max_dd)
+
+
+def information_coefficient(predictions: Union[List, any], actuals: Union[List, any]) -> float:
+    """
+    Calculate Information Coefficient (IC): correlation between predictions and actuals.
+    
+    Args:
+        predictions: Predicted values
+        actuals: Actual/realized values
+    
+    Returns:
+        IC (correlation coefficient)
+    """
+    if len(predictions) != len(actuals) or len(predictions) == 0:
+        return 0.0
+    
+    if HAS_NUMPY:
+        try:
+            pred_arr = np.array(predictions, dtype=np.float64)
+            actual_arr = np.array(actuals, dtype=np.float64)
+            # Pearson correlation
+            corr = np.corrcoef(pred_arr, actual_arr)[0, 1]
+            return float(corr) if not np.isnan(corr) else 0.0
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    n = len(predictions)
+    pred_mean = sum(predictions) / n
+    actual_mean = sum(actuals) / n
+    
+    numerator = sum((predictions[i] - pred_mean) * (actuals[i] - actual_mean) for i in range(n))
+    pred_var = sum((p - pred_mean) ** 2 for p in predictions)
+    actual_var = sum((a - actual_mean) ** 2 for a in actuals)
+    
+    denominator = math.sqrt(pred_var * actual_var)
+    if denominator == 0:
+        return 0.0
+    
+    return numerator / denominator
+
+
+def rank_ic(predictions: Union[List, any], actuals: Union[List, any]) -> float:
+    """
+    Calculate Rank IC: Spearman rank correlation.
+    
+    Args:
+        predictions: Predicted values
+        actuals: Actual values
+    
+    Returns:
+        Rank IC
+    """
+    if len(predictions) != len(actuals) or len(predictions) == 0:
+        return 0.0
+    
+    if HAS_NUMPY:
+        try:
+            from scipy.stats import spearmanr
+            corr, _ = spearmanr(predictions, actuals)
+            return float(corr) if not np.isnan(corr) else 0.0
+        except ImportError:
+            # Fallback to manual rank correlation
+            pass
+    
+    # Manual rank correlation
+    n = len(predictions)
+    pred_ranks = _get_ranks(predictions)
+    actual_ranks = _get_ranks(actuals)
+    
+    return information_coefficient(pred_ranks, actual_ranks)
+
+
+def _get_ranks(values: List) -> List:
+    """Get ranks of values."""
+    sorted_vals = sorted(enumerate(values), key=lambda x: x[1])
+    ranks = [0] * len(values)
+    for rank, (idx, _) in enumerate(sorted_vals, 1):
+        ranks[idx] = rank
+    return ranks
+
+
+def hit_rate(predictions: Union[List, any], actuals: Union[List, any]) -> float:
+    """
+    Calculate hit rate: percentage of correct directional predictions.
+    
+    Args:
+        predictions: Predicted values
+        actuals: Actual values
+    
+    Returns:
+        Hit rate (0.0 to 1.0)
+    """
+    if len(predictions) != len(actuals) or len(predictions) == 0:
+        return 0.0
+    
+    correct = 0
+    for i in range(len(predictions)):
+        pred_dir = 1 if predictions[i] > 0 else -1
+        actual_dir = 1 if actuals[i] > 0 else -1
+        if pred_dir == actual_dir:
+            correct += 1
+    
+    return correct / len(predictions)
+
+
+def var(returns: Union[List, any], confidence: float = 0.05) -> float:
+    """
+    Calculate Value at Risk (VaR).
+    
+    Args:
+        returns: List of returns
+        confidence: Confidence level (default: 0.05 for 95% VaR)
+    
+    Returns:
+        VaR (negative value)
+    """
+    if len(returns) == 0:
+        return 0.0
+    
+    if HAS_NUMPY:
+        try:
+            ret_arr = np.array(returns, dtype=np.float64)
+            var_val = np.percentile(ret_arr, confidence * 100)
+            return float(var_val)
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    sorted_returns = sorted(returns)
+    idx = int(len(sorted_returns) * confidence)
+    return sorted_returns[idx] if idx < len(sorted_returns) else sorted_returns[-1]
+
+
+def cvar(returns: Union[List, any], confidence: float = 0.05) -> float:
+    """
+    Calculate Conditional Value at Risk (CVaR) / Expected Shortfall.
+    
+    Args:
+        returns: List of returns
+        confidence: Confidence level
+    
+    Returns:
+        CVaR (negative value)
+    """
+    if len(returns) == 0:
+        return 0.0
+    
+    var_val = var(returns, confidence)
+    
+    if HAS_NUMPY:
+        try:
+            ret_arr = np.array(returns, dtype=np.float64)
+            tail_losses = ret_arr[ret_arr <= var_val]
+            if len(tail_losses) == 0:
+                return var_val
+            return float(np.mean(tail_losses))
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    tail_losses = [r for r in returns if r <= var_val]
+    if len(tail_losses) == 0:
+        return var_val
+    return sum(tail_losses) / len(tail_losses)
+
+
+def turnover(positions: Union[List, any]) -> float:
+    """
+    Calculate portfolio turnover.
+    
+    Args:
+        positions: List of position values (can be weights)
+    
+    Returns:
+        Average turnover
+    """
+    if len(positions) < 2:
+        return 0.0
+    
+    if HAS_NUMPY:
+        try:
+            pos_arr = np.array(positions, dtype=np.float64)
+            changes = np.abs(np.diff(pos_arr, axis=0))
+            return float(np.mean(np.sum(changes, axis=1) if len(changes.shape) > 1 else changes))
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    total_turnover = 0.0
+    for i in range(1, len(positions)):
+        if isinstance(positions[i], list) and isinstance(positions[i-1], list):
+            change = sum(abs(positions[i][j] - positions[i-1][j]) for j in range(len(positions[i])))
+        else:
+            change = abs(positions[i] - positions[i-1])
+        total_turnover += change
+    
+    return total_turnover / (len(positions) - 1)
+

quantml/training/regularization.py

@@ -0,0 +1,89 @@
+"""
+Regularization utilities for quant models.
+
+Provides dropout and other regularization techniques.
+"""
+
+from typing import Optional
+from quantml.tensor import Tensor
+from quantml import ops
+import random
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+class Dropout:
+    """
+    Dropout layer for regularization.
+    
+    Randomly sets a fraction of inputs to zero during training.
+    """
+    
+    def __init__(self, p: float = 0.5):
+        """
+        Initialize dropout layer.
+        
+        Args:
+            p: Probability of dropping out (0.0 to 1.0)
+        """
+        self.p = p
+        self.training = True
+        self.mask = None
+    
+    def forward(self, x: Tensor) -> Tensor:
+        """
+        Forward pass through dropout.
+        
+        Args:
+            x: Input tensor
+        
+        Returns:
+            Output tensor with dropout applied
+        """
+        if not self.training or self.p == 0.0:
+            return x
+        
+        # Create dropout mask
+        if HAS_NUMPY:
+            try:
+                import numpy as np
+                x_arr = x.numpy if x.numpy is not None else np.array(x.data, dtype=np.float64)
+                mask = (np.random.random(x_arr.shape) > self.p).astype(np.float64)
+                mask = mask / (1.0 - self.p)  # Scale to maintain expected value
+                self.mask = mask
+                out_arr = x_arr * mask
+                return Tensor(out_arr.tolist(), requires_grad=x.requires_grad)
+            except:
+                pass
+        
+        # Fallback to list-based
+        if isinstance(x.data[0], list):
+            mask = [[1.0 if random.random() > self.p else 0.0 for _ in row] for row in x.data]
+            scale = 1.0 / (1.0 - self.p)
+            mask = [[m * scale for m in row] for row in mask]
+            self.mask = mask
+            out_data = [[x.data[i][j] * mask[i][j] for j in range(len(x.data[i]))] 
+                       for i in range(len(x.data))]
+        else:
+            mask = [1.0 if random.random() > self.p else 0.0 for _ in x.data]
+            scale = 1.0 / (1.0 - self.p)
+            mask = [m * scale for m in mask]
+            self.mask = mask
+            out_data = [x.data[i] * mask[i] for i in range(len(x.data))]
+        
+        return Tensor(out_data, requires_grad=x.requires_grad)
+    
+    def eval(self):
+        """Set to evaluation mode (no dropout)."""
+        self.training = False
+    
+    def train(self):
+        """Set to training mode (with dropout)."""
+        self.training = True
+

quantml/training/trainer.py

@@ -0,0 +1,239 @@
+"""
+Training utilities for quant models.
+
+This module provides QuantTrainer class with training loop, early stopping,
+checkpointing, and metrics tracking.
+"""
+
+from typing import Optional, Callable, Dict, Any, List
+from quantml.tensor import Tensor
+from quantml import ops
+from quantml.training.gradient_clipping import GradientNormClipper, GradientValueClipper, AdaptiveClipper
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+class QuantTrainer:
+    """
+    Trainer class for quant model training.
+    
+    Provides training loop with early stopping, checkpointing, and metrics tracking.
+    
+    Attributes:
+        model: Model to train
+        optimizer: Optimizer
+        loss_fn: Loss function
+        metrics: List of metric functions to track
+    
+    Examples:
+        >>> trainer = QuantTrainer(model, optimizer, loss_fn=mse_loss)
+        >>> trainer.train(X_train, y_train, X_val, y_val, epochs=100)
+    """
+    
+    def __init__(
+        self,
+        model: Any,
+        optimizer: Any,
+        loss_fn: Callable,
+        metrics: Optional[List[Callable]] = None,
+        gradient_clipper: Optional[Any] = None,
+        accumulation_steps: int = 1
+    ):
+        """
+        Initialize trainer.
+        
+        Args:
+            model: Model to train
+            optimizer: Optimizer (SGD, Adam, etc.)
+            loss_fn: Loss function
+            metrics: Optional list of metric functions
+            gradient_clipper: Optional gradient clipper (GradientNormClipper, etc.)
+            accumulation_steps: Number of steps to accumulate gradients before optimizer step
+        """
+        self.model = model
+        self.optimizer = optimizer
+        self.loss_fn = loss_fn
+        self.metrics = metrics if metrics else []
+        self.gradient_clipper = gradient_clipper
+        self.accumulation_steps = accumulation_steps
+        self.accumulation_counter = 0
+        self.history = {'train_loss': [], 'val_loss': []}
+    
+    def train_step(self, x: Tensor, y: Tensor) -> float:
+        """
+        Perform a single training step.
+        
+        Args:
+            x: Input features
+            y: Targets
+        
+        Returns:
+            Loss value
+        """
+        # Forward pass
+        pred = self.model.forward(x)
+        
+        # Compute loss (scale by accumulation steps for correct averaging)
+        loss = self.loss_fn(pred, y)
+        if self.accumulation_steps > 1:
+            loss = ops.mul(loss, 1.0 / self.accumulation_steps)
+        
+        # Backward pass
+        if loss.requires_grad:
+            loss.backward()
+        
+        self.accumulation_counter += 1
+        
+        # Apply gradient clipping if enabled
+        if self.gradient_clipper is not None and self.accumulation_counter % self.accumulation_steps == 0:
+            params = self.model.parameters() if hasattr(self.model, 'parameters') else []
+            self.gradient_clipper(params)
+        
+        # Optimizer step only after accumulation
+        if self.accumulation_counter % self.accumulation_steps == 0:
+            self.optimizer.step()
+            self.model.zero_grad()
+            self.accumulation_counter = 0
+        
+        # Get loss value (unscale for reporting)
+        loss_value = self._get_value(loss)
+        if self.accumulation_steps > 1:
+            loss_value = loss_value * self.accumulation_steps
+        return loss_value
+    
+    def validate(self, x: Tensor, y: Tensor) -> Dict[str, float]:
+        """
+        Validate model on data.
+        
+        Args:
+            x: Input features
+            y: Targets
+        
+        Returns:
+            Dictionary of metrics
+        """
+        # Forward pass
+        pred = self.model.forward(x)
+        
+        # Compute loss
+        loss = self.loss_fn(pred, y)
+        metrics_dict = {'loss': self._get_value(loss)}
+        
+        # Compute additional metrics
+        for metric_fn in self.metrics:
+            try:
+                metric_val = metric_fn(pred, y)
+                if isinstance(metric_val, Tensor):
+                    metric_val = self._get_value(metric_val)
+                metrics_dict[metric_fn.__name__] = metric_val
+            except Exception:
+                pass
+        
+        return metrics_dict
+    
+    def train(
+        self,
+        X_train: List,
+        y_train: List,
+        X_val: Optional[List] = None,
+        y_val: Optional[List] = None,
+        epochs: int = 100,
+        batch_size: int = 32,
+        early_stopping: Optional[Dict] = None,
+        verbose: bool = True
+    ) -> Dict[str, List]:
+        """
+        Train model.
+        
+        Args:
+            X_train: Training features
+            y_train: Training targets
+            X_val: Validation features (optional)
+            y_val: Validation targets (optional)
+            epochs: Number of epochs
+            batch_size: Batch size
+            early_stopping: Early stopping config (patience, min_delta)
+            verbose: Whether to print progress
+        
+        Returns:
+            Training history
+        """
+        from quantml.training.data_loader import QuantDataLoader
+        
+        train_loader = QuantDataLoader(X_train, y_train, batch_size=batch_size, shuffle=False)
+        
+        val_loader = None
+        if X_val is not None and y_val is not None:
+            val_loader = QuantDataLoader(X_val, y_val, batch_size=batch_size, shuffle=False)
+        
+        # Early stopping
+        best_val_loss = float('inf')
+        patience_counter = 0
+        patience = early_stopping.get('patience', 10) if early_stopping else None
+        min_delta = early_stopping.get('min_delta', 0.0) if early_stopping else 0.0
+        
+        for epoch in range(epochs):
+            # Training
+            train_losses = []
+            for x_batch, y_batch in train_loader:
+                loss = self.train_step(x_batch, y_batch)
+                train_losses.append(loss)
+            
+            avg_train_loss = sum(train_losses) / len(train_losses) if train_losses else 0.0
+            self.history['train_loss'].append(avg_train_loss)
+            
+            # Validation
+            if val_loader is not None:
+                val_metrics = self._validate_loader(val_loader)
+                val_loss = val_metrics.get('loss', 0.0)
+                self.history['val_loss'].append(val_loss)
+                
+                # Early stopping check
+                if patience is not None:
+                    if val_loss < best_val_loss - min_delta:
+                        best_val_loss = val_loss
+                        patience_counter = 0
+                    else:
+                        patience_counter += 1
+                        if patience_counter >= patience:
+                            if verbose:
+                                print(f"Early stopping at epoch {epoch + 1}")
+                            break
+            
+            if verbose and (epoch + 1) % 10 == 0:
+                print(f"Epoch {epoch + 1}/{epochs}: Train Loss = {avg_train_loss:.6f}", end="")
+                if val_loader is not None:
+                    print(f", Val Loss = {val_loss:.6f}")
+                else:
+                    print()
+        
+        return self.history
+    
+    def _validate_loader(self, loader) -> Dict[str, float]:
+        """Validate on data loader."""
+        all_metrics = []
+        for x_batch, y_batch in loader:
+            metrics = self.validate(x_batch, y_batch)
+            all_metrics.append(metrics)
+        
+        # Average metrics
+        avg_metrics = {}
+        for key in all_metrics[0].keys():
+            avg_metrics[key] = sum(m[key] for m in all_metrics) / len(all_metrics)
+        
+        return avg_metrics
+    
+    def _get_value(self, tensor: Tensor) -> float:
+        """Extract scalar value from tensor."""
+        if isinstance(tensor.data, list):
+            if isinstance(tensor.data[0], list):
+                return float(tensor.data[0][0])
+            return float(tensor.data[0])
+        return float(tensor.data)
+