Cycles/IncrementalTrader/README.md

IncrementalTrader

A high-performance, memory-efficient trading framework designed for real-time algorithmic trading and backtesting. Built around the principle of incremental computation, IncrementalTrader processes new data points efficiently without recalculating entire histories.

🚀 Key Features

• Incremental Computation: Constant memory usage and O(1) processing time per data point
• Real-time Capable: Designed for live trading with minimal latency
• Modular Architecture: Clean separation between strategies, execution, and testing
• Built-in Strategies: MetaTrend, BBRS, and Random strategies included
• Comprehensive Backtesting: Multi-threaded backtesting with parameter optimization
• Rich Indicators: Supertrend, Bollinger Bands, RSI, Moving Averages, and more
• Performance Tracking: Detailed metrics and portfolio analysis

📦 Installation

# Clone the repository
git clone <repository-url>
cd Cycles

# Install dependencies
pip install -r requirements.txt

# Import the module
from IncrementalTrader import *

🏃‍♂️ Quick Start

Basic Strategy Usage

from IncrementalTrader import MetaTrendStrategy, IncTrader
import pandas as pd

# Load your data
data = pd.read_csv('your_data.csv')

# Create strategy
strategy = MetaTrendStrategy("metatrend", params={
    "timeframe": "15min",
    "supertrend_periods": [10, 20, 30],
    "supertrend_multipliers": [2.0, 3.0, 4.0]
})

# Create trader
trader = IncTrader(strategy, initial_usd=10000)

# Process data
for _, row in data.iterrows():
    trader.process_data_point(
        timestamp=row['timestamp'],
        ohlcv=(row['open'], row['high'], row['low'], row['close'], row['volume'])
    )

# Get results
results = trader.get_results()
print(f"Final Portfolio Value: ${results['final_portfolio_value']:.2f}")
print(f"Total Return: {results['total_return_pct']:.2f}%")

Backtesting

from IncrementalTrader import IncBacktester, BacktestConfig

# Configure backtest
config = BacktestConfig(
    initial_usd=10000,
    stop_loss_pct=0.03,
    take_profit_pct=0.06,
    start_date="2024-01-01",
    end_date="2024-12-31"
)

# Run backtest
backtester = IncBacktester()
results = backtester.run_single_strategy(
    strategy_class=MetaTrendStrategy,
    strategy_params={"timeframe": "15min"},
    config=config,
    data_file="data/BTCUSDT_1m.csv"
)

# Analyze results
print(f"Sharpe Ratio: {results['performance_metrics']['sharpe_ratio']:.2f}")
print(f"Max Drawdown: {results['performance_metrics']['max_drawdown_pct']:.2f}%")

📊 Available Strategies

MetaTrend Strategy

A sophisticated trend-following strategy that uses multiple Supertrend indicators to detect market trends.

strategy = MetaTrendStrategy("metatrend", params={
    "timeframe": "15min",
    "supertrend_periods": [10, 20, 30],
    "supertrend_multipliers": [2.0, 3.0, 4.0],
    "min_trend_agreement": 0.6
})

BBRS Strategy

Combines Bollinger Bands and RSI with market regime detection for adaptive trading.

strategy = BBRSStrategy("bbrs", params={
    "timeframe": "15min",
    "bb_period": 20,
    "bb_std": 2.0,
    "rsi_period": 14,
    "volume_ma_period": 20
})

Random Strategy

A testing strategy that generates random signals for framework validation.

strategy = RandomStrategy("random", params={
    "timeframe": "15min",
    "buy_probability": 0.1,
    "sell_probability": 0.1
})

🔧 Technical Indicators

All indicators are designed for incremental computation:

from IncrementalTrader.strategies.indicators import *

# Moving Averages
sma = MovingAverageState(period=20)
ema = ExponentialMovingAverageState(period=20, alpha=0.1)

# Volatility
atr = ATRState(period=14)

# Trend
supertrend = SupertrendState(period=10, multiplier=3.0)

# Oscillators
rsi = RSIState(period=14)
bb = BollingerBandsState(period=20, std_dev=2.0)

# Update with new data
for price in price_data:
    sma.update(price)
    current_sma = sma.get_value()

🧪 Parameter Optimization

from IncrementalTrader import OptimizationConfig

# Define parameter ranges
param_ranges = {
    "supertrend_periods": [[10, 20, 30], [15, 25, 35], [20, 30, 40]],
    "supertrend_multipliers": [[2.0, 3.0, 4.0], [1.5, 2.5, 3.5]],
    "min_trend_agreement": [0.5, 0.6, 0.7, 0.8]
}

# Configure optimization
opt_config = OptimizationConfig(
    base_config=config,
    param_ranges=param_ranges,
    max_workers=4
)

# Run optimization
results = backtester.optimize_strategy(
    strategy_class=MetaTrendStrategy,
    optimization_config=opt_config,
    data_file="data/BTCUSDT_1m.csv"
)

# Get best parameters
best_params = results['best_params']
best_performance = results['best_performance']

📈 Performance Analysis

# Get detailed performance metrics
performance = results['performance_metrics']

print(f"Total Trades: {performance['total_trades']}")
print(f"Win Rate: {performance['win_rate']:.2f}%")
print(f"Profit Factor: {performance['profit_factor']:.2f}")
print(f"Sharpe Ratio: {performance['sharpe_ratio']:.2f}")
print(f"Max Drawdown: {performance['max_drawdown_pct']:.2f}%")
print(f"Calmar Ratio: {performance['calmar_ratio']:.2f}")

# Access trade history
trades = results['trades']
for trade in trades[-5:]:  # Last 5 trades
    print(f"Trade: {trade['side']} at {trade['price']} - P&L: {trade['pnl']:.2f}")

🏗️ Architecture

IncrementalTrader follows a modular architecture:

IncrementalTrader/
├── strategies/          # Trading strategies and indicators
│   ├── base.py         # Base classes and framework
│   ├── metatrend.py    # MetaTrend strategy
│   ├── bbrs.py         # BBRS strategy
│   ├── random.py       # Random strategy
│   └── indicators/     # Technical indicators
├── trader/             # Trade execution and position management
│   ├── trader.py       # Main trader implementation
│   └── position.py     # Position management
├── backtester/         # Backtesting framework
│   ├── backtester.py   # Main backtesting engine
│   ├── config.py       # Configuration management
│   └── utils.py        # Utilities and helpers
└── docs/               # Documentation

🔍 Memory Efficiency

Traditional batch processing vs. IncrementalTrader:

Aspect	Batch Processing	IncrementalTrader
Memory Usage	O(n) - grows with data	O(1) - constant
Processing Time	O(n) - recalculates all	O(1) - per data point
Real-time Capable	No - too slow	Yes - designed for it
Scalability	Poor - memory limited	Excellent - unlimited data

📚 Documentation

• Architecture Overview - Detailed system design
• Strategy Development Guide - How to create custom strategies
• Indicator Reference - Complete indicator documentation
• Backtesting Guide - Advanced backtesting features
• API Reference - Complete API documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For questions, issues, or contributions:

• Open an issue on GitHub
• Check the documentation in the docs/ folder
• Review the examples in the examples/ folder

---

IncrementalTrader - Efficient, scalable, and production-ready algorithmic trading framework.