quantmllibrary 0.1.0__py3-none-any.whl

quantml/training/features.py

@@ -0,0 +1,364 @@
+"""
+Feature engineering pipeline for quant models.
+
+This module provides utilities for creating features from raw market data,
+including lagged features, rolling windows, cross-sectional features, and normalization.
+"""
+
+from typing import List, Optional, Union, Callable, Dict, Any
+from quantml.tensor import Tensor
+from quantml import time_series
+
+# Try to import NumPy
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+    np = None
+
+
+class FeaturePipeline:
+    """
+    Feature engineering pipeline for reproducible feature creation.
+    
+    This class provides a framework for creating features from raw data,
+    with support for lagged features, rolling windows, normalization, and more.
+    
+    Attributes:
+        features: List of feature definitions
+        normalizers: Dictionary of normalizers for each feature
+    
+    Examples:
+        >>> pipeline = FeaturePipeline()
+        >>> pipeline.add_lagged_feature('price', lags=[1, 5, 10])
+        >>> pipeline.add_rolling_feature('price', window=20, func='mean')
+        >>> features = pipeline.transform(prices)
+    """
+    
+    def __init__(self):
+        """Initialize feature pipeline."""
+        self.features = []
+        self.normalizers = {}
+    
+    def add_lagged_feature(
+        self,
+        name: str,
+        lags: List[int],
+        fill_value: float = 0.0
+    ):
+        """
+        Add lagged features.
+        
+        Args:
+            name: Feature name
+            lags: List of lag values (e.g., [1, 5, 10] for 1, 5, 10 period lags)
+            fill_value: Value to use for missing lags (at beginning)
+        """
+        self.features.append({
+            'type': 'lagged',
+            'name': name,
+            'lags': lags,
+            'fill_value': fill_value
+        })
+    
+    def add_rolling_feature(
+        self,
+        name: str,
+        window: int,
+        func: str = 'mean',
+        min_periods: Optional[int] = None
+    ):
+        """
+        Add rolling window feature.
+        
+        Args:
+            name: Feature name
+            window: Window size
+            func: Function to apply ('mean', 'std', 'min', 'max', 'sum')
+            min_periods: Minimum periods required (default: window)
+        """
+        if min_periods is None:
+            min_periods = window
+        
+        self.features.append({
+            'type': 'rolling',
+            'name': name,
+            'window': window,
+            'func': func,
+            'min_periods': min_periods
+        })
+    
+    def add_time_series_feature(
+        self,
+        name: str,
+        func: str,
+        **kwargs
+    ):
+        """
+        Add time-series feature (EMA, returns, etc.).
+        
+        Args:
+            name: Feature name
+            func: Function name ('ema', 'returns', 'volatility', etc.)
+            **kwargs: Arguments for the function
+        """
+        self.features.append({
+            'type': 'time_series',
+            'name': name,
+            'func': func,
+            'kwargs': kwargs
+        })
+    
+    def add_normalization(
+        self,
+        feature_name: str,
+        method: str = 'zscore',
+        window: Optional[int] = None
+    ):
+        """
+        Add normalization to a feature.
+        
+        Args:
+            feature_name: Name of feature to normalize
+            method: Normalization method ('zscore', 'minmax', 'robust')
+            window: Rolling window for normalization (None for global)
+        """
+        if feature_name not in self.normalizers:
+            self.normalizers[feature_name] = []
+        self.normalizers[feature_name].append({
+            'method': method,
+            'window': window
+        })
+    
+    def transform(self, data: Dict[str, List[float]]) -> List[List[float]]:
+        """
+        Transform raw data into features.
+        
+        Args:
+            data: Dictionary of feature name -> values
+        
+        Returns:
+            List of feature vectors (one per time step)
+        """
+        n = len(list(data.values())[0]) if data else 0
+        if n == 0:
+            return []
+        
+        feature_matrix = []
+        
+        for i in range(n):
+            feature_vector = []
+            
+            for feat_def in self.features:
+                feat_name = feat_def['name']
+                if feat_name not in data:
+                    continue
+                
+                values = data[feat_name]
+                
+                if feat_def['type'] == 'lagged':
+                    for lag in feat_def['lags']:
+                        if i >= lag:
+                            feature_vector.append(values[i - lag])
+                        else:
+                            feature_vector.append(feat_def['fill_value'])
+                
+                elif feat_def['type'] == 'rolling':
+                    window = feat_def['window']
+                    func = feat_def['func']
+                    min_periods = feat_def['min_periods']
+                    
+                    start_idx = max(0, i - window + 1)
+                    window_data = values[start_idx:i+1]
+                    
+                    if len(window_data) >= min_periods:
+                        if func == 'mean':
+                            feat_val = sum(window_data) / len(window_data)
+                        elif func == 'std':
+                            mean_val = sum(window_data) / len(window_data)
+                            variance = sum((x - mean_val) ** 2 for x in window_data) / len(window_data)
+                            feat_val = variance ** 0.5
+                        elif func == 'min':
+                            feat_val = min(window_data)
+                        elif func == 'max':
+                            feat_val = max(window_data)
+                        elif func == 'sum':
+                            feat_val = sum(window_data)
+                        else:
+                            feat_val = 0.0
+                    else:
+                        feat_val = 0.0
+                    
+                    feature_vector.append(feat_val)
+                
+                elif feat_def['type'] == 'time_series':
+                    func_name = feat_def['func']
+                    kwargs = feat_def['kwargs']
+                    
+                    # Convert to tensor for time_series operations
+                    tensor_data = Tensor([values[:i+1]])
+                    
+                    if func_name == 'ema':
+                        n_periods = kwargs.get('n', 20)
+                        ema_vals = time_series.ema(tensor_data, n=n_periods)
+                        if isinstance(ema_vals.data[0], list) and len(ema_vals.data[0]) > 0:
+                            feature_vector.append(ema_vals.data[0][-1])
+                        else:
+                            feature_vector.append(0.0)
+                    
+                    elif func_name == 'returns':
+                        rets = time_series.returns(tensor_data)
+                        if isinstance(rets.data[0], list) and len(rets.data[0]) > 0:
+                            feature_vector.append(rets.data[0][-1])
+                        else:
+                            feature_vector.append(0.0)
+                    
+                    elif func_name == 'volatility':
+                        n_periods = kwargs.get('n', 20)
+                        vol = time_series.volatility(tensor_data, n=n_periods)
+                        if isinstance(vol.data[0], list) and len(vol.data[0]) > 0:
+                            feature_vector.append(vol.data[0][-1])
+                        else:
+                            feature_vector.append(0.0)
+                    
+                    else:
+                        feature_vector.append(0.0)
+            
+            feature_matrix.append(feature_vector)
+        
+        # Apply normalization
+        if self.normalizers:
+            feature_matrix = self._apply_normalization(feature_matrix, data)
+        
+        return feature_matrix
+    
+    def _apply_normalization(
+        self,
+        feature_matrix: List[List[float]],
+        original_data: Dict[str, List[float]]
+    ) -> List[List[float]]:
+        """Apply normalization to features."""
+        # Simplified normalization - in practice would track feature indices
+        # For now, apply z-score normalization globally
+        if HAS_NUMPY:
+            try:
+                matrix = np.array(feature_matrix, dtype=np.float64)
+                mean_vals = np.mean(matrix, axis=0)
+                std_vals = np.std(matrix, axis=0)
+                std_vals = np.where(std_vals == 0, 1.0, std_vals)
+                normalized = (matrix - mean_vals) / std_vals
+                return normalized.tolist()
+            except (ValueError, TypeError):
+                pass
+        
+        # Pure Python fallback
+        if len(feature_matrix) == 0:
+            return feature_matrix
+        
+        n_features = len(feature_matrix[0])
+        means = [sum(row[i] for row in feature_matrix) / len(feature_matrix) 
+                for i in range(n_features)]
+        stds = []
+        for i in range(n_features):
+            variance = sum((row[i] - means[i]) ** 2 for row in feature_matrix) / len(feature_matrix)
+            stds.append(variance ** 0.5 if variance > 0 else 1.0)
+        
+        normalized = []
+        for row in feature_matrix:
+            normalized.append([
+                (row[i] - means[i]) / stds[i] if stds[i] > 0 else 0.0
+                for i in range(n_features)
+            ])
+        
+        return normalized
+
+
+def create_lagged_features(data: List[float], lags: List[int]) -> List[List[float]]:
+    """
+    Create lagged features from a time series.
+    
+    Args:
+        data: Time series data
+        lags: List of lag values
+    
+    Returns:
+        List of feature vectors with lagged values
+    """
+    features = []
+    for i in range(len(data)):
+        feature_vec = []
+        for lag in lags:
+            if i >= lag:
+                feature_vec.append(data[i - lag])
+            else:
+                feature_vec.append(0.0)
+        features.append(feature_vec)
+    return features
+
+
+def normalize_features(
+    features: List[List[float]],
+    method: str = 'zscore'
+) -> List[List[float]]:
+    """
+    Normalize feature matrix.
+    
+    Args:
+        features: Feature matrix
+        method: Normalization method ('zscore', 'minmax')
+    
+    Returns:
+        Normalized feature matrix
+    """
+    if len(features) == 0:
+        return features
+    
+    if HAS_NUMPY:
+        try:
+            matrix = np.array(features, dtype=np.float64)
+            if method == 'zscore':
+                mean_vals = np.mean(matrix, axis=0)
+                std_vals = np.std(matrix, axis=0)
+                std_vals = np.where(std_vals == 0, 1.0, std_vals)
+                normalized = (matrix - mean_vals) / std_vals
+            elif method == 'minmax':
+                min_vals = np.min(matrix, axis=0)
+                max_vals = np.max(matrix, axis=0)
+                ranges = max_vals - min_vals
+                ranges = np.where(ranges == 0, 1.0, ranges)
+                normalized = (matrix - min_vals) / ranges
+            else:
+                normalized = matrix
+            return normalized.tolist()
+        except (ValueError, TypeError):
+            pass
+    
+    # Pure Python fallback
+    n_features = len(features[0])
+    
+    if method == 'zscore':
+        means = [sum(row[i] for row in features) / len(features) for i in range(n_features)]
+        stds = []
+        for i in range(n_features):
+            variance = sum((row[i] - means[i]) ** 2 for row in features) / len(features)
+            stds.append(variance ** 0.5 if variance > 0 else 1.0)
+        
+        normalized = [
+            [(row[i] - means[i]) / stds[i] if stds[i] > 0 else 0.0 for i in range(n_features)]
+            for row in features
+        ]
+    elif method == 'minmax':
+        mins = [min(row[i] for row in features) for i in range(n_features)]
+        maxs = [max(row[i] for row in features) for i in range(n_features)]
+        ranges = [maxs[i] - mins[i] if maxs[i] > mins[i] else 1.0 for i in range(n_features)]
+        
+        normalized = [
+            [(row[i] - mins[i]) / ranges[i] if ranges[i] > 0 else 0.0 for i in range(n_features)]
+            for row in features
+        ]
+    else:
+        normalized = features
+    
+    return normalized
+

quantml/training/futures_backtest.py

@@ -0,0 +1,266 @@
+"""
+Futures-specific backtesting engine.
+
+Handles contract rolls, margin requirements, overnight gaps, and session-based trading.
+"""
+
+from typing import List, Optional, Dict, Any, Tuple
+from quantml.training.backtest import BacktestEngine
+from quantml.training.metrics import sharpe_ratio, max_drawdown
+
+
+class FuturesBacktestEngine(BacktestEngine):
+    """
+    Backtesting engine for futures contracts.
+    
+    Extends BacktestEngine with futures-specific features:
+    - Contract roll handling
+    - Margin requirements
+    - Overnight gap simulation
+    - Session-based trading (RTH vs ETH)
+    """
+    
+    def __init__(
+        self,
+        initial_capital: float = 100000.0,
+        commission: float = 0.001,
+        slippage: float = 0.0005,
+        margin_requirement: float = 0.05,  # 5% margin
+        contract_size: float = 50.0,  # ES contract multiplier
+        roll_dates: Optional[List[int]] = None,
+        session_type: str = "RTH"  # RTH or ETH
+    ):
+        """
+        Initialize futures backtesting engine.
+        
+        Args:
+            initial_capital: Starting capital
+            commission: Commission per trade
+            slippage: Slippage per trade
+            margin_requirement: Margin requirement as fraction (e.g., 0.05 = 5%)
+            contract_size: Contract multiplier (50 for ES, 20 for NQ)
+            roll_dates: List of indices where contract rolls occur
+            session_type: "RTH" (regular trading hours) or "ETH" (extended)
+        """
+        super().__init__(initial_capital, commission, slippage)
+        self.margin_requirement = margin_requirement
+        self.contract_size = contract_size
+        self.roll_dates = roll_dates or []
+        self.session_type = session_type
+    
+    def _calculate_margin(self, position: float, price: float) -> float:
+        """
+        Calculate margin requirement for position.
+        
+        Args:
+            position: Position size (number of contracts)
+            price: Current price
+        
+        Returns:
+            Required margin
+        """
+        position_value = abs(position) * price * self.contract_size
+        return position_value * self.margin_requirement
+    
+    def _apply_overnight_gap(
+        self,
+        position: float,
+        prev_close: float,
+        current_open: float
+    ) -> Tuple[float, float]:
+        """
+        Apply overnight gap to position.
+        
+        Args:
+            position: Current position
+            prev_close: Previous day's close
+            current_open: Current day's open
+        
+        Returns:
+            (updated_capital, gap_pnl)
+        """
+        if position == 0 or prev_close == 0:
+            return 0.0, 0.0
+        
+        gap = (current_open - prev_close) / prev_close
+        position_value = abs(position) * prev_close * self.contract_size
+        
+        if position > 0:  # Long
+            gap_pnl = position_value * gap
+        else:  # Short
+            gap_pnl = -position_value * gap
+        
+        return gap_pnl, gap_pnl
+    
+    def run_futures(
+        self,
+        signals: List[float],
+        prices: List[float],
+        opens: Optional[List[float]] = None,
+        closes: Optional[List[float]] = None,
+        volumes: Optional[List[float]] = None
+    ) -> Dict[str, Any]:
+        """
+        Run futures backtest with contract rolls and overnight gaps.
+        
+        Args:
+            signals: Trading signals
+            prices: Price data (can be close prices)
+            opens: Opening prices (for gap calculation)
+            closes: Closing prices (for gap calculation)
+            volumes: Volume data
+        
+        Returns:
+            Backtest results with futures-specific metrics
+        """
+        if len(signals) != len(prices):
+            raise ValueError("signals and prices must have same length")
+        
+        # Use closes if provided, otherwise use prices
+        if closes is None:
+            closes = prices
+        if opens is None:
+            opens = prices
+        
+        n = len(signals)
+        capital = self.initial_capital
+        position = 0.0  # Position in contracts
+        equity_curve = [capital]
+        trades = []
+        returns = []
+        overnight_gaps = []
+        margin_used = []
+        
+        for i in range(n):
+            price = prices[i]
+            signal = signals[i]
+            
+            # Check for contract roll
+            if i in self.roll_dates:
+                # Close position before roll
+                if position != 0:
+                    trade_value = abs(position) * price * self.contract_size
+                    commission_cost = trade_value * self.commission
+                    capital -= commission_cost
+                    
+                    trades.append({
+                        'index': i,
+                        'price': price,
+                        'execution_price': price,
+                        'size': -position,  # Close position
+                        'cost': commission_cost,
+                        'type': 'roll'
+                    })
+                    position = 0.0
+            
+            # Apply overnight gap (if not first bar)
+            if i > 0:
+                prev_close = closes[i-1] if i-1 < len(closes) else prices[i-1]
+                current_open = opens[i] if i < len(opens) else price
+                
+                if position != 0:
+                    gap_pnl, _ = self._apply_overnight_gap(position, prev_close, current_open)
+                    capital += gap_pnl
+                    overnight_gaps.append({
+                        'index': i,
+                        'gap': (current_open - prev_close) / prev_close if prev_close > 0 else 0.0,
+                        'pnl': gap_pnl
+                    })
+            
+            # Determine target position
+            target_position_value = self.position_sizing(signal, capital, price)
+            target_position = target_position_value / (price * self.contract_size) if price > 0 else 0.0
+            
+            # Round to integer contracts
+            target_position = round(target_position)
+            
+            # Calculate trade
+            trade_size = target_position - position
+            
+            if abs(trade_size) > 0.5:  # Only trade if at least 1 contract
+                # Check margin requirement
+                new_position_value = abs(target_position) * price * self.contract_size
+                required_margin = new_position_value * self.margin_requirement
+                
+                if required_margin > capital:
+                    # Insufficient margin, reduce position
+                    max_position = int(capital / (price * self.contract_size * self.margin_requirement))
+                    target_position = max_position if target_position > 0 else -max_position
+                    trade_size = target_position - position
+                
+                if abs(trade_size) > 0.5:
+                    # Apply slippage
+                    execution_price = price * (1 + self.slippage * (1 if trade_size > 0 else -1))
+                    
+                    # Calculate costs
+                    trade_value = abs(trade_size) * execution_price * self.contract_size
+                    commission_cost = trade_value * self.commission
+                    slippage_cost = abs(trade_size) * price * self.contract_size * self.slippage
+                    total_cost = commission_cost + slippage_cost
+                    
+                    # Update capital
+                    capital -= trade_size * execution_price * self.contract_size + total_cost
+                    
+                    # Update position
+                    position = target_position
+                    
+                    trades.append({
+                        'index': i,
+                        'price': price,
+                        'execution_price': execution_price,
+                        'size': trade_size,
+                        'cost': total_cost,
+                        'type': 'trade'
+                    })
+            
+            # Update equity (mark-to-market)
+            current_value = capital + position * price * self.contract_size
+            equity_curve.append(current_value)
+            
+            # Track margin usage
+            margin = self._calculate_margin(position, price)
+            margin_used.append(margin)
+            
+            # 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
+        
+        sharpe = sharpe_ratio(returns) if returns else 0.0
+        max_dd = max_drawdown(returns) if returns else 0.0
+        
+        # Trade statistics
+        n_trades = len([t for t in trades if t.get('type') == 'trade'])
+        avg_margin_usage = sum(margin_used) / len(margin_used) if margin_used else 0.0
+        max_margin_usage = max(margin_used) if margin_used else 0.0
+        
+        # Overnight gap statistics
+        gap_pnls = [g['pnl'] for g in overnight_gaps]
+        total_gap_pnl = sum(gap_pnls)
+        avg_gap = sum(g['gap'] for g in overnight_gaps) / len(overnight_gaps) if overnight_gaps 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,
+            'n_trades': n_trades,
+            'overnight_gaps': overnight_gaps,
+            'total_gap_pnl': total_gap_pnl,
+            'avg_gap': avg_gap,
+            'margin_used': margin_used,
+            'avg_margin_usage': avg_margin_usage,
+            'max_margin_usage': max_margin_usage,
+            'sharpe_ratio': sharpe,
+            'max_drawdown': max_dd,
+            'contract_size': self.contract_size,
+            'margin_requirement': self.margin_requirement
+        }
+