3.4 - 3.0 Strategy Configuration System
Implement comprehensive chart configuration and validation system - Introduced a modular chart configuration system in `components/charts/config/` to manage indicator definitions, default configurations, and strategy-specific setups. - Added new modules for error handling and validation, enhancing user guidance and error reporting capabilities. - Implemented detailed schema validation for indicators and strategies, ensuring robust configuration management. - Created example strategies and default configurations to facilitate user onboarding and usage. - Enhanced documentation to provide clear guidelines on the configuration system, validation rules, and usage examples. - Added unit tests for all new components to ensure functionality and reliability across the configuration system.
This commit is contained in:
Vasily.onl
580
docs/components/charts/README.md
Normal file
580
docs/components/charts/README.md
Normal file
@@ -0,0 +1,580 @@
|
||||
# Modular Chart Layers System
|
||||
|
||||
The Modular Chart Layers System is a flexible, strategy-driven chart system that supports technical indicator overlays, subplot management, and future bot signal integration. This system replaces basic chart functionality with a modular architecture that adapts to different trading strategies and their specific indicator requirements.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Architecture](#architecture)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Components](#components)
|
||||
- [Configuration System](#configuration-system)
|
||||
- [Example Strategies](#example-strategies)
|
||||
- [Validation System](#validation-system)
|
||||
- [API Reference](#api-reference)
|
||||
- [Examples](#examples)
|
||||
- [Best Practices](#best-practices)
|
||||
|
||||
## Overview
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Modular Architecture**: Chart layers can be independently tested and composed
|
||||
- **Strategy-Driven Configuration**: JSON-based configurations for different trading strategies
|
||||
- **Comprehensive Validation**: 10+ validation rules with detailed error reporting
|
||||
- **Example Strategies**: 5 real-world trading strategy templates
|
||||
- **Indicator Support**: 26+ professionally configured indicator presets
|
||||
- **Extensible Design**: Easy to add new indicators, strategies, and chart types
|
||||
|
||||
### Supported Indicators
|
||||
|
||||
**Trend Indicators:**
|
||||
- Simple Moving Average (SMA) - Multiple periods
|
||||
- Exponential Moving Average (EMA) - Multiple periods
|
||||
- Bollinger Bands - Various configurations
|
||||
|
||||
**Momentum Indicators:**
|
||||
- Relative Strength Index (RSI) - Multiple periods
|
||||
- MACD - Various speed configurations
|
||||
|
||||
**Volume Indicators:**
|
||||
- Volume analysis and confirmation
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
components/charts/
|
||||
├── config/ # Configuration management
|
||||
│ ├── indicator_defs.py # Indicator schemas and validation
|
||||
│ ├── defaults.py # Default configurations and presets
|
||||
│ ├── strategy_charts.py # Strategy-specific configurations
|
||||
│ ├── validation.py # Validation system
|
||||
│ ├── example_strategies.py # Real-world strategy examples
|
||||
│ └── __init__.py # Package exports
|
||||
├── layers/ # Chart layer implementation
|
||||
│ ├── base.py # Base layer system
|
||||
│ ├── indicators.py # Indicator overlays
|
||||
│ ├── subplots.py # Subplot management
|
||||
│ └── signals.py # Signal overlays (future)
|
||||
├── builder.py # Main chart builder
|
||||
└── utils.py # Chart utilities
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
create_ema_crossover_strategy,
|
||||
get_strategy_config,
|
||||
validate_configuration
|
||||
)
|
||||
|
||||
# Get a pre-built strategy
|
||||
strategy = create_ema_crossover_strategy()
|
||||
config = strategy.config
|
||||
|
||||
# Validate the configuration
|
||||
report = validate_configuration(config)
|
||||
if report.is_valid:
|
||||
print("Configuration is valid!")
|
||||
else:
|
||||
print(f"Errors: {[str(e) for e in report.errors]}")
|
||||
|
||||
# Use with dashboard
|
||||
# chart = create_chart(config, market_data)
|
||||
```
|
||||
|
||||
### Custom Strategy Creation
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
StrategyChartConfig,
|
||||
SubplotConfig,
|
||||
ChartStyle,
|
||||
TradingStrategy,
|
||||
SubplotType
|
||||
)
|
||||
|
||||
# Create custom strategy
|
||||
config = StrategyChartConfig(
|
||||
strategy_name="My Custom Strategy",
|
||||
strategy_type=TradingStrategy.DAY_TRADING,
|
||||
description="Custom day trading strategy",
|
||||
timeframes=["15m", "1h"],
|
||||
overlay_indicators=["ema_12", "ema_26", "bb_20_20"],
|
||||
subplot_configs=[
|
||||
SubplotConfig(
|
||||
subplot_type=SubplotType.RSI,
|
||||
height_ratio=0.2,
|
||||
indicators=["rsi_14"]
|
||||
)
|
||||
]
|
||||
)
|
||||
|
||||
# Validate and use
|
||||
is_valid, errors = config.validate()
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### 1. Configuration System
|
||||
|
||||
The configuration system provides schema validation, default presets, and strategy management.
|
||||
|
||||
**Key Files:**
|
||||
- `indicator_defs.py` - Core schemas and validation
|
||||
- `defaults.py` - 26+ indicator presets organized by category
|
||||
- `strategy_charts.py` - Complete strategy configurations
|
||||
|
||||
**Features:**
|
||||
- Type-safe indicator definitions
|
||||
- Parameter validation with ranges
|
||||
- Category-based organization (trend, momentum, volatility)
|
||||
- Strategy-specific recommendations
|
||||
|
||||
### 2. Validation System
|
||||
|
||||
Comprehensive validation with 10 validation rules:
|
||||
|
||||
1. **Required Fields** - Essential configuration validation
|
||||
2. **Height Ratios** - Chart layout validation
|
||||
3. **Indicator Existence** - Indicator availability check
|
||||
4. **Timeframe Format** - Valid timeframe patterns
|
||||
5. **Chart Style** - Color and styling validation
|
||||
6. **Subplot Config** - Subplot compatibility check
|
||||
7. **Strategy Consistency** - Strategy-timeframe alignment
|
||||
8. **Performance Impact** - Resource usage warnings
|
||||
9. **Indicator Conflicts** - Redundancy detection
|
||||
10. **Resource Usage** - Memory and rendering estimates
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
from components.charts.config import validate_configuration
|
||||
|
||||
report = validate_configuration(config)
|
||||
print(f"Valid: {report.is_valid}")
|
||||
print(f"Errors: {len(report.errors)}")
|
||||
print(f"Warnings: {len(report.warnings)}")
|
||||
```
|
||||
|
||||
### 3. Example Strategies
|
||||
|
||||
Five professionally configured trading strategies:
|
||||
|
||||
1. **EMA Crossover** (Intermediate, Medium Risk)
|
||||
- Classic trend-following with EMA crossovers
|
||||
- Best for trending markets, 15m-4h timeframes
|
||||
|
||||
2. **Momentum Breakout** (Advanced, High Risk)
|
||||
- Fast indicators for momentum capture
|
||||
- Volume confirmation, best for volatile markets
|
||||
|
||||
3. **Mean Reversion** (Intermediate, Medium Risk)
|
||||
- Oversold/overbought conditions
|
||||
- Multiple RSI periods, best for ranging markets
|
||||
|
||||
4. **Scalping** (Advanced, High Risk)
|
||||
- Ultra-fast indicators for 1m-5m trading
|
||||
- Tight risk management, high frequency
|
||||
|
||||
5. **Swing Trading** (Beginner, Medium Risk)
|
||||
- Medium-term trend following
|
||||
- 4h-1d timeframes, suitable for part-time traders
|
||||
|
||||
## Configuration System
|
||||
|
||||
### Indicator Definitions
|
||||
|
||||
Each indicator has a complete schema definition:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChartIndicatorConfig:
|
||||
indicator_type: IndicatorType
|
||||
parameters: Dict[str, Any]
|
||||
display_name: str
|
||||
color: str
|
||||
line_style: LineStyle
|
||||
line_width: int
|
||||
display_type: DisplayType
|
||||
```
|
||||
|
||||
### Strategy Configuration
|
||||
|
||||
Complete strategy definitions include:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class StrategyChartConfig:
|
||||
strategy_name: str
|
||||
strategy_type: TradingStrategy
|
||||
description: str
|
||||
timeframes: List[str]
|
||||
layout: ChartLayout
|
||||
main_chart_height: float
|
||||
overlay_indicators: List[str]
|
||||
subplot_configs: List[SubplotConfig]
|
||||
chart_style: ChartStyle
|
||||
```
|
||||
|
||||
### Default Configurations
|
||||
|
||||
26+ indicator presets organized by category:
|
||||
|
||||
- **Trend Indicators**: 13 SMA/EMA presets
|
||||
- **Momentum Indicators**: 9 RSI/MACD presets
|
||||
- **Volatility Indicators**: 4 Bollinger Bands configurations
|
||||
|
||||
Access via:
|
||||
```python
|
||||
from components.charts.config import get_all_default_indicators
|
||||
|
||||
indicators = get_all_default_indicators()
|
||||
trend_indicators = get_indicators_by_category(IndicatorCategory.TREND)
|
||||
```
|
||||
|
||||
## Example Strategies
|
||||
|
||||
### EMA Crossover Strategy
|
||||
|
||||
```python
|
||||
from components.charts.config import create_ema_crossover_strategy
|
||||
|
||||
strategy = create_ema_crossover_strategy()
|
||||
config = strategy.config
|
||||
|
||||
# Strategy includes:
|
||||
# - EMA 12, 26, 50 for trend analysis
|
||||
# - RSI 14 for momentum confirmation
|
||||
# - MACD for signal confirmation
|
||||
# - Bollinger Bands for volatility context
|
||||
```
|
||||
|
||||
### Custom Strategy Creation
|
||||
|
||||
```python
|
||||
from components.charts.config import create_custom_strategy_config
|
||||
|
||||
config, errors = create_custom_strategy_config(
|
||||
strategy_name="My Strategy",
|
||||
strategy_type=TradingStrategy.MOMENTUM,
|
||||
description="Custom momentum strategy",
|
||||
timeframes=["5m", "15m"],
|
||||
overlay_indicators=["ema_8", "ema_21"],
|
||||
subplot_configs=[{
|
||||
"subplot_type": "rsi",
|
||||
"height_ratio": 0.2,
|
||||
"indicators": ["rsi_7"]
|
||||
}]
|
||||
)
|
||||
```
|
||||
|
||||
## Validation System
|
||||
|
||||
### Comprehensive Validation
|
||||
|
||||
```python
|
||||
from components.charts.config import validate_configuration
|
||||
|
||||
# Full validation with detailed reporting
|
||||
report = validate_configuration(config)
|
||||
|
||||
# Check results
|
||||
if report.is_valid:
|
||||
print("✅ Configuration is valid")
|
||||
else:
|
||||
print("❌ Configuration has errors:")
|
||||
for error in report.errors:
|
||||
print(f" • {error}")
|
||||
|
||||
# Check warnings
|
||||
if report.warnings:
|
||||
print("⚠️ Warnings:")
|
||||
for warning in report.warnings:
|
||||
print(f" • {warning}")
|
||||
```
|
||||
|
||||
### Validation Rules Information
|
||||
|
||||
```python
|
||||
from components.charts.config import get_validation_rules_info
|
||||
|
||||
rules = get_validation_rules_info()
|
||||
for rule, info in rules.items():
|
||||
print(f"{info['name']}: {info['description']}")
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Core Classes
|
||||
|
||||
#### `StrategyChartConfig`
|
||||
Main configuration class for chart strategies.
|
||||
|
||||
**Methods:**
|
||||
- `validate()` → `tuple[bool, List[str]]` - Basic validation
|
||||
- `validate_comprehensive()` → `ValidationReport` - Detailed validation
|
||||
- `get_all_indicators()` → `List[str]` - Get all indicator names
|
||||
- `get_indicator_configs()` → `Dict[str, ChartIndicatorConfig]` - Get configurations
|
||||
|
||||
#### `StrategyExample`
|
||||
Container for example strategies with metadata.
|
||||
|
||||
**Properties:**
|
||||
- `config: StrategyChartConfig` - The strategy configuration
|
||||
- `description: str` - Detailed strategy description
|
||||
- `difficulty: str` - Beginner/Intermediate/Advanced
|
||||
- `risk_level: str` - Low/Medium/High
|
||||
- `market_conditions: List[str]` - Suitable market conditions
|
||||
|
||||
### Utility Functions
|
||||
|
||||
#### Configuration Access
|
||||
```python
|
||||
# Get all example strategies
|
||||
get_all_example_strategies() → Dict[str, StrategyExample]
|
||||
|
||||
# Filter by criteria
|
||||
get_strategies_by_difficulty("Intermediate") → List[StrategyExample]
|
||||
get_strategies_by_risk_level("Medium") → List[StrategyExample]
|
||||
get_strategies_by_market_condition("Trending") → List[StrategyExample]
|
||||
|
||||
# Get strategy summary
|
||||
get_strategy_summary() → Dict[str, Dict[str, str]]
|
||||
```
|
||||
|
||||
#### JSON Export/Import
|
||||
```python
|
||||
# Export to JSON
|
||||
export_strategy_config_to_json(config) → str
|
||||
export_example_strategies_to_json() → str
|
||||
|
||||
# Import from JSON
|
||||
load_strategy_config_from_json(json_data) → tuple[StrategyChartConfig, List[str]]
|
||||
```
|
||||
|
||||
#### Validation
|
||||
```python
|
||||
# Comprehensive validation
|
||||
validate_configuration(config, rules=None, strict=False) → ValidationReport
|
||||
|
||||
# Get validation rules info
|
||||
get_validation_rules_info() → Dict[ValidationRule, Dict[str, str]]
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Using Pre-built Strategy
|
||||
|
||||
```python
|
||||
from components.charts.config import get_example_strategy
|
||||
|
||||
# Get a specific strategy
|
||||
strategy = get_example_strategy("ema_crossover")
|
||||
|
||||
print(f"Strategy: {strategy.config.strategy_name}")
|
||||
print(f"Difficulty: {strategy.difficulty}")
|
||||
print(f"Risk Level: {strategy.risk_level}")
|
||||
print(f"Timeframes: {strategy.config.timeframes}")
|
||||
print(f"Indicators: {strategy.config.overlay_indicators}")
|
||||
|
||||
# Validate before use
|
||||
is_valid, errors = strategy.config.validate()
|
||||
if is_valid:
|
||||
# Use in dashboard
|
||||
pass
|
||||
```
|
||||
|
||||
### Example 2: Creating Custom Configuration
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
StrategyChartConfig, SubplotConfig, ChartStyle,
|
||||
TradingStrategy, SubplotType, ChartLayout
|
||||
)
|
||||
|
||||
# Create custom configuration
|
||||
config = StrategyChartConfig(
|
||||
strategy_name="Custom Momentum Strategy",
|
||||
strategy_type=TradingStrategy.MOMENTUM,
|
||||
description="Fast momentum strategy with volume confirmation",
|
||||
timeframes=["5m", "15m"],
|
||||
layout=ChartLayout.MAIN_WITH_SUBPLOTS,
|
||||
main_chart_height=0.65,
|
||||
overlay_indicators=["ema_8", "ema_21", "bb_20_25"],
|
||||
subplot_configs=[
|
||||
SubplotConfig(
|
||||
subplot_type=SubplotType.RSI,
|
||||
height_ratio=0.15,
|
||||
indicators=["rsi_7"],
|
||||
title="Fast RSI"
|
||||
),
|
||||
SubplotConfig(
|
||||
subplot_type=SubplotType.VOLUME,
|
||||
height_ratio=0.2,
|
||||
indicators=[],
|
||||
title="Volume Confirmation"
|
||||
)
|
||||
],
|
||||
chart_style=ChartStyle(
|
||||
theme="plotly_white",
|
||||
candlestick_up_color="#00d4aa",
|
||||
candlestick_down_color="#fe6a85"
|
||||
)
|
||||
)
|
||||
|
||||
# Comprehensive validation
|
||||
report = config.validate_comprehensive()
|
||||
print(f"Validation: {report.summary()}")
|
||||
```
|
||||
|
||||
### Example 3: Filtering Strategies
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
get_strategies_by_difficulty,
|
||||
get_strategies_by_market_condition
|
||||
)
|
||||
|
||||
# Get beginner-friendly strategies
|
||||
beginner_strategies = get_strategies_by_difficulty("Beginner")
|
||||
print("Beginner Strategies:")
|
||||
for strategy in beginner_strategies:
|
||||
print(f" • {strategy.config.strategy_name}")
|
||||
|
||||
# Get strategies for trending markets
|
||||
trending_strategies = get_strategies_by_market_condition("Trending")
|
||||
print("\nTrending Market Strategies:")
|
||||
for strategy in trending_strategies:
|
||||
print(f" • {strategy.config.strategy_name}")
|
||||
```
|
||||
|
||||
### Example 4: Validation with Error Handling
|
||||
|
||||
```python
|
||||
from components.charts.config import validate_configuration, ValidationLevel
|
||||
|
||||
# Validate with comprehensive reporting
|
||||
report = validate_configuration(config)
|
||||
|
||||
# Handle different severity levels
|
||||
if report.errors:
|
||||
print("🚨 ERRORS (must fix):")
|
||||
for error in report.errors:
|
||||
print(f" • {error}")
|
||||
|
||||
if report.warnings:
|
||||
print("\n⚠️ WARNINGS (recommended fixes):")
|
||||
for warning in report.warnings:
|
||||
print(f" • {warning}")
|
||||
|
||||
if report.info:
|
||||
print("\nℹ️ INFO (optimization suggestions):")
|
||||
for info in report.info:
|
||||
print(f" • {info}")
|
||||
|
||||
# Check specific validation rules
|
||||
height_issues = report.get_issues_by_rule(ValidationRule.HEIGHT_RATIOS)
|
||||
if height_issues:
|
||||
print(f"\nHeight ratio issues: {len(height_issues)}")
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Configuration Design
|
||||
|
||||
- **Use meaningful names**: Strategy names should be descriptive
|
||||
- **Validate early**: Always validate configurations before use
|
||||
- **Consider timeframes**: Match timeframes to strategy type
|
||||
- **Height ratios**: Ensure total height ≤ 1.0
|
||||
|
||||
### 2. Indicator Selection
|
||||
|
||||
- **Avoid redundancy**: Don't use multiple similar indicators
|
||||
- **Performance impact**: Limit complex indicators (>3 Bollinger Bands)
|
||||
- **Category balance**: Mix trend, momentum, and volume indicators
|
||||
- **Timeframe alignment**: Use appropriate indicator periods
|
||||
|
||||
### 3. Strategy Development
|
||||
|
||||
- **Start simple**: Begin with proven strategies like EMA crossover
|
||||
- **Test thoroughly**: Validate both technically and with market data
|
||||
- **Document well**: Include entry/exit rules and market conditions
|
||||
- **Consider risk**: Match complexity to experience level
|
||||
|
||||
### 4. Validation Usage
|
||||
|
||||
- **Use comprehensive validation**: Get detailed reports with suggestions
|
||||
- **Handle warnings**: Address performance and usability warnings
|
||||
- **Test edge cases**: Validate with extreme configurations
|
||||
- **Monitor updates**: Re-validate when changing configurations
|
||||
|
||||
### 5. Performance Optimization
|
||||
|
||||
- **Limit indicators**: Keep total indicators <10 for performance
|
||||
- **Monitor memory**: Check resource usage warnings
|
||||
- **Optimize rendering**: Consider visual complexity
|
||||
- **Cache configurations**: Reuse validated configurations
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
1. **"Indicator not found in defaults"**
|
||||
```python
|
||||
# Check available indicators
|
||||
from components.charts.config import get_all_default_indicators
|
||||
available = get_all_default_indicators()
|
||||
print(list(available.keys()))
|
||||
```
|
||||
|
||||
2. **"Total height exceeds 1.0"**
|
||||
```python
|
||||
# Adjust height ratios
|
||||
config.main_chart_height = 0.7
|
||||
for subplot in config.subplot_configs:
|
||||
subplot.height_ratio = 0.1
|
||||
```
|
||||
|
||||
3. **"Invalid timeframe format"**
|
||||
```python
|
||||
# Use standard formats
|
||||
config.timeframes = ["1m", "5m", "15m", "1h", "4h", "1d", "1w"]
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
The system includes comprehensive tests:
|
||||
|
||||
- **112+ test cases** across all components
|
||||
- **Unit tests** for individual components
|
||||
- **Integration tests** for system interactions
|
||||
- **Validation tests** for error handling
|
||||
|
||||
Run tests:
|
||||
```bash
|
||||
uv run pytest tests/test_*_strategies.py -v
|
||||
uv run pytest tests/test_validation.py -v
|
||||
uv run pytest tests/test_defaults.py -v
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- **Signal Layer Integration**: Bot trade signals and alerts
|
||||
- **Custom Indicators**: User-defined technical indicators
|
||||
- **Advanced Layouts**: Multi-chart and grid layouts
|
||||
- **Real-time Updates**: Live chart updates with indicator toggling
|
||||
- **Performance Monitoring**: Advanced resource usage tracking
|
||||
|
||||
## Support
|
||||
|
||||
For issues, questions, or contributions:
|
||||
|
||||
1. Check existing configurations in `example_strategies.py`
|
||||
2. Review validation rules in `validation.py`
|
||||
3. Test with comprehensive validation
|
||||
4. Refer to this documentation
|
||||
|
||||
The modular chart system is designed to be extensible and maintainable, providing a solid foundation for advanced trading chart functionality.
|
||||
752
docs/components/charts/configuration.md
Normal file
752
docs/components/charts/configuration.md
Normal file
@@ -0,0 +1,752 @@
|
||||
# Chart Configuration System
|
||||
|
||||
The Chart Configuration System provides comprehensive management of chart settings, indicator definitions, and trading strategy configurations. It includes schema validation, default presets, and extensible configuration patterns.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Indicator Definitions](#indicator-definitions)
|
||||
- [Default Configurations](#default-configurations)
|
||||
- [Strategy Configurations](#strategy-configurations)
|
||||
- [Validation System](#validation-system)
|
||||
- [Configuration Files](#configuration-files)
|
||||
- [Usage Examples](#usage-examples)
|
||||
- [Extension Guide](#extension-guide)
|
||||
|
||||
## Overview
|
||||
|
||||
The configuration system is built around three core concepts:
|
||||
|
||||
1. **Indicator Definitions** - Schema and validation for technical indicators
|
||||
2. **Default Configurations** - Pre-built indicator presets organized by category
|
||||
3. **Strategy Configurations** - Complete chart setups for trading strategies
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
components/charts/config/
|
||||
├── indicator_defs.py # Core schemas and validation
|
||||
├── defaults.py # Default indicator presets
|
||||
├── strategy_charts.py # Strategy configurations
|
||||
├── validation.py # Validation system
|
||||
├── example_strategies.py # Real-world examples
|
||||
└── __init__.py # Package exports
|
||||
```
|
||||
|
||||
## Indicator Definitions
|
||||
|
||||
### Core Classes
|
||||
|
||||
#### `ChartIndicatorConfig`
|
||||
|
||||
The main configuration class for individual indicators:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChartIndicatorConfig:
|
||||
indicator_type: IndicatorType
|
||||
parameters: Dict[str, Any]
|
||||
display_name: str
|
||||
color: str
|
||||
line_style: LineStyle = LineStyle.SOLID
|
||||
line_width: int = 2
|
||||
display_type: DisplayType = DisplayType.OVERLAY
|
||||
opacity: float = 1.0
|
||||
show_legend: bool = True
|
||||
```
|
||||
|
||||
#### Enums
|
||||
|
||||
**IndicatorType**
|
||||
```python
|
||||
class IndicatorType(str, Enum):
|
||||
SMA = "sma"
|
||||
EMA = "ema"
|
||||
RSI = "rsi"
|
||||
MACD = "macd"
|
||||
BOLLINGER_BANDS = "bollinger_bands"
|
||||
VOLUME = "volume"
|
||||
```
|
||||
|
||||
**DisplayType**
|
||||
```python
|
||||
class DisplayType(str, Enum):
|
||||
OVERLAY = "overlay" # Overlaid on price chart
|
||||
SUBPLOT = "subplot" # Separate subplot
|
||||
HISTOGRAM = "histogram" # Histogram display
|
||||
```
|
||||
|
||||
**LineStyle**
|
||||
```python
|
||||
class LineStyle(str, Enum):
|
||||
SOLID = "solid"
|
||||
DASHED = "dash"
|
||||
DOTTED = "dot"
|
||||
DASH_DOT = "dashdot"
|
||||
```
|
||||
|
||||
### Schema Validation
|
||||
|
||||
#### `IndicatorParameterSchema`
|
||||
|
||||
Defines validation rules for indicator parameters:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class IndicatorParameterSchema:
|
||||
name: str
|
||||
type: type
|
||||
required: bool = True
|
||||
min_value: Optional[Union[int, float]] = None
|
||||
max_value: Optional[Union[int, float]] = None
|
||||
default_value: Any = None
|
||||
description: str = ""
|
||||
valid_values: Optional[List[Any]] = None
|
||||
```
|
||||
|
||||
#### `IndicatorSchema`
|
||||
|
||||
Complete schema for an indicator type:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class IndicatorSchema:
|
||||
indicator_type: IndicatorType
|
||||
display_type: DisplayType
|
||||
parameters: List[IndicatorParameterSchema]
|
||||
description: str
|
||||
calculation_description: str
|
||||
usage_notes: List[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
### Schema Definitions
|
||||
|
||||
The system includes complete schemas for all supported indicators:
|
||||
|
||||
```python
|
||||
INDICATOR_SCHEMAS = {
|
||||
IndicatorType.SMA: IndicatorSchema(
|
||||
indicator_type=IndicatorType.SMA,
|
||||
display_type=DisplayType.OVERLAY,
|
||||
parameters=[
|
||||
IndicatorParameterSchema(
|
||||
name="period",
|
||||
type=int,
|
||||
min_value=1,
|
||||
max_value=200,
|
||||
default_value=20,
|
||||
description="Number of periods for the moving average"
|
||||
),
|
||||
IndicatorParameterSchema(
|
||||
name="price_column",
|
||||
type=str,
|
||||
required=False,
|
||||
default_value="close",
|
||||
valid_values=["open", "high", "low", "close"],
|
||||
description="Price column to use for calculation"
|
||||
)
|
||||
],
|
||||
description="Simple Moving Average - arithmetic mean of prices",
|
||||
calculation_description="Sum of closing prices divided by period"
|
||||
),
|
||||
# ... more schemas
|
||||
}
|
||||
```
|
||||
|
||||
### Utility Functions
|
||||
|
||||
#### Validation Functions
|
||||
|
||||
```python
|
||||
# Validate individual indicator configuration
|
||||
def validate_indicator_configuration(config: ChartIndicatorConfig) -> tuple[bool, List[str]]
|
||||
|
||||
# Create indicator configuration with validation
|
||||
def create_indicator_config(
|
||||
indicator_type: IndicatorType,
|
||||
parameters: Dict[str, Any],
|
||||
**kwargs
|
||||
) -> tuple[Optional[ChartIndicatorConfig], List[str]]
|
||||
|
||||
# Get schema for indicator type
|
||||
def get_indicator_schema(indicator_type: IndicatorType) -> Optional[IndicatorSchema]
|
||||
|
||||
# Get available indicator types
|
||||
def get_available_indicator_types() -> List[IndicatorType]
|
||||
|
||||
# Validate parameters for specific type
|
||||
def validate_parameters_for_type(
|
||||
indicator_type: IndicatorType,
|
||||
parameters: Dict[str, Any]
|
||||
) -> tuple[bool, List[str]]
|
||||
```
|
||||
|
||||
## Default Configurations
|
||||
|
||||
### Organization
|
||||
|
||||
Default configurations are organized by category and trading strategy:
|
||||
|
||||
#### Categories
|
||||
|
||||
```python
|
||||
class IndicatorCategory(str, Enum):
|
||||
TREND = "trend"
|
||||
MOMENTUM = "momentum"
|
||||
VOLATILITY = "volatility"
|
||||
VOLUME = "volume"
|
||||
SUPPORT_RESISTANCE = "support_resistance"
|
||||
```
|
||||
|
||||
#### Trading Strategies
|
||||
|
||||
```python
|
||||
class TradingStrategy(str, Enum):
|
||||
SCALPING = "scalping"
|
||||
DAY_TRADING = "day_trading"
|
||||
SWING_TRADING = "swing_trading"
|
||||
POSITION_TRADING = "position_trading"
|
||||
MOMENTUM = "momentum"
|
||||
MEAN_REVERSION = "mean_reversion"
|
||||
```
|
||||
|
||||
### Indicator Presets
|
||||
|
||||
#### `IndicatorPreset`
|
||||
|
||||
Container for pre-configured indicators:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class IndicatorPreset:
|
||||
name: str
|
||||
config: ChartIndicatorConfig
|
||||
category: IndicatorCategory
|
||||
description: str
|
||||
recommended_timeframes: List[str]
|
||||
suitable_strategies: List[TradingStrategy]
|
||||
notes: List[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
### Available Presets
|
||||
|
||||
**Trend Indicators (13 presets)**
|
||||
- `sma_5`, `sma_10`, `sma_20`, `sma_50`, `sma_100`, `sma_200`
|
||||
- `ema_5`, `ema_12`, `ema_21`, `ema_26`, `ema_50`, `ema_100`, `ema_200`
|
||||
|
||||
**Momentum Indicators (9 presets)**
|
||||
- `rsi_7`, `rsi_14`, `rsi_21`
|
||||
- `macd_5_13_4`, `macd_8_17_6`, `macd_12_26_9`, `macd_19_39_13`
|
||||
|
||||
**Volatility Indicators (4 presets)**
|
||||
- `bb_10_15`, `bb_20_15`, `bb_20_20`, `bb_50_20`
|
||||
|
||||
### Color Schemes
|
||||
|
||||
Organized color palettes by category:
|
||||
|
||||
```python
|
||||
CATEGORY_COLORS = {
|
||||
IndicatorCategory.TREND: {
|
||||
"primary": "#2E86C1", # Blue
|
||||
"secondary": "#5DADE2", # Light Blue
|
||||
"accent": "#1F618D" # Dark Blue
|
||||
},
|
||||
IndicatorCategory.MOMENTUM: {
|
||||
"primary": "#E74C3C", # Red
|
||||
"secondary": "#F1948A", # Light Red
|
||||
"accent": "#C0392B" # Dark Red
|
||||
},
|
||||
# ... more colors
|
||||
}
|
||||
```
|
||||
|
||||
### Access Functions
|
||||
|
||||
```python
|
||||
# Get all default indicators
|
||||
def get_all_default_indicators() -> Dict[str, IndicatorPreset]
|
||||
|
||||
# Filter by category
|
||||
def get_indicators_by_category(category: IndicatorCategory) -> Dict[str, IndicatorPreset]
|
||||
|
||||
# Filter by timeframe
|
||||
def get_indicators_for_timeframe(timeframe: str) -> Dict[str, IndicatorPreset]
|
||||
|
||||
# Get strategy-specific indicators
|
||||
def get_strategy_indicators(strategy: TradingStrategy) -> Dict[str, IndicatorPreset]
|
||||
|
||||
# Create custom preset
|
||||
def create_custom_preset(
|
||||
name: str,
|
||||
indicator_type: IndicatorType,
|
||||
parameters: Dict[str, Any],
|
||||
category: IndicatorCategory,
|
||||
**kwargs
|
||||
) -> tuple[Optional[IndicatorPreset], List[str]]
|
||||
```
|
||||
|
||||
## Strategy Configurations
|
||||
|
||||
### Core Classes
|
||||
|
||||
#### `StrategyChartConfig`
|
||||
|
||||
Complete chart configuration for a trading strategy:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class StrategyChartConfig:
|
||||
strategy_name: str
|
||||
strategy_type: TradingStrategy
|
||||
description: str
|
||||
timeframes: List[str]
|
||||
|
||||
# Chart layout
|
||||
layout: ChartLayout = ChartLayout.MAIN_WITH_SUBPLOTS
|
||||
main_chart_height: float = 0.7
|
||||
|
||||
# Indicators
|
||||
overlay_indicators: List[str] = field(default_factory=list)
|
||||
subplot_configs: List[SubplotConfig] = field(default_factory=list)
|
||||
|
||||
# Style
|
||||
chart_style: ChartStyle = field(default_factory=ChartStyle)
|
||||
|
||||
# Metadata
|
||||
created_at: Optional[datetime] = None
|
||||
updated_at: Optional[datetime] = None
|
||||
version: str = "1.0"
|
||||
tags: List[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
#### `SubplotConfig`
|
||||
|
||||
Configuration for chart subplots:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class SubplotConfig:
|
||||
subplot_type: SubplotType
|
||||
height_ratio: float = 0.3
|
||||
indicators: List[str] = field(default_factory=list)
|
||||
title: Optional[str] = None
|
||||
y_axis_label: Optional[str] = None
|
||||
show_grid: bool = True
|
||||
show_legend: bool = True
|
||||
background_color: Optional[str] = None
|
||||
```
|
||||
|
||||
#### `ChartStyle`
|
||||
|
||||
Comprehensive chart styling:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChartStyle:
|
||||
theme: str = "plotly_white"
|
||||
background_color: str = "#ffffff"
|
||||
grid_color: str = "#e6e6e6"
|
||||
text_color: str = "#2c3e50"
|
||||
font_family: str = "Arial, sans-serif"
|
||||
font_size: int = 12
|
||||
candlestick_up_color: str = "#26a69a"
|
||||
candlestick_down_color: str = "#ef5350"
|
||||
volume_color: str = "#78909c"
|
||||
show_volume: bool = True
|
||||
show_grid: bool = True
|
||||
show_legend: bool = True
|
||||
show_toolbar: bool = True
|
||||
```
|
||||
|
||||
### Default Strategy Configurations
|
||||
|
||||
Pre-built strategy configurations for common trading approaches:
|
||||
|
||||
1. **Scalping Strategy**
|
||||
- Ultra-fast indicators (EMA 5, 12, 21)
|
||||
- Fast RSI (7) and MACD (5,13,4)
|
||||
- 1m-5m timeframes
|
||||
|
||||
2. **Day Trading Strategy**
|
||||
- Balanced indicators (SMA 20, EMA 12/26, BB 20,2.0)
|
||||
- Standard RSI (14) and MACD (12,26,9)
|
||||
- 5m-1h timeframes
|
||||
|
||||
3. **Swing Trading Strategy**
|
||||
- Longer-term indicators (SMA 50, EMA 21/50, BB 20,2.0)
|
||||
- Standard momentum indicators
|
||||
- 1h-1d timeframes
|
||||
|
||||
### Configuration Functions
|
||||
|
||||
```python
|
||||
# Create default strategy configurations
|
||||
def create_default_strategy_configurations() -> Dict[str, StrategyChartConfig]
|
||||
|
||||
# Create custom strategy
|
||||
def create_custom_strategy_config(
|
||||
strategy_name: str,
|
||||
strategy_type: TradingStrategy,
|
||||
description: str,
|
||||
timeframes: List[str],
|
||||
overlay_indicators: List[str],
|
||||
subplot_configs: List[Dict[str, Any]],
|
||||
**kwargs
|
||||
) -> tuple[Optional[StrategyChartConfig], List[str]]
|
||||
|
||||
# JSON import/export
|
||||
def load_strategy_config_from_json(json_data: Union[str, Dict[str, Any]]) -> tuple[Optional[StrategyChartConfig], List[str]]
|
||||
def export_strategy_config_to_json(config: StrategyChartConfig) -> str
|
||||
|
||||
# Access functions
|
||||
def get_strategy_config(strategy_name: str) -> Optional[StrategyChartConfig]
|
||||
def get_all_strategy_configs() -> Dict[str, StrategyChartConfig]
|
||||
def get_available_strategy_names() -> List[str]
|
||||
```
|
||||
|
||||
## Validation System
|
||||
|
||||
### Validation Rules
|
||||
|
||||
The system includes 10 comprehensive validation rules:
|
||||
|
||||
1. **REQUIRED_FIELDS** - Validates essential configuration fields
|
||||
2. **HEIGHT_RATIOS** - Ensures chart height ratios sum correctly
|
||||
3. **INDICATOR_EXISTENCE** - Checks indicator availability
|
||||
4. **TIMEFRAME_FORMAT** - Validates timeframe patterns
|
||||
5. **CHART_STYLE** - Validates styling options
|
||||
6. **SUBPLOT_CONFIG** - Validates subplot configurations
|
||||
7. **STRATEGY_CONSISTENCY** - Checks strategy-timeframe alignment
|
||||
8. **PERFORMANCE_IMPACT** - Warns about performance issues
|
||||
9. **INDICATOR_CONFLICTS** - Detects redundant indicators
|
||||
10. **RESOURCE_USAGE** - Estimates resource consumption
|
||||
|
||||
### Validation Classes
|
||||
|
||||
#### `ValidationReport`
|
||||
|
||||
Comprehensive validation results:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ValidationReport:
|
||||
is_valid: bool
|
||||
errors: List[ValidationIssue] = field(default_factory=list)
|
||||
warnings: List[ValidationIssue] = field(default_factory=list)
|
||||
info: List[ValidationIssue] = field(default_factory=list)
|
||||
debug: List[ValidationIssue] = field(default_factory=list)
|
||||
validation_time: Optional[datetime] = None
|
||||
rules_applied: Set[ValidationRule] = field(default_factory=set)
|
||||
```
|
||||
|
||||
#### `ValidationIssue`
|
||||
|
||||
Individual validation issue:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ValidationIssue:
|
||||
level: ValidationLevel
|
||||
rule: ValidationRule
|
||||
message: str
|
||||
field_path: str = ""
|
||||
suggestion: Optional[str] = None
|
||||
auto_fix: Optional[str] = None
|
||||
context: Dict[str, Any] = field(default_factory=dict)
|
||||
```
|
||||
|
||||
### Validation Usage
|
||||
|
||||
```python
|
||||
from components.charts.config import validate_configuration
|
||||
|
||||
# Comprehensive validation
|
||||
report = validate_configuration(config)
|
||||
|
||||
# Check results
|
||||
if report.is_valid:
|
||||
print("✅ Configuration is valid")
|
||||
else:
|
||||
print("❌ Configuration has errors:")
|
||||
for error in report.errors:
|
||||
print(f" • {error}")
|
||||
|
||||
# Handle warnings
|
||||
if report.warnings:
|
||||
print("⚠️ Warnings:")
|
||||
for warning in report.warnings:
|
||||
print(f" • {warning}")
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
components/charts/config/
|
||||
├── __init__.py # Package exports and public API
|
||||
├── indicator_defs.py # Core indicator schemas and validation
|
||||
├── defaults.py # Default indicator presets and categories
|
||||
├── strategy_charts.py # Strategy configuration classes and defaults
|
||||
├── validation.py # Validation system and rules
|
||||
└── example_strategies.py # Real-world trading strategy examples
|
||||
```
|
||||
|
||||
### Key Exports
|
||||
|
||||
From `__init__.py`:
|
||||
|
||||
```python
|
||||
# Core classes
|
||||
from .indicator_defs import (
|
||||
IndicatorType, DisplayType, LineStyle, PriceColumn,
|
||||
IndicatorParameterSchema, IndicatorSchema, ChartIndicatorConfig
|
||||
)
|
||||
|
||||
# Default configurations
|
||||
from .defaults import (
|
||||
IndicatorCategory, TradingStrategy, IndicatorPreset,
|
||||
get_all_default_indicators, get_indicators_by_category
|
||||
)
|
||||
|
||||
# Strategy configurations
|
||||
from .strategy_charts import (
|
||||
ChartLayout, SubplotType, SubplotConfig, ChartStyle, StrategyChartConfig,
|
||||
create_default_strategy_configurations
|
||||
)
|
||||
|
||||
# Validation system
|
||||
from .validation import (
|
||||
ValidationLevel, ValidationRule, ValidationIssue, ValidationReport,
|
||||
validate_configuration
|
||||
)
|
||||
|
||||
# Example strategies
|
||||
from .example_strategies import (
|
||||
StrategyExample, create_ema_crossover_strategy,
|
||||
get_all_example_strategies
|
||||
)
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Creating Custom Indicator
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
create_indicator_config, IndicatorType
|
||||
)
|
||||
|
||||
# Create custom EMA configuration
|
||||
config, errors = create_indicator_config(
|
||||
indicator_type=IndicatorType.EMA,
|
||||
parameters={"period": 21, "price_column": "close"},
|
||||
display_name="EMA 21",
|
||||
color="#2E86C1",
|
||||
line_width=2
|
||||
)
|
||||
|
||||
if config:
|
||||
print(f"Created: {config.display_name}")
|
||||
else:
|
||||
print(f"Errors: {errors}")
|
||||
```
|
||||
|
||||
### Example 2: Using Default Presets
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
get_all_default_indicators,
|
||||
get_indicators_by_category,
|
||||
IndicatorCategory
|
||||
)
|
||||
|
||||
# Get all available indicators
|
||||
all_indicators = get_all_default_indicators()
|
||||
print(f"Available indicators: {len(all_indicators)}")
|
||||
|
||||
# Get trend indicators only
|
||||
trend_indicators = get_indicators_by_category(IndicatorCategory.TREND)
|
||||
for name, preset in trend_indicators.items():
|
||||
print(f"{name}: {preset.description}")
|
||||
```
|
||||
|
||||
### Example 3: Strategy Configuration
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
create_custom_strategy_config,
|
||||
TradingStrategy
|
||||
)
|
||||
|
||||
# Create custom momentum strategy
|
||||
config, errors = create_custom_strategy_config(
|
||||
strategy_name="Custom Momentum",
|
||||
strategy_type=TradingStrategy.MOMENTUM,
|
||||
description="Fast momentum trading strategy",
|
||||
timeframes=["5m", "15m"],
|
||||
overlay_indicators=["ema_8", "ema_21"],
|
||||
subplot_configs=[{
|
||||
"subplot_type": "rsi",
|
||||
"height_ratio": 0.2,
|
||||
"indicators": ["rsi_7"]
|
||||
}]
|
||||
)
|
||||
|
||||
if config:
|
||||
print(f"Created strategy: {config.strategy_name}")
|
||||
is_valid, validation_errors = config.validate()
|
||||
if is_valid:
|
||||
print("Strategy is valid!")
|
||||
else:
|
||||
print(f"Validation errors: {validation_errors}")
|
||||
```
|
||||
|
||||
### Example 4: Comprehensive Validation
|
||||
|
||||
```python
|
||||
from components.charts.config import (
|
||||
validate_configuration,
|
||||
ValidationRule
|
||||
)
|
||||
|
||||
# Validate with specific rules
|
||||
rules = {ValidationRule.REQUIRED_FIELDS, ValidationRule.HEIGHT_RATIOS}
|
||||
report = validate_configuration(config, rules=rules)
|
||||
|
||||
# Detailed error handling
|
||||
for error in report.errors:
|
||||
print(f"ERROR: {error.message}")
|
||||
if error.suggestion:
|
||||
print(f" Suggestion: {error.suggestion}")
|
||||
if error.auto_fix:
|
||||
print(f" Auto-fix: {error.auto_fix}")
|
||||
|
||||
# Performance warnings
|
||||
performance_issues = report.get_issues_by_rule(ValidationRule.PERFORMANCE_IMPACT)
|
||||
if performance_issues:
|
||||
print(f"Performance concerns: {len(performance_issues)}")
|
||||
```
|
||||
|
||||
## Extension Guide
|
||||
|
||||
### Adding New Indicators
|
||||
|
||||
1. **Define Indicator Type**
|
||||
```python
|
||||
# Add to IndicatorType enum
|
||||
class IndicatorType(str, Enum):
|
||||
# ... existing types
|
||||
STOCHASTIC = "stochastic"
|
||||
```
|
||||
|
||||
2. **Create Schema**
|
||||
```python
|
||||
# Add to INDICATOR_SCHEMAS
|
||||
INDICATOR_SCHEMAS[IndicatorType.STOCHASTIC] = IndicatorSchema(
|
||||
indicator_type=IndicatorType.STOCHASTIC,
|
||||
display_type=DisplayType.SUBPLOT,
|
||||
parameters=[
|
||||
IndicatorParameterSchema(
|
||||
name="k_period",
|
||||
type=int,
|
||||
min_value=1,
|
||||
max_value=100,
|
||||
default_value=14
|
||||
),
|
||||
# ... more parameters
|
||||
],
|
||||
description="Stochastic Oscillator",
|
||||
calculation_description="Momentum indicator comparing closing price to price range"
|
||||
)
|
||||
```
|
||||
|
||||
3. **Create Default Presets**
|
||||
```python
|
||||
# Add to defaults.py
|
||||
def create_momentum_indicators():
|
||||
# ... existing indicators
|
||||
indicators["stoch_14"] = IndicatorPreset(
|
||||
name="stoch_14",
|
||||
config=create_indicator_config(
|
||||
IndicatorType.STOCHASTIC,
|
||||
{"k_period": 14, "d_period": 3},
|
||||
display_name="Stochastic %K(14,%D(3))",
|
||||
color=CATEGORY_COLORS[IndicatorCategory.MOMENTUM]["primary"]
|
||||
)[0],
|
||||
category=IndicatorCategory.MOMENTUM,
|
||||
description="Standard Stochastic oscillator",
|
||||
recommended_timeframes=["15m", "1h", "4h"],
|
||||
suitable_strategies=[TradingStrategy.SWING_TRADING]
|
||||
)
|
||||
```
|
||||
|
||||
### Adding New Validation Rules
|
||||
|
||||
1. **Define Rule**
|
||||
```python
|
||||
# Add to ValidationRule enum
|
||||
class ValidationRule(str, Enum):
|
||||
# ... existing rules
|
||||
CUSTOM_RULE = "custom_rule"
|
||||
```
|
||||
|
||||
2. **Implement Validation**
|
||||
```python
|
||||
# Add to ConfigurationValidator
|
||||
def _validate_custom_rule(self, config: StrategyChartConfig, report: ValidationReport) -> None:
|
||||
# Custom validation logic
|
||||
if some_condition:
|
||||
report.add_issue(ValidationIssue(
|
||||
level=ValidationLevel.WARNING,
|
||||
rule=ValidationRule.CUSTOM_RULE,
|
||||
message="Custom validation message",
|
||||
suggestion="Suggested fix"
|
||||
))
|
||||
```
|
||||
|
||||
3. **Add to Validator**
|
||||
```python
|
||||
# Add to validate_strategy_config method
|
||||
if ValidationRule.CUSTOM_RULE in self.enabled_rules:
|
||||
self._validate_custom_rule(config, report)
|
||||
```
|
||||
|
||||
### Adding New Strategy Types
|
||||
|
||||
1. **Define Strategy Type**
|
||||
```python
|
||||
# Add to TradingStrategy enum
|
||||
class TradingStrategy(str, Enum):
|
||||
# ... existing strategies
|
||||
GRID_TRADING = "grid_trading"
|
||||
```
|
||||
|
||||
2. **Create Strategy Configuration**
|
||||
```python
|
||||
# Add to create_default_strategy_configurations()
|
||||
strategy_configs["grid_trading"] = StrategyChartConfig(
|
||||
strategy_name="Grid Trading Strategy",
|
||||
strategy_type=TradingStrategy.GRID_TRADING,
|
||||
description="Grid trading with support/resistance levels",
|
||||
timeframes=["1h", "4h"],
|
||||
overlay_indicators=["sma_20", "sma_50"],
|
||||
# ... complete configuration
|
||||
)
|
||||
```
|
||||
|
||||
3. **Add Example Strategy**
|
||||
```python
|
||||
# Create in example_strategies.py
|
||||
def create_grid_trading_strategy() -> StrategyExample:
|
||||
config = StrategyChartConfig(...)
|
||||
return StrategyExample(
|
||||
config=config,
|
||||
description="Grid trading strategy description...",
|
||||
difficulty="Intermediate",
|
||||
risk_level="Medium"
|
||||
)
|
||||
```
|
||||
|
||||
The configuration system is designed to be highly extensible while maintaining type safety and comprehensive validation. All additions should follow the established patterns and include appropriate tests.
|
||||
280
docs/components/charts/quick-reference.md
Normal file
280
docs/components/charts/quick-reference.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# Chart System Quick Reference
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Import Everything You Need
|
||||
```python
|
||||
from components.charts.config import (
|
||||
# Example strategies
|
||||
create_ema_crossover_strategy,
|
||||
get_all_example_strategies,
|
||||
|
||||
# Configuration
|
||||
StrategyChartConfig,
|
||||
create_custom_strategy_config,
|
||||
validate_configuration,
|
||||
|
||||
# Indicators
|
||||
get_all_default_indicators,
|
||||
get_indicators_by_category,
|
||||
IndicatorCategory,
|
||||
TradingStrategy
|
||||
)
|
||||
```
|
||||
|
||||
### Use Pre-built Strategy
|
||||
```python
|
||||
# Get EMA crossover strategy
|
||||
strategy = create_ema_crossover_strategy()
|
||||
config = strategy.config
|
||||
|
||||
# Validate before use
|
||||
report = validate_configuration(config)
|
||||
if report.is_valid:
|
||||
print("✅ Ready to use!")
|
||||
else:
|
||||
print(f"❌ Errors: {[str(e) for e in report.errors]}")
|
||||
```
|
||||
|
||||
### Create Custom Strategy
|
||||
```python
|
||||
config, errors = create_custom_strategy_config(
|
||||
strategy_name="My Strategy",
|
||||
strategy_type=TradingStrategy.DAY_TRADING,
|
||||
description="Custom day trading strategy",
|
||||
timeframes=["15m", "1h"],
|
||||
overlay_indicators=["ema_12", "ema_26"],
|
||||
subplot_configs=[{
|
||||
"subplot_type": "rsi",
|
||||
"height_ratio": 0.2,
|
||||
"indicators": ["rsi_14"]
|
||||
}]
|
||||
)
|
||||
```
|
||||
|
||||
## Available Indicators
|
||||
|
||||
### Trend Indicators
|
||||
- `sma_5`, `sma_10`, `sma_20`, `sma_50`, `sma_100`, `sma_200`
|
||||
- `ema_5`, `ema_12`, `ema_21`, `ema_26`, `ema_50`, `ema_100`, `ema_200`
|
||||
|
||||
### Momentum Indicators
|
||||
- `rsi_7`, `rsi_14`, `rsi_21`
|
||||
- `macd_5_13_4`, `macd_8_17_6`, `macd_12_26_9`, `macd_19_39_13`
|
||||
|
||||
### Volatility Indicators
|
||||
- `bb_10_15`, `bb_20_15`, `bb_20_20`, `bb_50_20`
|
||||
|
||||
## Example Strategies
|
||||
|
||||
### 1. EMA Crossover (Intermediate, Medium Risk)
|
||||
```python
|
||||
strategy = create_ema_crossover_strategy()
|
||||
# Uses: EMA 12/26/50, RSI 14, MACD, Bollinger Bands
|
||||
# Best for: Trending markets, 15m-4h timeframes
|
||||
```
|
||||
|
||||
### 2. Momentum Breakout (Advanced, High Risk)
|
||||
```python
|
||||
strategy = create_momentum_breakout_strategy()
|
||||
# Uses: EMA 8/21, Fast RSI/MACD, Volume
|
||||
# Best for: Volatile markets, 5m-1h timeframes
|
||||
```
|
||||
|
||||
### 3. Mean Reversion (Intermediate, Medium Risk)
|
||||
```python
|
||||
strategy = create_mean_reversion_strategy()
|
||||
# Uses: SMA 20/50, Multiple RSI, Tight BB
|
||||
# Best for: Ranging markets, 15m-4h timeframes
|
||||
```
|
||||
|
||||
### 4. Scalping (Advanced, High Risk)
|
||||
```python
|
||||
strategy = create_scalping_strategy()
|
||||
# Uses: Ultra-fast EMAs, RSI 7, Fast MACD
|
||||
# Best for: High liquidity, 1m-5m timeframes
|
||||
```
|
||||
|
||||
### 5. Swing Trading (Beginner, Medium Risk)
|
||||
```python
|
||||
strategy = create_swing_trading_strategy()
|
||||
# Uses: SMA 20/50, Standard indicators
|
||||
# Best for: Trending markets, 4h-1d timeframes
|
||||
```
|
||||
|
||||
## Strategy Filtering
|
||||
|
||||
### By Difficulty
|
||||
```python
|
||||
beginner = get_strategies_by_difficulty("Beginner")
|
||||
intermediate = get_strategies_by_difficulty("Intermediate")
|
||||
advanced = get_strategies_by_difficulty("Advanced")
|
||||
```
|
||||
|
||||
### By Risk Level
|
||||
```python
|
||||
low_risk = get_strategies_by_risk_level("Low")
|
||||
medium_risk = get_strategies_by_risk_level("Medium")
|
||||
high_risk = get_strategies_by_risk_level("High")
|
||||
```
|
||||
|
||||
### By Market Condition
|
||||
```python
|
||||
trending = get_strategies_by_market_condition("Trending")
|
||||
sideways = get_strategies_by_market_condition("Sideways")
|
||||
volatile = get_strategies_by_market_condition("Volatile")
|
||||
```
|
||||
|
||||
## Validation Quick Checks
|
||||
|
||||
### Basic Validation
|
||||
```python
|
||||
is_valid, errors = config.validate()
|
||||
if not is_valid:
|
||||
for error in errors:
|
||||
print(f"❌ {error}")
|
||||
```
|
||||
|
||||
### Comprehensive Validation
|
||||
```python
|
||||
report = validate_configuration(config)
|
||||
|
||||
# Errors (must fix)
|
||||
for error in report.errors:
|
||||
print(f"🚨 {error}")
|
||||
|
||||
# Warnings (recommended)
|
||||
for warning in report.warnings:
|
||||
print(f"⚠️ {warning}")
|
||||
|
||||
# Info (optional)
|
||||
for info in report.info:
|
||||
print(f"ℹ️ {info}")
|
||||
```
|
||||
|
||||
## JSON Export/Import
|
||||
|
||||
### Export Strategy
|
||||
```python
|
||||
json_data = export_strategy_config_to_json(config)
|
||||
```
|
||||
|
||||
### Import Strategy
|
||||
```python
|
||||
config, errors = load_strategy_config_from_json(json_data)
|
||||
```
|
||||
|
||||
### Export All Examples
|
||||
```python
|
||||
all_strategies_json = export_example_strategies_to_json()
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Get Strategy Summary
|
||||
```python
|
||||
summary = get_strategy_summary()
|
||||
for name, info in summary.items():
|
||||
print(f"{name}: {info['difficulty']} - {info['risk_level']}")
|
||||
```
|
||||
|
||||
### List Available Indicators
|
||||
```python
|
||||
indicators = get_all_default_indicators()
|
||||
for name, preset in indicators.items():
|
||||
print(f"{name}: {preset.description}")
|
||||
```
|
||||
|
||||
### Filter by Category
|
||||
```python
|
||||
trend_indicators = get_indicators_by_category(IndicatorCategory.TREND)
|
||||
momentum_indicators = get_indicators_by_category(IndicatorCategory.MOMENTUM)
|
||||
```
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
### Strategy Config
|
||||
```python
|
||||
StrategyChartConfig(
|
||||
strategy_name="Strategy Name",
|
||||
strategy_type=TradingStrategy.DAY_TRADING,
|
||||
description="Strategy description",
|
||||
timeframes=["15m", "1h"],
|
||||
overlay_indicators=["ema_12", "ema_26"],
|
||||
subplot_configs=[
|
||||
{
|
||||
"subplot_type": "rsi",
|
||||
"height_ratio": 0.2,
|
||||
"indicators": ["rsi_14"]
|
||||
}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Subplot Types
|
||||
- `"rsi"` - RSI oscillator
|
||||
- `"macd"` - MACD with histogram
|
||||
- `"volume"` - Volume bars
|
||||
|
||||
### Timeframe Formats
|
||||
- `"1m"`, `"5m"`, `"15m"`, `"30m"`
|
||||
- `"1h"`, `"2h"`, `"4h"`, `"6h"`, `"12h"`
|
||||
- `"1d"`, `"1w"`, `"1M"`
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
1. **"Indicator not found"** - Check available indicators list
|
||||
2. **"Height ratios exceed 1.0"** - Adjust main_chart_height and subplot ratios
|
||||
3. **"Invalid timeframe"** - Use standard timeframe formats
|
||||
|
||||
### Validation Rules
|
||||
1. Required fields present
|
||||
2. Height ratios sum ≤ 1.0
|
||||
3. Indicators exist in defaults
|
||||
4. Valid timeframe formats
|
||||
5. Chart style validation
|
||||
6. Subplot configuration
|
||||
7. Strategy consistency
|
||||
8. Performance impact
|
||||
9. Indicator conflicts
|
||||
10. Resource usage
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Strategy Design
|
||||
- Start with proven strategies (EMA crossover)
|
||||
- Match timeframes to strategy type
|
||||
- Balance indicator categories (trend + momentum + volume)
|
||||
- Consider performance impact (<10 indicators)
|
||||
|
||||
### Validation
|
||||
- Always validate before use
|
||||
- Address all errors
|
||||
- Consider warnings for optimization
|
||||
- Test with edge cases
|
||||
|
||||
### Performance
|
||||
- Limit complex indicators (Bollinger Bands)
|
||||
- Monitor resource usage warnings
|
||||
- Cache validated configurations
|
||||
- Use appropriate timeframes for strategy type
|
||||
|
||||
## Testing Commands
|
||||
|
||||
```bash
|
||||
# Test all chart components
|
||||
uv run pytest tests/test_*_strategies.py -v
|
||||
uv run pytest tests/test_validation.py -v
|
||||
uv run pytest tests/test_defaults.py -v
|
||||
|
||||
# Test specific component
|
||||
uv run pytest tests/test_example_strategies.py::TestEMACrossoverStrategy -v
|
||||
```
|
||||
|
||||
## File Locations
|
||||
|
||||
- **Main config**: `components/charts/config/`
|
||||
- **Documentation**: `docs/components/charts/`
|
||||
- **Tests**: `tests/test_*_strategies.py`
|
||||
- **Examples**: `components/charts/config/example_strategies.py`
|
||||
Reference in New Issue
Block a user