Cycles/docs/strategies.md

# Strategies Documentation

## Overview

The Cycles framework implements advanced trading strategies with sophisticated timeframe management, signal processing, and multi-strategy combination capabilities. Each strategy can operate on its preferred timeframes while maintaining precise execution control.

## Architecture

### Strategy System Components

1. **StrategyBase**: Abstract base class with timeframe management
2. **Individual Strategies**: DefaultStrategy, BBRSStrategy implementations  
3. **StrategyManager**: Multi-strategy orchestration and signal combination
4. **Timeframe System**: Automatic data resampling and signal mapping

### New Timeframe Management

Each strategy now controls its own timeframe requirements:

```python
class MyStrategy(StrategyBase):
    def get_timeframes(self):
        return ["15min", "1h"]  # Strategy specifies needed timeframes
    
    def initialize(self, backtester):
        # Framework automatically resamples data
        self._resample_data(backtester.original_df)
        
        # Access resampled data
        data_15m = self.get_data_for_timeframe("15min")
        data_1h = self.get_data_for_timeframe("1h")
```

## Available Strategies

### 1. Default Strategy (Meta-Trend Analysis)

**Purpose**: Meta-trend analysis using multiple Supertrend indicators

**Timeframe Behavior**:
- **Configurable Primary Timeframe**: Set via `params["timeframe"]` (default: "15min")
- **1-Minute Precision**: Always includes 1min data for precise stop-loss execution
- **Example Timeframes**: `["15min", "1min"]` or `["5min", "1min"]`

**Configuration**:
```json
{
    "name": "default",
    "weight": 1.0,
    "params": {
        "timeframe": "15min",    // Configurable: "5min", "15min", "1h", etc.
        "stop_loss_pct": 0.03    // Stop loss percentage
    }
}
```

**Algorithm**:
1. Calculate 3 Supertrend indicators with different parameters on primary timeframe
2. Determine meta-trend: all three must agree for directional signal
3. **Entry**: Meta-trend changes from != 1 to == 1 (all trends align upward)
4. **Exit**: Meta-trend changes to -1 (trend reversal) or stop-loss triggered
5. **Stop-Loss**: 1-minute precision using percentage-based threshold

**Strengths**:
- Robust trend following with multiple confirmations
- Configurable for different market timeframes
- Precise risk management
- Low false signals in trending markets

**Best Use Cases**:
- Medium to long-term trend following
- Markets with clear directional movements
- Risk-conscious trading with defined exits

### 2. BBRS Strategy (Bollinger Bands + RSI)

**Purpose**: Market regime-adaptive strategy combining Bollinger Bands and RSI

**Timeframe Behavior**:
- **1-Minute Input**: Strategy receives 1-minute data
- **Internal Resampling**: Underlying Strategy class handles resampling to 15min/1h
- **No Double-Resampling**: Avoids conflicts with existing resampling logic
- **Signal Mapping**: Results mapped back to 1-minute resolution

**Configuration**:
```json
{
    "name": "bbrs",
    "weight": 1.0,
    "params": {
        "bb_width": 0.05,                           // Bollinger Band width threshold
        "bb_period": 20,                            // Bollinger Band period
        "rsi_period": 14,                           // RSI calculation period
        "trending_rsi_threshold": [30, 70],         // RSI thresholds for trending market
        "trending_bb_multiplier": 2.5,              // BB multiplier for trending market
        "sideways_rsi_threshold": [40, 60],         // RSI thresholds for sideways market
        "sideways_bb_multiplier": 1.8,              // BB multiplier for sideways market
        "strategy_name": "MarketRegimeStrategy",    // Implementation variant
        "SqueezeStrategy": true,                    // Enable squeeze detection
        "stop_loss_pct": 0.05                      // Stop loss percentage
    }
}
```

**Algorithm**:

**MarketRegimeStrategy** (Primary Implementation):
1. **Market Regime Detection**: Determines if market is trending or sideways
2. **Adaptive Parameters**: Adjusts BB/RSI thresholds based on market regime
3. **Trending Market Entry**: Price < Lower Band ∧ RSI < 50 ∧ Volume Spike
4. **Sideways Market Entry**: Price ≤ Lower Band ∧ RSI ≤ 40  
5. **Exit Conditions**: Opposite band touch, RSI reversal, or stop-loss
6. **Volume Confirmation**: Requires 1.5× average volume for trending signals

**CryptoTradingStrategy** (Alternative Implementation):
1. **Multi-Timeframe Analysis**: Combines 15-minute and 1-hour Bollinger Bands
2. **Entry**: Price ≤ both 15m & 1h lower bands + RSI < 35 + Volume surge
3. **Exit**: 2:1 risk-reward ratio with ATR-based stops
4. **Adaptive Volatility**: Uses ATR for dynamic stop-loss/take-profit

**Strengths**:
- Adapts to different market regimes
- Multiple timeframe confirmation (internal)
- Volume analysis for signal quality
- Sophisticated entry/exit conditions

**Best Use Cases**:
- Volatile cryptocurrency markets
- Markets with alternating trending/sideways periods
- Short to medium-term trading

## Strategy Combination

### Multi-Strategy Architecture

The StrategyManager allows combining multiple strategies with configurable rules:

```json
{
    "strategies": [
        {
            "name": "default",
            "weight": 0.6,
            "params": {"timeframe": "15min"}
        },
        {
            "name": "bbrs", 
            "weight": 0.4,
            "params": {"strategy_name": "MarketRegimeStrategy"}
        }
    ],
    "combination_rules": {
        "entry": "weighted_consensus",
        "exit": "any",
        "min_confidence": 0.6
    }
}
```

### Signal Combination Methods

**Entry Combinations**:
- **`any`**: Enter if ANY strategy signals entry
- **`all`**: Enter only if ALL strategies signal entry
- **`majority`**: Enter if majority of strategies signal entry  
- **`weighted_consensus`**: Enter based on weighted confidence average

**Exit Combinations**:
- **`any`**: Exit if ANY strategy signals exit (recommended for risk management)
- **`all`**: Exit only if ALL strategies agree
- **`priority`**: Prioritized exit (STOP_LOSS > SELL_SIGNAL > others)

## Performance Characteristics

### Default Strategy Performance

**Strengths**:
- **Trend Accuracy**: High accuracy in strong trending markets
- **Risk Management**: Defined stop-losses with 1-minute precision
- **Low Noise**: Multiple Supertrend confirmation reduces false signals
- **Adaptable**: Works across different timeframes

**Weaknesses**:
- **Sideways Markets**: May generate false signals in ranging markets
- **Lag**: Multiple confirmations can delay entry/exit signals
- **Whipsaws**: Vulnerable to rapid trend reversals

**Optimal Conditions**:
- Clear trending markets
- Medium to low volatility trending
- Sufficient data history for Supertrend calculation

### BBRS Strategy Performance

**Strengths**:
- **Market Adaptation**: Automatically adjusts to market regime
- **Volume Confirmation**: Reduces false signals with volume analysis
- **Multi-Timeframe**: Internal analysis across multiple timeframes
- **Volatility Handling**: Designed for cryptocurrency volatility

**Weaknesses**:
- **Complexity**: More parameters to optimize
- **Market Noise**: Can be sensitive to short-term noise
- **Volume Dependency**: Requires reliable volume data

**Optimal Conditions**:
- High-volume cryptocurrency markets
- Markets with clear regime shifts
- Sufficient data for regime detection

## Usage Examples

### Single Strategy Backtests

```bash
# Default strategy on 15-minute timeframe
uv run .\main.py .\configs\config_default.json

# Default strategy on 5-minute timeframe  
uv run .\main.py .\configs\config_default_5min.json

# BBRS strategy with market regime detection
uv run .\main.py .\configs\config_bbrs.json
```

### Multi-Strategy Backtests

```bash
# Combined strategies with weighted consensus
uv run .\main.py .\configs\config_combined.json
```

### Custom Configurations

**Aggressive Default Strategy**:
```json
{
    "name": "default",
    "params": {
        "timeframe": "5min",      // Faster signals
        "stop_loss_pct": 0.02     // Tighter stop-loss
    }
}
```

**Conservative BBRS Strategy**:
```json
{
    "name": "bbrs", 
    "params": {
        "bb_width": 0.03,         // Tighter BB width
        "stop_loss_pct": 0.07,    // Wider stop-loss
        "SqueezeStrategy": false  // Disable squeeze for simplicity
    }
}
```

## Development Guidelines

### Creating New Strategies

1. **Inherit from StrategyBase**:
```python
from cycles.strategies.base import StrategyBase, StrategySignal

class NewStrategy(StrategyBase):
    def __init__(self, weight=1.0, params=None):
        super().__init__("new_strategy", weight, params)
```

2. **Specify Timeframes**:
```python
def get_timeframes(self):
    return ["1h"]  # Specify required timeframes
```

3. **Implement Core Methods**:
```python
def initialize(self, backtester):
    self._resample_data(backtester.original_df)
    # Calculate indicators...
    self.initialized = True

def get_entry_signal(self, backtester, df_index):
    # Entry logic...
    return StrategySignal("ENTRY", confidence=0.8)

def get_exit_signal(self, backtester, df_index):
    # Exit logic...
    return StrategySignal("EXIT", confidence=1.0)
```

4. **Register Strategy**:
```python
# In StrategyManager._load_strategies()
elif name == "new_strategy":
    strategies.append(NewStrategy(weight, params))
```

### Timeframe Best Practices

1. **Minimize Timeframe Requirements**:
```python
def get_timeframes(self):
    return ["15min"]  # Only what's needed
```

2. **Include 1min for Stop-Loss**:
```python
def get_timeframes(self):
    primary_tf = self.params.get("timeframe", "15min")
    timeframes = [primary_tf]
    if "1min" not in timeframes:
        timeframes.append("1min")
    return timeframes
```

3. **Handle Multi-Timeframe Synchronization**:
```python
def get_entry_signal(self, backtester, df_index):
    # Get current timestamp from primary timeframe
    primary_data = self.get_primary_timeframe_data()
    current_time = primary_data.index[df_index]
    
    # Map to other timeframes
    hourly_data = self.get_data_for_timeframe("1h")
    h1_idx = hourly_data.index.get_indexer([current_time], method='ffill')[0]
```

## Testing and Validation

### Strategy Testing Workflow

1. **Individual Strategy Testing**:
   - Test each strategy independently
   - Validate on different timeframes
   - Check edge cases and data sufficiency

2. **Multi-Strategy Testing**:
   - Test strategy combinations
   - Validate combination rules
   - Monitor for signal conflicts

3. **Timeframe Validation**:
   - Ensure consistent behavior across timeframes
   - Validate data alignment
   - Check memory usage with large datasets

### Performance Monitoring

```python
# Get strategy summary
summary = strategy_manager.get_strategy_summary()
print(f"Strategies: {[s['name'] for s in summary['strategies']]}")
print(f"Timeframes: {summary['all_timeframes']}")

# Monitor individual strategy performance
for strategy in strategy_manager.strategies:
    print(f"{strategy.name}: {strategy.get_timeframes()}")
```

## Advanced Topics

### Multi-Timeframe Strategy Development

For strategies requiring multiple timeframes:

```python
class MultiTimeframeStrategy(StrategyBase):
    def get_timeframes(self):
        return ["5min", "15min", "1h"]
    
    def get_entry_signal(self, backtester, df_index):
        # Analyze multiple timeframes
        data_5m = self.get_data_for_timeframe("5min")
        data_15m = self.get_data_for_timeframe("15min") 
        data_1h = self.get_data_for_timeframe("1h")
        
        # Synchronize across timeframes
        current_time = data_5m.index[df_index]
        idx_15m = data_15m.index.get_indexer([current_time], method='ffill')[0]
        idx_1h = data_1h.index.get_indexer([current_time], method='ffill')[0]
        
        # Multi-timeframe logic
        short_signal = self._analyze_5min(data_5m, df_index)
        medium_signal = self._analyze_15min(data_15m, idx_15m)
        long_signal = self._analyze_1h(data_1h, idx_1h)
        
        # Combine signals with appropriate confidence
        if short_signal and medium_signal and long_signal:
            return StrategySignal("ENTRY", confidence=0.9)
        elif short_signal and medium_signal:
            return StrategySignal("ENTRY", confidence=0.7)
        else:
            return StrategySignal("HOLD", confidence=0.0)
```

### Strategy Optimization

1. **Parameter Optimization**: Systematic testing of strategy parameters
2. **Timeframe Optimization**: Finding optimal timeframes for each strategy
3. **Combination Optimization**: Optimizing weights and combination rules
4. **Market Regime Adaptation**: Adapting strategies to different market conditions

For detailed timeframe system documentation, see [Timeframe System](./timeframe_system.md).