Cycles/IncrementalTrader/docs/migration.md

Migration Guide: Cycles Framework → IncrementalTrader

Overview

This guide helps you migrate from the legacy Cycles framework to the new IncrementalTrader module. The IncrementalTrader module provides a cleaner, more modular architecture while maintaining compatibility with existing strategies and workflows.

Key Architectural Changes

Module Structure

Old Structure (Cycles):

cycles/
├── IncStrategies/
│   ├── base.py
│   ├── default_strategy.py
│   └── bbrs_strategy.py
├── backtest.py
├── trader.py
└── utils/

New Structure (IncrementalTrader):

IncrementalTrader/
├── strategies/
│   ├── base.py
│   ├── metatrend.py
│   ├── random.py
│   ├── bbrs.py
│   └── indicators/
├── trader/
│   ├── trader.py
│   └── position.py
├── backtester/
│   ├── backtester.py
│   ├── config.py
│   └── utils.py
└── docs/

Import Changes

Old Imports:

from cycles.IncStrategies.base import StrategyBase, StrategySignal
from cycles.IncStrategies.default_strategy import DefaultStrategy
from cycles.IncStrategies.bbrs_strategy import BBRSStrategy
from cycles.backtest import Backtester
from cycles.trader import Trader

New Imports:

from IncrementalTrader.strategies.base import IncStrategyBase, IncStrategySignal
from IncrementalTrader.strategies.metatrend import MetaTrendStrategy
from IncrementalTrader.strategies.bbrs import BBRSStrategy
from IncrementalTrader.backtester import IncBacktester
from IncrementalTrader.trader import IncTrader

Strategy Migration

Base Class Changes

Old Base Class:

class MyStrategy(StrategyBase):
    def get_entry_signal(self, backtester, df_index):
        return StrategySignal("ENTRY", confidence=0.8)

New Base Class:

class MyStrategy(IncStrategyBase):
    def get_entry_signal(self, backtester, df_index):
        return IncStrategySignal.BUY(confidence=0.8)

Signal Generation Changes

Old Signal Creation:

# Manual signal creation
signal = StrategySignal("ENTRY", confidence=0.8)
signal = StrategySignal("EXIT", confidence=0.9)
signal = StrategySignal("HOLD", confidence=0.0)

New Signal Creation (Factory Methods):

# Factory methods for cleaner signal creation
signal = IncStrategySignal.BUY(confidence=0.8)
signal = IncStrategySignal.SELL(confidence=0.9)
signal = IncStrategySignal.HOLD(confidence=0.0)

Strategy Name Mapping

Old Strategy	New Strategy	Compatibility Alias
DefaultStrategy	MetaTrendStrategy	IncMetaTrendStrategy
BBRSStrategy	BBRSStrategy	IncBBRSStrategy
N/A	RandomStrategy	IncRandomStrategy

Backtesting Migration

Configuration Changes

Old Configuration:

# Direct backtester usage
backtester = Backtester(data, strategy)
results = backtester.run()

New Configuration:

# Enhanced configuration system
from IncrementalTrader.backtester import IncBacktester, BacktestConfig

config = BacktestConfig(
    initial_capital=10000,
    commission=0.001,
    slippage=0.0001
)

backtester = IncBacktester(config)
results = backtester.run_backtest(data, strategy)

Parameter Optimization

Old Optimization:

# Manual parameter loops
for param1 in values1:
    for param2 in values2:
        strategy = MyStrategy(param1=param1, param2=param2)
        results = backtester.run()

New Optimization:

# Built-in optimization framework
from IncrementalTrader.backtester import OptimizationConfig

opt_config = OptimizationConfig(
    strategy_class=MyStrategy,
    param_ranges={
        'param1': [1, 2, 3, 4, 5],
        'param2': [0.1, 0.2, 0.3, 0.4, 0.5]
    },
    optimization_metric='sharpe_ratio'
)

results = backtester.optimize_strategy(data, opt_config)

Trading Migration

Trader Interface Changes

Old Trader:

trader = Trader(strategy, initial_capital=10000)
trader.process_tick(price_data)

New Trader:

trader = IncTrader(strategy, initial_capital=10000)
trader.process_tick(price_data)

Position Management

Old Position Handling:

# Position management was embedded in trader
if trader.position_size > 0:
    # Handle long position

New Position Handling:

# Dedicated position manager
position_manager = trader.position_manager
if position_manager.has_position():
    current_position = position_manager.get_current_position()
    # Handle position with dedicated methods

Indicator Migration

Import Changes

Old Indicator Imports:

from cycles.IncStrategies.indicators import SupertrendState, ATRState

New Indicator Imports:

from IncrementalTrader.strategies.indicators import SupertrendState, ATRState

Indicator Usage

The indicator interface remains largely the same, but with enhanced features:

Enhanced Indicator Features:

# New indicators have better state management
supertrend = SupertrendState(period=10, multiplier=3.0)

# Process data incrementally
for price_data in data_stream:
    supertrend.update(price_data)
    current_trend = supertrend.get_value()
    trend_direction = supertrend.get_trend()

Compatibility Layer

Backward Compatibility Aliases

The new module provides compatibility aliases for smooth migration:

# These imports work for backward compatibility
from IncrementalTrader.strategies.metatrend import IncMetaTrendStrategy as DefaultStrategy
from IncrementalTrader.strategies.bbrs import IncBBRSStrategy as BBRSStrategy
from IncrementalTrader.strategies.random import IncRandomStrategy as RandomStrategy

Gradual Migration Strategy

1. Phase 1: Update imports to use compatibility aliases
2. Phase 2: Update signal generation to use factory methods
3. Phase 3: Migrate to new configuration system
4. Phase 4: Update to new class names and remove aliases

Enhanced Features

New Capabilities in IncrementalTrader

1. Modular Architecture: Each component can be used independently
2. Enhanced Configuration: Robust configuration with validation
3. Better Error Handling: Comprehensive exception handling and logging
4. Improved Performance: Optimized data processing and memory usage
5. Self-Contained: No external dependencies on legacy modules
6. Enhanced Documentation: Comprehensive API documentation and examples

Performance Improvements

• Memory Efficiency: Reduced memory footprint for large datasets
• Processing Speed: Optimized indicator calculations
• Parallel Processing: Built-in support for parallel backtesting
• Resource Management: Intelligent system resource allocation

Migration Checklist

Pre-Migration

• Review current strategy implementations
• Identify external dependencies
• Backup existing configurations
• Test current system performance

During Migration

• Update import statements
• Replace signal generation with factory methods
• Update configuration format
• Test strategy behavior equivalence
• Validate backtesting results

Post-Migration

• Remove old import statements
• Update documentation
• Performance testing
• Clean up legacy code references

Common Migration Issues

Issue 1: Signal Type Mismatch

Problem: Old string-based signals don't work with new system Solution: Use factory methods (IncStrategySignal.BUY() instead of "ENTRY")

Issue 2: Import Errors

Problem: Old import paths no longer exist Solution: Update to new module structure or use compatibility aliases

Issue 3: Configuration Format

Problem: Old configuration format not compatible Solution: Migrate to new BacktestConfig and OptimizationConfig classes

Issue 4: Indicator State

Problem: Indicator state not preserved during migration Solution: Use new indicator initialization patterns with proper state management

Support and Resources

Documentation

• Strategy Development Guide
• Indicator Reference
• Backtesting Guide
• API Reference

Examples

• Basic Usage Examples
• Strategy migration examples in documentation

Getting Help

• Review the comprehensive API documentation
• Check the examples directory for usage patterns
• Refer to the original Cycles documentation for context

Legacy Framework Reference

Timeframe System (Legacy)

The legacy Cycles framework had sophisticated timeframe management that is preserved in the new system:

Key Concepts from Legacy System:

• Strategy-controlled timeframes
• Automatic resampling
• Precision execution with 1-minute data
• Signal mapping between timeframes

Migration Notes:

• The new TimeframeAggregator provides similar functionality
• Strategies can still specify required timeframes
• Multi-timeframe strategies are fully supported
• 1-minute precision for stop-loss execution is maintained

Strategy Manager (Legacy)

The legacy StrategyManager for multi-strategy combination:

Legacy Features:

• Multi-strategy orchestration
• Signal combination methods (weighted consensus, majority voting)
• Multi-timeframe strategy coordination

Migration Path:

• Individual strategies are now self-contained
• Multi-strategy combination can be implemented at the application level
• Consider using multiple backtests and combining results

Performance Characteristics (Legacy)

Legacy Strategy Performance Notes:

• Default Strategy: High accuracy in trending markets, vulnerable to sideways markets
• BBRS Strategy: Market regime adaptation, volume confirmation, multi-timeframe analysis

New Performance Improvements:

• Enhanced signal generation reduces false positives
• Better risk management with dedicated position manager
• Improved backtesting accuracy with enhanced data handling

---

This migration guide provides a comprehensive path from the legacy Cycles framework to the new IncrementalTrader module while preserving functionality and improving architecture.