Simon/Cycles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cleaning up

Browse Source
This commit is contained in:
Ajasra
2025-05-29 00:11:57 +08:00
parent b9836efab7
commit 54e3f5677a
9 changed files with 0 additions and 2401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/analysis.md
View File

@@ -1,106 +0,0 @@
# Analysis Module
This document provides an overview of the `Analysis` module and its components, which are typically used for technical analysis of financial market data.
## Modules
The `Analysis` module includes classes for calculating common technical indicators:
- **Relative Strength Index (RSI)**: Implemented in `cycles/Analysis/rsi.py`.
- **Bollinger Bands**: Implemented in `cycles/Analysis/boillinger_band.py`.
- Note: Trading strategies are detailed in `strategies.md`.
## Class: `RSI`
Found in `cycles/Analysis/rsi.py`.
Calculates the Relative Strength Index.
### Mathematical Model
The standard RSI calculation typically involves Wilder's smoothing for average gains and losses.
1. **Price Change (Delta)**: Difference between consecutive closing prices.
2. **Gain and Loss**: Separate positive (gain) and negative (loss, expressed as positive) price changes.
3. **Average Gain (AvgU)** and **Average Loss (AvgD)**: Smoothed averages of gains and losses over the RSI period. Wilder's smoothing is a specific type of exponential moving average (EMA):
- Initial AvgU/AvgD: Simple Moving Average (SMA) over the first `period` values.
- Subsequent AvgU: `(Previous AvgU * (period - 1) + Current Gain) / period`
- Subsequent AvgD: `(Previous AvgD * (period - 1) + Current Loss) / period`
4. **Relative Strength (RS)**:
$$
RS = \\frac{\\text{AvgU}}{\\text{AvgD}}
$$
5. **RSI**:
$$
RSI = 100 - \\frac{100}{1 + RS}
$$
Special conditions:
- If AvgD is 0: RSI is 100 if AvgU > 0, or 50 if AvgU is also 0 (neutral).
### `__init__(self, config: dict)`
- **Description**: Initializes the RSI calculator.
- **Parameters**:\n - `config` (dict): Configuration dictionary. Must contain an `'rsi_period'` key with a positive integer value (e.g., `{'rsi_period': 14}`).
### `calculate(self, data_df: pd.DataFrame, price_column: str = 'close') -> pd.DataFrame`
- **Description**: Calculates the RSI (using Wilder's smoothing by default) and adds it as an 'RSI' column to the input DataFrame. This method utilizes `calculate_custom_rsi` internally with `smoothing='EMA'`.
- **Parameters**:\n - `data_df` (pd.DataFrame): DataFrame with historical price data. Must contain the `price_column`.\n - `price_column` (str, optional): The name of the column containing price data. Defaults to 'close'.
- **Returns**: `pd.DataFrame` - A copy of the input DataFrame with an added 'RSI' column. If data length is insufficient for the period, the 'RSI' column will contain `np.nan`.
### `calculate_custom_rsi(price_series: pd.Series, window: int = 14, smoothing: str = 'SMA') -> pd.Series` (Static Method)
- **Description**: Calculates RSI with a specified window and smoothing method (SMA or EMA). This is the core calculation engine.
- **Parameters**:
- `price_series` (pd.Series): Series of prices.
- `window` (int, optional): The period for RSI calculation. Defaults to 14. Must be a positive integer.
- `smoothing` (str, optional): Smoothing method, can be 'SMA' (Simple Moving Average) or 'EMA' (Exponential Moving Average, specifically Wilder's smoothing when `alpha = 1/window`). Defaults to 'SMA'.
- **Returns**: `pd.Series` - Series containing the RSI values. Returns a series of NaNs if data length is insufficient.
## Class: `BollingerBands`
Found in `cycles/Analysis/boillinger_band.py`.
Calculates Bollinger Bands.
### Mathematical Model
1. **Middle Band**: Simple Moving Average (SMA) over `period`.
$$
\\text{Middle Band} = \\text{SMA}(\\text{price}, \\text{period})
$$
2. **Standard Deviation (σ)**: Standard deviation of price over `period`.
3. **Upper Band**: Middle Band + `num_std` × σ
$$
\\text{Upper Band} = \\text{Middle Band} + \\text{num_std} \\times \\sigma_{\\text{period}}
$$
4. **Lower Band**: Middle Band − `num_std` × σ
$$
\\text{Lower Band} = \\text{Middle Band} - \\text{num_std} \\times \\sigma_{\\text{period}}
$$
For the adaptive calculation in the `calculate` method (when `squeeze=False`):
- **BBWidth**: `(Reference Upper Band - Reference Lower Band) / SMA`, where reference bands are typically calculated using a 2.0 standard deviation multiplier.
- **MarketRegime**: Determined by comparing `BBWidth` to a threshold from the configuration. `1` for sideways, `0` for trending.
- The `num_std` used for the final Upper and Lower Bands then varies based on this `MarketRegime` and the `bb_std_dev_multiplier` values for "trending" and "sideways" markets from the configuration, applied row-wise.
### `__init__(self, config: dict)`
- **Description**: Initializes the BollingerBands calculator.
- **Parameters**:\n - `config` (dict): Configuration dictionary. It must contain:
- `'bb_period'` (int): Positive integer for the moving average and standard deviation period.
- `'trending'` (dict): Containing `'bb_std_dev_multiplier'` (float, positive) for trending markets.
- `'sideways'` (dict): Containing `'bb_std_dev_multiplier'` (float, positive) for sideways markets.
- `'bb_width'` (float): Positive float threshold for determining market regime.
### `calculate(self, data_df: pd.DataFrame, price_column: str = 'close', squeeze: bool = False) -> pd.DataFrame`
- **Description**: Calculates Bollinger Bands and adds relevant columns to the DataFrame.
- If `squeeze` is `False` (default): Calculates adaptive Bollinger Bands. It determines the market regime (trending/sideways) based on `BBWidth` and applies different standard deviation multipliers (from the `config`) on a row-by-row basis. Adds 'SMA', 'UpperBand', 'LowerBand', 'BBWidth', and 'MarketRegime' columns.
- If `squeeze` is `True`: Calculates simpler Bollinger Bands with a fixed window of 14 and a standard deviation multiplier of 1.5 by calling `calculate_custom_bands`. Adds 'SMA', 'UpperBand', 'LowerBand' columns; 'BBWidth' and 'MarketRegime' will be `NaN`.
- **Parameters**:\n - `data_df` (pd.DataFrame): DataFrame with price data. Must include the `price_column`.\n - `price_column` (str, optional): The name of the column containing the price data. Defaults to 'close'.\n - `squeeze` (bool, optional): If `True`, calculates bands with fixed parameters (window 14, std 1.5). Defaults to `False`.
- **Returns**: `pd.DataFrame` - A copy of the original DataFrame with added Bollinger Band related columns.
### `calculate_custom_bands(price_series: pd.Series, window: int = 20, num_std: float = 2.0, min_periods: int = None) -> tuple[pd.Series, pd.Series, pd.Series]` (Static Method)
- **Description**: Calculates Bollinger Bands with a specified window, standard deviation multiplier, and minimum periods.
- **Parameters**:
- `price_series` (pd.Series): Series of prices.
- `window` (int, optional): The period for the moving average and standard deviation. Defaults to 20.
- `num_std` (float, optional): The number of standard deviations for the upper and lower bands. Defaults to 2.0.
- `min_periods` (int, optional): Minimum number of observations in window required to have a value. Defaults to `window` if `None`.
- **Returns**: `tuple[pd.Series, pd.Series, pd.Series]` - A tuple containing the Upper band, SMA, and Lower band series.

405
docs/strategies.md
View File

@@ -1,405 +0,0 @@
# 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).

390
docs/strategy_manager.md
View File

@@ -1,390 +0,0 @@
# Strategy Manager Documentation
## Overview
The Strategy Manager is a sophisticated orchestration system that enables the combination of multiple trading strategies with configurable signal aggregation rules. It supports multi-timeframe analysis, weighted consensus voting, and flexible signal combination methods.
## Architecture
### Core Components
1. **StrategyBase**: Abstract base class defining the strategy interface
2. **StrategySignal**: Encapsulates trading signals with confidence levels
3. **StrategyManager**: Orchestrates multiple strategies and combines signals
4. **Strategy Implementations**: DefaultStrategy, BBRSStrategy, etc.
### New Timeframe System
The framework now supports strategy-level timeframe management:
- **Strategy-Controlled Timeframes**: Each strategy specifies its required timeframes
- **Automatic Data Resampling**: Framework automatically resamples 1-minute data to strategy needs
- **Multi-Timeframe Support**: Strategies can use multiple timeframes simultaneously
- **Precision Stop-Loss**: All strategies maintain 1-minute data for precise execution
```python
class MyStrategy(StrategyBase):
def get_timeframes(self):
return ["15min", "1h"] # Strategy needs both timeframes
def initialize(self, backtester):
# Access resampled data
data_15m = self.get_data_for_timeframe("15min")
data_1h = self.get_data_for_timeframe("1h")
# Setup indicators...
```
## Strategy Interface
### StrategyBase Class
All strategies must inherit from `StrategyBase` and implement:
```python
from cycles.strategies.base import StrategyBase, StrategySignal
class MyStrategy(StrategyBase):
def get_timeframes(self) -> List[str]:
"""Specify required timeframes"""
return ["15min"]
def initialize(self, backtester) -> None:
"""Setup strategy with data"""
self._resample_data(backtester.original_df)
# Calculate indicators...
self.initialized = True
def get_entry_signal(self, backtester, df_index: int) -> StrategySignal:
"""Generate entry signals"""
if condition_met:
return StrategySignal("ENTRY", confidence=0.8)
return StrategySignal("HOLD", confidence=0.0)
def get_exit_signal(self, backtester, df_index: int) -> StrategySignal:
"""Generate exit signals"""
if exit_condition:
return StrategySignal("EXIT", confidence=1.0,
metadata={"type": "SELL_SIGNAL"})
return StrategySignal("HOLD", confidence=0.0)
```
### StrategySignal Class
Encapsulates trading signals with metadata:
```python
# Entry signal with high confidence
entry_signal = StrategySignal("ENTRY", confidence=0.9)
# Exit signal with specific price
exit_signal = StrategySignal("EXIT", confidence=1.0, price=50000,
metadata={"type": "STOP_LOSS"})
# Hold signal
hold_signal = StrategySignal("HOLD", confidence=0.0)
```
## Available Strategies
### 1. Default Strategy
Meta-trend analysis using multiple Supertrend indicators.
**Features:**
- Uses 3 Supertrend indicators with different parameters
- Configurable timeframe (default: 15min)
- Entry when all trends align upward
- Exit on trend reversal or stop-loss
**Configuration:**
```json
{
"name": "default",
"weight": 1.0,
"params": {
"timeframe": "15min",
"stop_loss_pct": 0.03
}
}
```
**Timeframes:**
- Primary: Configurable (default 15min)
- Stop-loss: Always includes 1min for precision
### 2. BBRS Strategy
Bollinger Bands + RSI with market regime detection.
**Features:**
- Market regime detection (trending vs sideways)
- Adaptive parameters based on market conditions
- Volume analysis and confirmation
- Multi-timeframe internal analysis (1min → 15min/1h)
**Configuration:**
```json
{
"name": "bbrs",
"weight": 1.0,
"params": {
"bb_width": 0.05,
"bb_period": 20,
"rsi_period": 14,
"strategy_name": "MarketRegimeStrategy",
"stop_loss_pct": 0.05
}
}
```
**Timeframes:**
- Input: 1min (Strategy class handles internal resampling)
- Internal: 15min, 1h (handled by underlying Strategy class)
- Output: Mapped back to 1min for backtesting
## Signal Combination
### Entry Signal Combination
```python
combination_rules = {
"entry": "weighted_consensus", # or "any", "all", "majority"
"min_confidence": 0.6
}
```
**Methods:**
- **`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 average confidence
### Exit Signal Combination
```python
combination_rules = {
"exit": "priority" # or "any", "all"
}
```
**Methods:**
- **`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)
## Configuration
### Basic Strategy Manager Setup
```json
{
"strategies": [
{
"name": "default",
"weight": 0.6,
"params": {
"timeframe": "15min",
"stop_loss_pct": 0.03
}
},
{
"name": "bbrs",
"weight": 0.4,
"params": {
"bb_width": 0.05,
"strategy_name": "MarketRegimeStrategy"
}
}
],
"combination_rules": {
"entry": "weighted_consensus",
"exit": "any",
"min_confidence": 0.5
}
}
```
### Timeframe Examples
**Single Timeframe Strategy:**
```json
{
"name": "default",
"params": {
"timeframe": "5min" # Strategy works on 5-minute data
}
}
```
**Multi-Timeframe Strategy (Future Enhancement):**
```json
{
"name": "multi_tf_strategy",
"params": {
"timeframes": ["5min", "15min", "1h"], # Multiple timeframes
"primary_timeframe": "15min"
}
}
```
## Usage Examples
### Create Strategy Manager
```python
from cycles.strategies import create_strategy_manager
config = {
"strategies": [
{"name": "default", "weight": 1.0, "params": {"timeframe": "15min"}}
],
"combination_rules": {
"entry": "any",
"exit": "any"
}
}
strategy_manager = create_strategy_manager(config)
```
### Initialize and Use
```python
# Initialize with backtester
strategy_manager.initialize(backtester)
# Get signals during backtesting
entry_signal = strategy_manager.get_entry_signal(backtester, df_index)
exit_signal, exit_price = strategy_manager.get_exit_signal(backtester, df_index)
# Get strategy summary
summary = strategy_manager.get_strategy_summary()
print(f"Loaded strategies: {[s['name'] for s in summary['strategies']]}")
print(f"All timeframes: {summary['all_timeframes']}")
```
## Extending the System
### Adding New Strategies
1. **Create Strategy Class:**
```python
class NewStrategy(StrategyBase):
def get_timeframes(self):
return ["1h"] # Specify required timeframes
def initialize(self, backtester):
self._resample_data(backtester.original_df)
# Setup indicators...
self.initialized = True
def get_entry_signal(self, backtester, df_index):
# Implement entry logic
pass
def get_exit_signal(self, backtester, df_index):
# Implement exit logic
pass
```
2. **Register in StrategyManager:**
```python
# In StrategyManager._load_strategies()
elif name == "new_strategy":
strategies.append(NewStrategy(weight, params))
```
### Multi-Timeframe Strategy Development
For strategies requiring multiple timeframes:
```python
class MultiTimeframeStrategy(StrategyBase):
def get_timeframes(self):
return ["5min", "15min", "1h"]
def initialize(self, backtester):
self._resample_data(backtester.original_df)
# Access different 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")
# Calculate indicators on each timeframe
# ...
def _calculate_signal_confidence(self, backtester, df_index):
# Analyze multiple timeframes for confidence
primary_signal = self._get_primary_signal(df_index)
confirmation = self._get_timeframe_confirmation(df_index)
return primary_signal * confirmation
```
## Performance Considerations
### Timeframe Management
- **Efficient Resampling**: Each strategy resamples data once during initialization
- **Memory Usage**: Only required timeframes are kept in memory
- **Signal Mapping**: Efficient mapping between timeframes using pandas reindex
### Strategy Combination
- **Lazy Evaluation**: Signals calculated only when needed
- **Error Handling**: Individual strategy failures don't crash the system
- **Logging**: Comprehensive logging for debugging and monitoring
## Best Practices
1. **Strategy Design:**
- Specify minimal required timeframes
- Include 1min for stop-loss precision
- Use confidence levels effectively
2. **Signal Combination:**
- Use `any` for exits (risk management)
- Use `weighted_consensus` for entries
- Set appropriate minimum confidence levels
3. **Error Handling:**
- Implement robust initialization checks
- Handle missing data gracefully
- Log strategy-specific warnings
4. **Testing:**
- Test strategies individually before combining
- Validate timeframe requirements
- Monitor memory usage with large datasets
## Troubleshooting
### Common Issues
1. **Timeframe Mismatches:**
- Ensure strategy specifies correct timeframes
- Check data availability for all timeframes
2. **Signal Conflicts:**
- Review combination rules
- Adjust confidence thresholds
- Monitor strategy weights
3. **Performance Issues:**
- Minimize timeframe requirements
- Optimize indicator calculations
- Use efficient pandas operations
### Debugging Tips
- Enable detailed logging: `logging.basicConfig(level=logging.DEBUG)`
- Use strategy summary: `manager.get_strategy_summary()`
- Test individual strategies before combining
- Monitor signal confidence levels
---
**Version**: 1.0.0
**Last Updated**: January 2025
**TCP Cycles Project**

488
docs/timeframe_system.md
View File

@@ -1,488 +0,0 @@
# Timeframe System Documentation
## Overview
The Cycles framework features a sophisticated timeframe management system that allows strategies to operate on their preferred timeframes while maintaining precise execution control. This system supports both single-timeframe and multi-timeframe strategies with automatic data resampling and intelligent signal mapping.
## Architecture
### Core Concepts
1. **Strategy-Controlled Timeframes**: Each strategy specifies its required timeframes
2. **Automatic Resampling**: Framework resamples 1-minute data to strategy needs
3. **Precision Execution**: All strategies maintain 1-minute data for accurate stop-loss execution
4. **Signal Mapping**: Intelligent mapping between different timeframe resolutions
### Data Flow
```
Original 1min Data
↓
Strategy.get_timeframes() → ["15min", "1h"]
↓
Automatic Resampling
↓
Strategy Logic (15min + 1h analysis)
↓
Signal Generation
↓
Map to Working Timeframe
↓
Backtesting Engine
```
## Strategy Timeframe Interface
### StrategyBase Methods
All strategies inherit timeframe capabilities from `StrategyBase`:
```python
class MyStrategy(StrategyBase):
def get_timeframes(self) -> List[str]:
"""Specify required timeframes for this strategy"""
return ["15min", "1h"] # Strategy needs both timeframes
def initialize(self, backtester) -> None:
# Automatic resampling happens here
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")
# Calculate indicators on each timeframe
self.indicators_15m = self._calculate_indicators(data_15m)
self.indicators_1h = self._calculate_indicators(data_1h)
self.initialized = True
```
### Data Access Methods
```python
# Get data for specific timeframe
data_15m = strategy.get_data_for_timeframe("15min")
# Get primary timeframe data (first in list)
primary_data = strategy.get_primary_timeframe_data()
# Check available timeframes
timeframes = strategy.get_timeframes()
```
## Supported Timeframes
### Standard Timeframes
- **`"1min"`**: 1-minute bars (original resolution)
- **`"5min"`**: 5-minute bars
- **`"15min"`**: 15-minute bars
- **`"30min"`**: 30-minute bars
- **`"1h"`**: 1-hour bars
- **`"4h"`**: 4-hour bars
- **`"1d"`**: Daily bars
### Custom Timeframes
Any pandas-compatible frequency string is supported:
- **`"2min"`**: 2-minute bars
- **`"10min"`**: 10-minute bars
- **`"2h"`**: 2-hour bars
- **`"12h"`**: 12-hour bars
## Strategy Examples
### Single Timeframe Strategy
```python
class SingleTimeframeStrategy(StrategyBase):
def get_timeframes(self):
return ["15min"] # Only needs 15-minute data
def initialize(self, backtester):
self._resample_data(backtester.original_df)
# Work with 15-minute data
data = self.get_primary_timeframe_data()
self.indicators = self._calculate_indicators(data)
self.initialized = True
def get_entry_signal(self, backtester, df_index):
# df_index refers to 15-minute data
if self.indicators['signal'][df_index]:
return StrategySignal("ENTRY", confidence=0.8)
return StrategySignal("HOLD", confidence=0.0)
```
### Multi-Timeframe Strategy
```python
class MultiTimeframeStrategy(StrategyBase):
def get_timeframes(self):
return ["15min", "1h", "4h"] # Multiple timeframes
def initialize(self, backtester):
self._resample_data(backtester.original_df)
# Access different timeframes
self.data_15m = self.get_data_for_timeframe("15min")
self.data_1h = self.get_data_for_timeframe("1h")
self.data_4h = self.get_data_for_timeframe("4h")
# Calculate indicators on each timeframe
self.trend_4h = self._calculate_trend(self.data_4h)
self.momentum_1h = self._calculate_momentum(self.data_1h)
self.entry_signals_15m = self._calculate_entries(self.data_15m)
self.initialized = True
def get_entry_signal(self, backtester, df_index):
# Primary timeframe is 15min (first in list)
# Map df_index to other timeframes for confirmation
# Get current 15min timestamp
current_time = self.data_15m.index[df_index]
# Find corresponding indices in other timeframes
h1_idx = self.data_1h.index.get_indexer([current_time], method='ffill')[0]
h4_idx = self.data_4h.index.get_indexer([current_time], method='ffill')[0]
# Multi-timeframe confirmation
trend_ok = self.trend_4h[h4_idx] > 0
momentum_ok = self.momentum_1h[h1_idx] > 0.5
entry_signal = self.entry_signals_15m[df_index]
if trend_ok and momentum_ok and entry_signal:
confidence = 0.9 # High confidence with all timeframes aligned
return StrategySignal("ENTRY", confidence=confidence)
return StrategySignal("HOLD", confidence=0.0)
```
### Configurable Timeframe Strategy
```python
class ConfigurableStrategy(StrategyBase):
def get_timeframes(self):
# Strategy timeframe configurable via parameters
primary_tf = self.params.get("timeframe", "15min")
return [primary_tf, "1min"] # Primary + 1min for stop-loss
def initialize(self, backtester):
self._resample_data(backtester.original_df)
primary_tf = self.get_timeframes()[0]
self.data = self.get_data_for_timeframe(primary_tf)
# Indicator parameters can also be timeframe-dependent
if primary_tf == "5min":
self.ma_period = 20
elif primary_tf == "15min":
self.ma_period = 14
else:
self.ma_period = 10
self.indicators = self._calculate_indicators(self.data)
self.initialized = True
```
## Built-in Strategy Timeframe Behavior
### Default Strategy
**Timeframes**: Configurable primary + 1min for stop-loss
```python
# Configuration
{
"name": "default",
"params": {
"timeframe": "5min" # Configurable timeframe
}
}
# Resulting timeframes: ["5min", "1min"]
```
**Features**:
- Supertrend analysis on configured timeframe
- 1-minute precision for stop-loss execution
- Optimized for 15-minute default, but works on any timeframe
### BBRS Strategy
**Timeframes**: 1min input (internal resampling)
```python
# Configuration
{
"name": "bbrs",
"params": {
"strategy_name": "MarketRegimeStrategy"
}
}
# Resulting timeframes: ["1min"]
```
**Features**:
- Uses 1-minute data as input
- Internal resampling to 15min/1h by Strategy class
- Signals mapped back to 1-minute resolution
- No double-resampling issues
## Advanced Features
### Timeframe Synchronization
When working with multiple timeframes, synchronization is crucial:
```python
def _get_synchronized_signals(self, df_index, primary_timeframe="15min"):
"""Get signals synchronized across timeframes"""
# Get timestamp from primary timeframe
primary_data = self.get_data_for_timeframe(primary_timeframe)
current_time = primary_data.index[df_index]
signals = {}
for tf in self.get_timeframes():
if tf == primary_timeframe:
signals[tf] = df_index
else:
# Find corresponding index in other timeframe
tf_data = self.get_data_for_timeframe(tf)
tf_idx = tf_data.index.get_indexer([current_time], method='ffill')[0]
signals[tf] = tf_idx
return signals
```
### Dynamic Timeframe Selection
Strategies can adapt timeframes based on market conditions:
```python
class AdaptiveStrategy(StrategyBase):
def get_timeframes(self):
# Fixed set of timeframes strategy might need
return ["5min", "15min", "1h"]
def _select_active_timeframe(self, market_volatility):
"""Select timeframe based on market conditions"""
if market_volatility > 0.8:
return "5min" # High volatility -> shorter timeframe
elif market_volatility > 0.4:
return "15min" # Medium volatility -> medium timeframe
else:
return "1h" # Low volatility -> longer timeframe
def get_entry_signal(self, backtester, df_index):
# Calculate market volatility
volatility = self._calculate_volatility(df_index)
# Select appropriate timeframe
active_tf = self._select_active_timeframe(volatility)
# Generate signal on selected timeframe
return self._generate_signal_for_timeframe(active_tf, df_index)
```
## Configuration Examples
### Single Timeframe Configuration
```json
{
"strategies": [
{
"name": "default",
"weight": 1.0,
"params": {
"timeframe": "15min",
"stop_loss_pct": 0.03
}
}
]
}
```
### Multi-Timeframe Configuration
```json
{
"strategies": [
{
"name": "multi_timeframe_strategy",
"weight": 1.0,
"params": {
"primary_timeframe": "15min",
"confirmation_timeframes": ["1h", "4h"],
"signal_timeframe": "5min"
}
}
]
}
```
### Mixed Strategy Configuration
```json
{
"strategies": [
{
"name": "default",
"weight": 0.6,
"params": {
"timeframe": "15min"
}
},
{
"name": "bbrs",
"weight": 0.4,
"params": {
"strategy_name": "MarketRegimeStrategy"
}
}
]
}
```
## Performance Considerations
### Memory Usage
- Only required timeframes are resampled and stored
- Original 1-minute data shared across all strategies
- Efficient pandas resampling with minimal memory overhead
### Processing Speed
- Resampling happens once during initialization
- No repeated resampling during backtesting
- Vectorized operations on pre-computed timeframes
### Data Alignment
- All timeframes aligned to original 1-minute timestamps
- Forward-fill resampling ensures data availability
- Intelligent handling of missing data points
## Best Practices
### 1. Minimize Timeframe Requirements
```python
# Good - minimal timeframes
def get_timeframes(self):
return ["15min"]
# Less optimal - unnecessary timeframes
def get_timeframes(self):
return ["1min", "5min", "15min", "1h", "4h", "1d"]
```
### 2. Use Appropriate Timeframes for Strategy Logic
```python
# Good - timeframe matches strategy logic
class TrendStrategy(StrategyBase):
def get_timeframes(self):
return ["1h"] # Trend analysis works well on hourly data
class ScalpingStrategy(StrategyBase):
def get_timeframes(self):
return ["1min", "5min"] # Scalping needs fine-grained data
```
### 3. Include 1min for Stop-Loss Precision
```python
def get_timeframes(self):
primary_tf = self.params.get("timeframe", "15min")
timeframes = [primary_tf]
# Always include 1min for precise stop-loss
if "1min" not in timeframes:
timeframes.append("1min")
return timeframes
```
### 4. Handle Timeframe Edge Cases
```python
def get_entry_signal(self, backtester, df_index):
# Check bounds for all timeframes
if df_index >= len(self.get_primary_timeframe_data()):
return StrategySignal("HOLD", confidence=0.0)
# Robust timeframe indexing
try:
signal = self._calculate_signal(df_index)
return signal
except IndexError:
return StrategySignal("HOLD", confidence=0.0)
```
## Troubleshooting
### Common Issues
1. **Index Out of Bounds**
```python
# Problem: Different timeframes have different lengths
# Solution: Always check bounds
if df_index < len(self.data_1h):
signal = self.data_1h[df_index]
```
2. **Timeframe Misalignment**
```python
# Problem: Assuming same index across timeframes
# Solution: Use timestamp-based alignment
current_time = primary_data.index[df_index]
h1_idx = hourly_data.index.get_indexer([current_time], method='ffill')[0]
```
3. **Memory Issues with Large Datasets**
```python
# Solution: Only include necessary timeframes
def get_timeframes(self):
# Return minimal set
return ["15min"] # Not ["1min", "5min", "15min", "1h"]
```
### Debugging Tips
```python
# Log timeframe information
def initialize(self, backtester):
self._resample_data(backtester.original_df)
for tf in self.get_timeframes():
data = self.get_data_for_timeframe(tf)
print(f"Timeframe {tf}: {len(data)} bars, "
f"from {data.index[0]} to {data.index[-1]}")
self.initialized = True
```
## Future Enhancements
### Planned Features
1. **Dynamic Timeframe Switching**: Strategies adapt timeframes based on market conditions
2. **Timeframe Confidence Weighting**: Different confidence levels per timeframe
3. **Cross-Timeframe Signal Validation**: Automatic signal confirmation across timeframes
4. **Optimized Memory Management**: Lazy loading and caching for large datasets
### Extension Points
The timeframe system is designed for easy extension:
- Custom resampling methods
- Alternative timeframe synchronization strategies
- Market-specific timeframe preferences
- Real-time timeframe adaptation

73
docs/utils_storage.md
View File

@@ -1,73 +0,0 @@
# Storage Utilities
This document describes the storage utility functions found in `cycles/utils/storage.py`.
## Overview
The `storage.py` module provides a `Storage` class designed for handling the loading and saving of data and results. It supports operations with CSV and JSON files and integrates with pandas DataFrames for data manipulation. The class also manages the creation of necessary `results` and `data` directories.
## Constants
- `RESULTS_DIR`: Defines the default directory name for storing results (default: "results").
- `DATA_DIR`: Defines the default directory name for storing input data (default: "data").
## Class: `Storage`
Handles storage operations for data and results.
### `__init__(self, logging=None, results_dir=RESULTS_DIR, data_dir=DATA_DIR)`
- **Description**: Initializes the `Storage` class. It creates the results and data directories if they don't already exist.
- **Parameters**:
- `logging` (optional): A logging instance for outputting information. Defaults to `None`.
- `results_dir` (str, optional): Path to the directory for storing results. Defaults to `RESULTS_DIR`.
- `data_dir` (str, optional): Path to the directory for storing data. Defaults to `DATA_DIR`.
### `load_data(self, file_path, start_date, stop_date)`
- **Description**: Loads data from a specified file (CSV or JSON), performs type optimization, filters by date range, and converts column names to lowercase. The timestamp column is set as the DataFrame index.
- **Parameters**:
- `file_path` (str): Path to the data file (relative to `data_dir`).
- `start_date` (datetime-like): The start date for filtering data.
- `stop_date` (datetime-like): The end date for filtering data.
- **Returns**: `pandas.DataFrame` - The loaded and processed data, with a `timestamp` index. Returns an empty DataFrame on error.
### `save_data(self, data: pd.DataFrame, file_path: str)`
- **Description**: Saves a pandas DataFrame to a CSV file within the `data_dir`. If the DataFrame has a DatetimeIndex, it's converted to a Unix timestamp (seconds since epoch) and stored in a column named 'timestamp', which becomes the first column in the CSV. The DataFrame's active index is not saved if a 'timestamp' column is created.
- **Parameters**:
- `data` (pd.DataFrame): The DataFrame to save.
- `file_path` (str): Path to the data file (relative to `data_dir`).
### `format_row(self, row)`
- **Description**: Formats a dictionary row for output to a combined results CSV file, applying specific string formatting for percentages and float values.
- **Parameters**:
- `row` (dict): The row of data to format.
- **Returns**: `dict` - The formatted row.
### `write_results_chunk(self, filename, fieldnames, rows, write_header=False, initial_usd=None)`
- **Description**: Writes a chunk of results (list of dictionaries) to a CSV file. Can append to an existing file or write a new one with a header. An optional `initial_usd` can be written as a comment in the header.
- **Parameters**:
- `filename` (str): The name of the file to write to (path is absolute or relative to current working dir).
- `fieldnames` (list): A list of strings representing the CSV header/column names.
- `rows` (list): A list of dictionaries, where each dictionary is a row.
- `write_header` (bool, optional): If `True`, writes the header. Defaults to `False`.
- `initial_usd` (numeric, optional): If provided and `write_header` is `True`, this value is written as a comment in the CSV header. Defaults to `None`.
### `write_results_combined(self, filename, fieldnames, rows)`
- **Description**: Writes combined results to a CSV file in the `results_dir`. Uses tab as a delimiter and formats rows using `format_row`.
- **Parameters**:
- `filename` (str): The name of the file to write to (relative to `results_dir`).
- `fieldnames` (list): A list of strings representing the CSV header/column names.
- `rows` (list): A list of dictionaries, where each dictionary is a row.
### `write_trades(self, all_trade_rows, trades_fieldnames)`
- **Description**: Writes trade data to separate CSV files based on timeframe and stop-loss percentage. Files are named `trades_{tf}_ST{sl_percent}pct.csv` and stored in `results_dir`.
- **Parameters**:
- `all_trade_rows` (list): A list of dictionaries, where each dictionary represents a trade.
- `trades_fieldnames` (list): A list of strings for the CSV header of trade files.

49
docs/utils_system.md
View File

@@ -1,49 +0,0 @@
# System Utilities
This document describes the system utility functions found in `cycles/utils/system.py`.
## Overview
The `system.py` module provides utility functions related to system information and resource management. It currently includes a class `SystemUtils` for determining optimal configurations based on system resources.
## Classes and Methods
### `SystemUtils`
A class to provide system-related utility methods.
#### `__init__(self, logging=None)`
- **Description**: Initializes the `SystemUtils` class.
- **Parameters**:
- `logging` (optional): A logging instance to output information. Defaults to `None`.
#### `get_optimal_workers(self)`
- **Description**: Determines the optimal number of worker processes based on available CPU cores and memory.
The heuristic aims to use 75% of CPU cores, with a cap based on available memory (assuming each worker might need ~2GB for large datasets). It returns the minimum of the workers calculated by CPU and memory.
- **Parameters**: None.
- **Returns**: `int` - The recommended number of worker processes.
## Usage Examples
```python
from cycles.utils.system import SystemUtils
# Initialize (optionally with a logger)
# import logging
# logging.basicConfig(level=logging.INFO)
# logger = logging.getLogger(__name__)
# sys_utils = SystemUtils(logging=logger)
sys_utils = SystemUtils()
optimal_workers = sys_utils.get_optimal_workers()
print(f"Optimal number of workers: {optimal_workers}")
# This value can then be used, for example, when setting up a ThreadPoolExecutor
# from concurrent.futures import ThreadPoolExecutor
# with ThreadPoolExecutor(max_workers=optimal_workers) as executor:
# # ... submit tasks ...
# pass
```