quantmllibrary 0.1.0__py3-none-any.whl

quantml/training/cv.py

@@ -0,0 +1,106 @@
+"""
+Cross-validation utilities for time-series data.
+
+Provides time-series aware cross-validation to avoid lookahead bias.
+"""
+
+from typing import List, Iterator, Tuple, Optional
+import math
+
+
+class TimeSeriesSplit:
+    """
+    Time-series aware cross-validation splitter.
+    
+    Splits data sequentially to avoid lookahead bias.
+    """
+    
+    def __init__(self, n_splits: int = 5, test_size: Optional[int] = None):
+        """
+        Initialize TimeSeriesSplit.
+        
+        Args:
+            n_splits: Number of splits
+            test_size: Size of test set (if None, uses 1/n_splits)
+        """
+        self.n_splits = n_splits
+        self.test_size = test_size
+    
+    def split(self, X: List, y: Optional[List] = None) -> Iterator[Tuple[List[int], List[int]]]:
+        """
+        Generate train/test splits.
+        
+        Args:
+            X: Input data
+            y: Optional target data
+        
+        Yields:
+            Tuple of (train_indices, test_indices)
+        """
+        n_samples = len(X)
+        if self.test_size is None:
+            test_size = n_samples // (self.n_splits + 1)
+        else:
+            test_size = self.test_size
+        
+        for i in range(self.n_splits):
+            test_start = (i + 1) * test_size
+            test_end = min(test_start + test_size, n_samples)
+            
+            if test_start >= n_samples:
+                break
+            
+            train_indices = list(range(test_start))
+            test_indices = list(range(test_start, test_end))
+            
+            yield train_indices, test_indices
+
+
+class PurgedKFold:
+    """
+    Purged K-fold for time-series.
+    
+    Removes overlapping periods to avoid leakage.
+    """
+    
+    def __init__(self, n_splits: int = 5, purge_gap: int = 1):
+        """
+        Initialize PurgedKFold.
+        
+        Args:
+            n_splits: Number of splits
+            purge_gap: Number of samples to purge between train and test
+        """
+        self.n_splits = n_splits
+        self.purge_gap = purge_gap
+    
+    def split(self, X: List, y: Optional[List] = None) -> Iterator[Tuple[List[int], List[int]]]:
+        """
+        Generate purged train/test splits.
+        
+        Args:
+            X: Input data
+            y: Optional target data
+        
+        Yields:
+            Tuple of (train_indices, test_indices)
+        """
+        n_samples = len(X)
+        fold_size = n_samples // self.n_splits
+        
+        for i in range(self.n_splits):
+            test_start = i * fold_size
+            test_end = min((i + 1) * fold_size, n_samples)
+            
+            # Purge gap before test set
+            train_end = max(0, test_start - self.purge_gap)
+            train_indices = list(range(train_end))
+            
+            # Purge gap after test set
+            train_start_after = min(n_samples, test_end + self.purge_gap)
+            train_indices.extend(list(range(train_start_after, n_samples)))
+            
+            test_indices = list(range(test_start, test_end))
+            
+            yield train_indices, test_indices
+

quantml/training/data_loader.py

@@ -0,0 +1,177 @@
+"""
+Efficient data loader for time-series aware batching.
+
+This module provides data loaders optimized for quant training,
+with support for time-series aware batching to prevent lookahead bias.
+"""
+
+from typing import List, Tuple, Optional, Iterator, Any
+from quantml.tensor import Tensor
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+class QuantDataLoader:
+    """
+    Data loader for quant model training with time-series awareness.
+    
+    This loader ensures no lookahead bias by only using past data
+    for training batches.
+    
+    Attributes:
+        X: Feature data
+        y: Target data
+        batch_size: Batch size
+        shuffle: Whether to shuffle (should be False for time-series)
+        drop_last: Whether to drop last incomplete batch
+    
+    Examples:
+        >>> loader = QuantDataLoader(X, y, batch_size=32)
+        >>> for batch_x, batch_y in loader:
+        >>>     # Train on batch
+    """
+    
+    def __init__(
+        self,
+        X: List,
+        y: List,
+        batch_size: int = 32,
+        shuffle: bool = False,
+        drop_last: bool = False
+    ):
+        """
+        Initialize data loader.
+        
+        Args:
+            X: Feature data
+            y: Target data
+            batch_size: Batch size
+            shuffle: Whether to shuffle (False recommended for time-series)
+            drop_last: Whether to drop last incomplete batch
+        """
+        if len(X) != len(y):
+            raise ValueError("X and y must have same length")
+        
+        self.X = X
+        self.y = y
+        self.batch_size = batch_size
+        self.shuffle = shuffle
+        self.drop_last = drop_last
+        self.n_samples = len(X)
+    
+    def __len__(self) -> int:
+        """Get number of batches."""
+        if self.drop_last:
+            return self.n_samples // self.batch_size
+        return (self.n_samples + self.batch_size - 1) // self.batch_size
+    
+    def __iter__(self) -> Iterator[Tuple[Tensor, Tensor]]:
+        """Iterate over batches."""
+        indices = list(range(self.n_samples))
+        
+        if self.shuffle:
+            import random
+            random.shuffle(indices)
+        
+        for i in range(0, self.n_samples, self.batch_size):
+            batch_indices = indices[i:i + self.batch_size]
+            
+            if self.drop_last and len(batch_indices) < self.batch_size:
+                break
+            
+            batch_x = [self.X[idx] for idx in batch_indices]
+            batch_y = [self.y[idx] for idx in batch_indices]
+            
+            # Convert to tensors
+            x_tensor = Tensor(batch_x)
+            y_tensor = Tensor(batch_y)
+            
+            yield x_tensor, y_tensor
+
+
+class TimeSeriesDataLoader:
+    """
+    Time-series aware data loader with sequence support.
+    
+    This loader creates sequences for RNN/TCN models while ensuring
+    no lookahead bias.
+    
+    Attributes:
+        X: Feature data
+        y: Target data
+        sequence_length: Length of input sequences
+        batch_size: Batch size
+        stride: Stride for sequence creation
+    
+    Examples:
+        >>> loader = TimeSeriesDataLoader(X, y, sequence_length=20, batch_size=16)
+        >>> for seq_x, seq_y in loader:
+        >>>     # Train on sequences
+    """
+    
+    def __init__(
+        self,
+        X: List,
+        y: List,
+        sequence_length: int = 20,
+        batch_size: int = 32,
+        stride: int = 1
+    ):
+        """
+        Initialize time-series data loader.
+        
+        Args:
+            X: Feature data
+            y: Target data
+            sequence_length: Length of input sequences
+            batch_size: Batch size
+            stride: Stride for sequence creation
+        """
+        if len(X) != len(y):
+            raise ValueError("X and y must have same length")
+        
+        self.X = X
+        self.y = y
+        self.sequence_length = sequence_length
+        self.batch_size = batch_size
+        self.stride = stride
+        
+        # Create sequences
+        self.sequences = self._create_sequences()
+        self.n_sequences = len(self.sequences)
+    
+    def _create_sequences(self) -> List[Tuple[List, float]]:
+        """Create sequences from data."""
+        sequences = []
+        
+        for i in range(self.sequence_length, len(self.X), self.stride):
+            seq_x = self.X[i - self.sequence_length:i]
+            seq_y = self.y[i]
+            sequences.append((seq_x, seq_y))
+        
+        return sequences
+    
+    def __len__(self) -> int:
+        """Get number of batches."""
+        return (self.n_sequences + self.batch_size - 1) // self.batch_size
+    
+    def __iter__(self) -> Iterator[Tuple[Tensor, Tensor]]:
+        """Iterate over batches."""
+        for i in range(0, self.n_sequences, self.batch_size):
+            batch_sequences = self.sequences[i:i + self.batch_size]
+            
+            batch_x = [seq[0] for seq in batch_sequences]
+            batch_y = [seq[1] for seq in batch_sequences]
+            
+            # Convert to tensors
+            x_tensor = Tensor(batch_x)
+            y_tensor = Tensor(batch_y)
+            
+            yield x_tensor, y_tensor
+

quantml/training/ensemble.py

@@ -0,0 +1,84 @@
+"""
+Model ensembling utilities for quant models.
+
+Provides utilities for combining multiple models.
+"""
+
+from typing import List, Optional, Callable, Any, Dict
+from quantml.tensor import Tensor
+
+
+class EnsembleModel:
+    """
+    Ensemble model that combines multiple models.
+    
+    Supports weighted averaging, voting, and stacking strategies.
+    """
+    
+    def __init__(
+        self,
+        models: List[Any],
+        weights: Optional[List[float]] = None,
+        strategy: str = 'weighted_avg'
+    ):
+        """
+        Initialize ensemble model.
+        
+        Args:
+            models: List of models to ensemble
+            weights: Optional weights for each model (defaults to equal weights)
+            strategy: Ensemble strategy ('weighted_avg', 'voting', 'stacking')
+        """
+        self.models = models
+        self.strategy = strategy
+        
+        if weights is None:
+            self.weights = [1.0 / len(models)] * len(models)
+        else:
+            # Normalize weights
+            total = sum(weights)
+            self.weights = [w / total for w in weights]
+    
+    def forward(self, x: Tensor) -> Tensor:
+        """
+        Forward pass through ensemble.
+        
+        Args:
+            x: Input features
+        
+        Returns:
+            Ensemble prediction
+        """
+        if self.strategy == 'weighted_avg':
+            predictions = [model.forward(x) for model in self.models]
+            # Weighted average
+            from quantml import ops
+            result = ops.mul(predictions[0], self.weights[0])
+            for i in range(1, len(predictions)):
+                result = ops.add(result, ops.mul(predictions[i], self.weights[i]))
+            return result
+        elif self.strategy == 'voting':
+            # Simple voting (for classification - simplified for regression)
+            predictions = [model.forward(x) for model in self.models]
+            from quantml import ops
+            result = ops.mul(predictions[0], self.weights[0])
+            for i in range(1, len(predictions)):
+                result = ops.add(result, ops.mul(predictions[i], self.weights[i]))
+            return result
+        else:  # stacking
+            # Stacking would require a meta-learner (simplified here)
+            predictions = [model.forward(x) for model in self.models]
+            from quantml import ops
+            result = ops.mul(predictions[0], self.weights[0])
+            for i in range(1, len(predictions)):
+                result = ops.add(result, ops.mul(predictions[i], self.weights[i]))
+            return result
+    
+    def parameters(self):
+        """Get all parameters from all models."""
+        params = []
+        for model in self.models:
+            if hasattr(model, 'parameters'):
+                params.extend(model.parameters())
+        return params
+

quantml/training/feature_importance.py

@@ -0,0 +1,135 @@
+"""
+Feature importance tracking and analysis.
+
+Provides utilities for tracking feature contributions to model predictions.
+"""
+
+from typing import List, Dict, Optional, Any, Callable
+from quantml.tensor import Tensor
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+class FeatureImportanceTracker:
+    """
+    Track feature importance for quant models.
+    
+    Tracks gradient-based and permutation-based feature importance.
+    """
+    
+    def __init__(self):
+        """Initialize feature importance tracker."""
+        self.gradient_importance: Dict[int, List[float]] = {}
+        self.permutation_importance: Dict[int, List[float]] = {}
+    
+    def compute_gradient_importance(self, model: Any, x: Tensor, y: Tensor) -> List[float]:
+        """
+        Compute gradient-based feature importance.
+        
+        Args:
+            model: Model to analyze
+            x: Input features
+            y: Targets
+        
+        Returns:
+            List of importance scores for each feature
+        """
+        # Forward pass
+        pred = model.forward(x)
+        loss = model.loss_fn(pred, y) if hasattr(model, 'loss_fn') else None
+        
+        if loss is None:
+            from quantml.training.losses import mse_loss
+            loss = mse_loss(pred, y)
+        
+        # Backward pass
+        if loss.requires_grad:
+            loss.backward()
+        
+        # Extract gradients from input
+        # This is simplified - would need to track gradients through model
+        importance = []
+        if hasattr(x, 'grad') and x.grad is not None:
+            grad = x.grad
+            if HAS_NUMPY and isinstance(grad, np.ndarray):
+                importance = np.abs(grad).mean(axis=0).tolist()
+            elif isinstance(grad, list):
+                if isinstance(grad[0], list):
+                    # Average over samples
+                    importance = [sum(abs(grad[i][j]) for i in range(len(grad))) / len(grad) 
+                                 for j in range(len(grad[0]))]
+                else:
+                    importance = [abs(g) for g in grad]
+        
+        return importance
+    
+    def compute_permutation_importance(
+        self, 
+        model: Any, 
+        x: Tensor, 
+        y: Tensor, 
+        metric_fn: Callable,
+        n_permutations: int = 10
+    ) -> List[float]:
+        """
+        Compute permutation-based feature importance.
+        
+        Args:
+            model: Model to analyze
+            x: Input features
+            y: Targets
+            metric_fn: Metric function to use
+            n_permutations: Number of permutations per feature
+        
+        Returns:
+            List of importance scores
+        """
+        # Baseline metric
+        pred_baseline = model.forward(x)
+        baseline_score = metric_fn(pred_baseline, y)
+        
+        importance = []
+        x_data = x.data
+        
+        # For each feature
+        num_features = len(x_data[0]) if isinstance(x_data[0], list) else len(x_data)
+        
+        for feat_idx in range(num_features):
+            scores = []
+            for _ in range(n_permutations):
+                # Permute feature
+                x_permuted = self._permute_feature(x_data, feat_idx)
+                x_perm_tensor = Tensor(x_permuted)
+                pred_perm = model.forward(x_perm_tensor)
+                score = metric_fn(pred_perm, y)
+                scores.append(score)
+            
+            # Importance is decrease in performance
+            avg_score = sum(scores) / len(scores)
+            importance.append(baseline_score - avg_score)
+        
+        return importance
+    
+    def _permute_feature(self, data: List, feat_idx: int) -> List:
+        """Permute a single feature in the data."""
+        if isinstance(data[0], list):
+            # 2D case
+            import random
+            values = [row[feat_idx] for row in data]
+            random.shuffle(values)
+            return [[row[j] if j != feat_idx else values[i] 
+                    for j in range(len(row))] 
+                   for i, row in enumerate(data)]
+        else:
+            # 1D case
+            import random
+            values = data.copy()
+            random.shuffle(values)
+            return values
+