Cycles/test/strategy_optimisation/README.md

# Strategy Parameter Optimization

This directory contains comprehensive tools for optimizing trading strategy parameters using the IncrementalTrader framework.

## Overview

The strategy optimization script provides:

- **Parallel Parameter Testing**: Uses multiple CPU cores for efficient optimization
- **Configurable Supertrend Parameters**: Test different period and multiplier combinations
- **Risk Management Optimization**: Optimize stop-loss and take-profit settings
- **Multiple Timeframes**: Test strategies across different timeframes
- **Comprehensive Results**: Detailed analysis and sensitivity reports
- **Custom Parameter Ranges**: Support for custom parameter configurations

## Files

- `strategy_parameter_optimization.py` - Main optimization script
- `custom_params_example.json` - Example custom parameter configuration
- `README.md` - This documentation

## Quick Start

### 1. Basic Quick Test

Run a quick test with a smaller parameter space:

```bash
python tasks/strategy_parameter_optimization.py --quick-test --create-sample-data
```

This will:
- Create sample data if it doesn't exist
- Test a limited set of parameters for faster execution
- Use the optimal number of CPU cores automatically

### 2. Full Optimization

Run comprehensive parameter optimization:

```bash
python tasks/strategy_parameter_optimization.py \
    --data-file "your_data.csv" \
    --start-date "2024-01-01" \
    --end-date "2024-12-31" \
    --optimization-metric "sharpe_ratio"
```

### 3. Custom Parameter Ranges

Create a custom parameter file and use it:

```bash
python tasks/strategy_parameter_optimization.py \
    --custom-params "tasks/custom_params_example.json" \
    --max-workers 4
```

## Parameter Configuration

### Strategy Parameters

The MetaTrend strategy now supports the following configurable parameters:

| Parameter | Type | Description | Example Values |
|-----------|------|-------------|----------------|
| `timeframe` | str | Analysis timeframe | `"5min"`, `"15min"`, `"30min"`, `"1h"` |
| `supertrend_periods` | List[int] | Periods for Supertrend indicators | `[10, 12, 14]`, `[12, 15, 18]` |
| `supertrend_multipliers` | List[float] | Multipliers for Supertrend indicators | `[2.0, 2.5, 3.0]`, `[1.5, 2.0, 2.5]` |
| `min_trend_agreement` | float | Minimum agreement threshold (0.0-1.0) | `0.6`, `0.8`, `1.0` |

### Risk Management Parameters

| Parameter | Type | Description | Example Values |
|-----------|------|-------------|----------------|
| `stop_loss_pct` | float | Stop loss percentage | `0.02` (2%), `0.03` (3%) |
| `take_profit_pct` | float | Take profit percentage | `0.04` (4%), `0.06` (6%) |

### Understanding min_trend_agreement

The `min_trend_agreement` parameter controls how many Supertrend indicators must agree:

- `1.0` - All indicators must agree (original behavior)
- `0.8` - 80% of indicators must agree
- `0.6` - 60% of indicators must agree
- `0.5` - Simple majority must agree

## Usage Examples

### Example 1: Test Different Timeframes

```json
{
  "timeframe": ["5min", "15min", "30min", "1h"],
  "min_trend_agreement": [1.0],
  "stop_loss_pct": [0.03],
  "take_profit_pct": [0.06]
}
```

### Example 2: Optimize Supertrend Parameters

```json
{
  "timeframe": ["15min"],
  "supertrend_periods": [
    [8, 10, 12],
    [10, 12, 14],
    [12, 15, 18],
    [15, 20, 25]
  ],
  "supertrend_multipliers": [
    [1.5, 2.0, 2.5],
    [2.0, 2.5, 3.0],
    [2.5, 3.0, 3.5]
  ],
  "min_trend_agreement": [0.6, 0.8, 1.0]
}
```

### Example 3: Risk Management Focus

```json
{
  "timeframe": ["15min"],
  "stop_loss_pct": [0.01, 0.015, 0.02, 0.025, 0.03, 0.04, 0.05],
  "take_profit_pct": [0.02, 0.03, 0.04, 0.05, 0.06, 0.08, 0.10]
}
```

## Command Line Options

```bash
python tasks/strategy_parameter_optimization.py [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--data-file` | str | `sample_btc_1min.csv` | Data file for backtesting |
| `--data-dir` | str | `data` | Directory containing data files |
| `--results-dir` | str | `results` | Directory for saving results |
| `--start-date` | str | `2024-01-01` | Start date (YYYY-MM-DD) |
| `--end-date` | str | `2024-03-31` | End date (YYYY-MM-DD) |
| `--initial-usd` | float | `10000` | Initial USD balance |
| `--max-workers` | int | `auto` | Maximum parallel workers |
| `--quick-test` | flag | `false` | Use smaller parameter space |
| `--optimization-metric` | str | `sharpe_ratio` | Metric to optimize |
| `--create-sample-data` | flag | `false` | Create sample data |
| `--custom-params` | str | `none` | JSON file with custom ranges |

### Optimization Metrics

Available optimization metrics:

- `profit_ratio` - Total profit ratio
- `sharpe_ratio` - Risk-adjusted return (recommended)
- `sortino_ratio` - Downside risk-adjusted return
- `calmar_ratio` - Return to max drawdown ratio

## Output Files

The script generates several output files in the results directory:

### 1. Summary Report
`optimization_MetaTrendStrategy_sharpe_ratio_TIMESTAMP_summary.json`

Contains:
- Best performing parameters
- Summary statistics across all runs
- Session information

### 2. Detailed Results
`optimization_MetaTrendStrategy_sharpe_ratio_TIMESTAMP_detailed.csv`

Contains:
- All parameter combinations tested
- Performance metrics for each combination
- Success/failure status

### 3. Individual Strategy Results
`optimization_MetaTrendStrategy_sharpe_ratio_TIMESTAMP_strategy_N_metatrend.json`

Contains:
- Detailed results for each parameter combination
- Trade-by-trade breakdown
- Strategy-specific metrics

### 4. Sensitivity Analysis
`sensitivity_analysis_TIMESTAMP.json`

Contains:
- Parameter correlation analysis
- Performance impact of each parameter
- Top performing configurations

### 5. Master Index
`optimization_MetaTrendStrategy_sharpe_ratio_TIMESTAMP_index.json`

Contains:
- File index for easy navigation
- Quick statistics summary
- Session metadata

## Performance Considerations

### System Resources

The script automatically detects your system capabilities and uses optimal worker counts:

- **CPU Cores**: Uses ~75% of available cores
- **Memory**: Limits workers based on available RAM
- **I/O**: Handles large result datasets efficiently

### Parameter Space Size

Be aware of exponential growth in parameter combinations:

- Quick test: ~48 combinations
- Full test: ~5,000+ combinations
- Custom ranges: Varies based on configuration

### Execution Time

Approximate execution times (varies by system and data size):

- Quick test: 2-10 minutes
- Medium test: 30-60 minutes  
- Full test: 2-8 hours

## Data Requirements

### Data Format

The script expects CSV data with columns:
- `timestamp` - Unix timestamp in milliseconds
- `open` - Opening price
- `high` - Highest price
- `low` - Lowest price
- `close` - Closing price
- `volume` - Trading volume

### Sample Data

Use `--create-sample-data` to generate sample data for testing:

```bash
python tasks/strategy_parameter_optimization.py --create-sample-data --quick-test
```

## Advanced Usage

### 1. Distributed Optimization

For very large parameter spaces, consider running multiple instances:

```bash
# Terminal 1 - Test timeframes 5min, 15min
python tasks/strategy_parameter_optimization.py --custom-params timeframe_5_15.json

# Terminal 2 - Test timeframes 30min, 1h  
python tasks/strategy_parameter_optimization.py --custom-params timeframe_30_1h.json
```

### 2. Walk-Forward Analysis

For more robust results, test across multiple time periods:

```bash
# Q1 2024
python tasks/strategy_parameter_optimization.py --start-date 2024-01-01 --end-date 2024-03-31

# Q2 2024
python tasks/strategy_parameter_optimization.py --start-date 2024-04-01 --end-date 2024-06-30
```

### 3. Custom Metrics

The script supports custom optimization metrics. See the documentation for implementation details.

## Troubleshooting

### Common Issues

1. **Memory Errors**: Reduce `--max-workers` or use `--quick-test`
2. **Data Not Found**: Use `--create-sample-data` or check file path
3. **Import Errors**: Ensure IncrementalTrader is properly installed
4. **Slow Performance**: Check system resources and reduce parameter space

### Logging

The script provides detailed logging. For debug information:

```python
import logging
logging.getLogger().setLevel(logging.DEBUG)
```

## Examples

### Quick Start Example

```bash
# Run quick optimization with sample data
python tasks/strategy_parameter_optimization.py \
    --quick-test \
    --create-sample-data \
    --optimization-metric sharpe_ratio \
    --max-workers 4
```

### Production Example

```bash
# Run comprehensive optimization with real data
python tasks/strategy_parameter_optimization.py \
    --data-file "BTCUSDT_1m_2024.csv" \
    --start-date "2024-01-01" \
    --end-date "2024-12-31" \
    --optimization-metric calmar_ratio \
    --custom-params "production_params.json"
```

This comprehensive setup allows you to:

1. **Test the modified MetaTrend strategy** with configurable Supertrend parameters
2. **Run parameter optimization in parallel** using system utilities from utils.py
3. **Test multiple timeframes and risk management settings**
4. **Get detailed analysis and sensitivity reports**
5. **Use custom parameter ranges** for focused optimization

The script leverages the existing IncrementalTrader framework and integrates with the utilities you already have in place.