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:

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:

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:

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

{
  "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

{
  "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

{
  "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

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:

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:

# 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:

# 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:

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

Examples

Quick Start Example

# 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

# 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.