documentation update
This commit is contained in:
Vasily.onl
702
docs/modules/charts/README.md
Normal file
702
docs/modules/charts/README.md
Normal file
@@ -0,0 +1,702 @@
|
||||
# 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)
|
||||
- [User Indicator Management](#user-indicator-management)
|
||||
- [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
|
||||
- **User Indicator Management**: Create, edit, and manage custom indicators with JSON persistence
|
||||
- **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/
|
||||
├── indicator_manager.py # User indicator CRUD operations
|
||||
├── indicator_defaults.py # Default indicator templates
|
||||
├── 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
|
||||
|
||||
dashboard/ # Modular dashboard integration
|
||||
├── layouts/market_data.py # Chart layout with controls
|
||||
├── callbacks/charts.py # Chart update callbacks
|
||||
├── components/
|
||||
│ ├── chart_controls.py # Reusable chart configuration panel
|
||||
│ └── indicator_modal.py # Indicator management UI
|
||||
|
||||
config/indicators/
|
||||
└── user_indicators/ # User-created indicators (JSON files)
|
||||
├── sma_abc123.json
|
||||
├── ema_def456.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Dashboard Integration
|
||||
|
||||
The chart system is fully integrated with the modular dashboard structure:
|
||||
|
||||
### Modular Components
|
||||
|
||||
- **`dashboard/layouts/market_data.py`** - Chart layout with strategy selection and indicator controls
|
||||
- **`dashboard/callbacks/charts.py`** - Chart update callbacks with strategy handling
|
||||
- **`dashboard/components/chart_controls.py`** - Reusable chart configuration panel
|
||||
- **`dashboard/components/indicator_modal.py`** - Complete indicator management interface
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Strategy Dropdown**: Auto-loads predefined indicator combinations
|
||||
- **Real-time Updates**: Charts update immediately with indicator changes
|
||||
- **Modular Architecture**: Each component under 300 lines for maintainability
|
||||
- **Separated Concerns**: Layouts, callbacks, and components in dedicated modules
|
||||
|
||||
### Usage in Dashboard
|
||||
|
||||
```python
|
||||
# From dashboard/layouts/market_data.py
|
||||
from components.charts.config import get_available_strategy_names
|
||||
from components.charts.indicator_manager import get_indicator_manager
|
||||
|
||||
# Get available strategies for dropdown
|
||||
strategy_names = get_available_strategy_names()
|
||||
strategy_options = [{'label': name.replace('_', ' ').title(), 'value': name}
|
||||
for name in strategy_names]
|
||||
|
||||
# Get user indicators for checklists
|
||||
indicator_manager = get_indicator_manager()
|
||||
overlay_indicators = indicator_manager.get_indicators_by_type('overlay')
|
||||
subplot_indicators = indicator_manager.get_indicators_by_type('subplot')
|
||||
```
|
||||
|
||||
For complete dashboard documentation, see [Dashboard Modular Structure (`../dashboard-modular-structure.md`)](../dashboard-modular-structure.md).
|
||||
|
||||
## User Indicator Management
|
||||
|
||||
The system includes a comprehensive user indicator management system that allows creating, editing, and managing custom technical indicators.
|
||||
|
||||
### Features
|
||||
|
||||
- **Interactive UI**: Modal dialog for creating and editing indicators
|
||||
- **Real-time Updates**: Charts update immediately when indicators are toggled
|
||||
- **JSON Persistence**: Each indicator saved as individual JSON file
|
||||
- **Full CRUD Operations**: Create, Read, Update, Delete functionality
|
||||
- **Type Validation**: Parameter validation based on indicator type
|
||||
- **Custom Styling**: Color, line width, and appearance customization
|
||||
|
||||
### Quick Access
|
||||
|
||||
- **📊 [Complete Indicator Documentation (`indicators.md`)](./indicators.md)** - Comprehensive guide to the indicator system
|
||||
- **⚡ [Quick Guide: Adding New Indicators (`adding-new-indicators.md`)](./adding-new-indicators.md)** - Step-by-step checklist for developers
|
||||
|
||||
### Current User Indicators
|
||||
|
||||
| Indicator | Type | Parameters | Display |
|
||||
|-----------|------|------------|---------|
|
||||
| Simple Moving Average (SMA) | `sma` | period (1-200) | Overlay |
|
||||
| Exponential Moving Average (EMA) | `ema` | period (1-200) | Overlay |
|
||||
| Bollinger Bands | `bollinger_bands` | period (5-100), std_dev (0.5-5.0) | Overlay |
|
||||
| Relative Strength Index (RSI) | `rsi` | period (2-50) | Subplot |
|
||||
| MACD | `macd` | fast_period, slow_period, signal_period | Subplot |
|
||||
|
||||
### Usage Example
|
||||
|
||||
```python
|
||||
# Get indicator manager
|
||||
from components.charts.indicator_manager import get_indicator_manager
|
||||
manager = get_indicator_manager()
|
||||
|
||||
# Create new indicator
|
||||
indicator = manager.create_indicator(
|
||||
name="My SMA 50",
|
||||
indicator_type="sma",
|
||||
parameters={"period": 50},
|
||||
description="50-period Simple Moving Average",
|
||||
color="#ff0000"
|
||||
)
|
||||
|
||||
# Load and update
|
||||
loaded = manager.load_indicator("sma_abc123")
|
||||
success = manager.update_indicator("sma_abc123", name="Updated SMA")
|
||||
|
||||
# Get indicators by type
|
||||
overlay_indicators = manager.get_indicators_by_type("overlay")
|
||||
subplot_indicators = manager.get_indicators_by_type("subplot")
|
||||
```
|
||||
|
||||
## 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 - **IMPLEMENTED** - See [Bot Integration Guide (`bot-integration.md`)](./bot-integration.md)
|
||||
- **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
|
||||
|
||||
## Bot Integration
|
||||
|
||||
The chart system now includes comprehensive bot integration capabilities:
|
||||
|
||||
- **Real-time Signal Visualization**: Live bot signals on charts
|
||||
- **Trade Execution Tracking**: P&L and trade entry/exit points
|
||||
- **Multi-Bot Support**: Compare strategies across multiple bots
|
||||
- **Performance Analytics**: Built-in bot performance metrics
|
||||
|
||||
📊 **[Complete Bot Integration Guide (`bot-integration.md`)](./bot-integration.md)** - Comprehensive documentation for integrating bot signals with charts
|
||||
|
||||
## 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.
|
||||
---
|
||||
|
||||
*Back to [Modules Documentation](../README.md)*
|
||||
249
docs/modules/charts/adding-new-indicators.md
Normal file
249
docs/modules/charts/adding-new-indicators.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# Quick Guide: Adding New Indicators
|
||||
|
||||
## Overview
|
||||
|
||||
This guide provides a step-by-step checklist for adding new technical indicators to the Crypto Trading Bot Dashboard, updated for the new modular dashboard structure.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Understanding of Python and technical analysis
|
||||
- Familiarity with the project structure and Dash callbacks
|
||||
- Knowledge of the indicator type (overlay vs subplot)
|
||||
|
||||
## Step-by-Step Checklist
|
||||
|
||||
### ✅ Step 1: Plan Your Indicator
|
||||
|
||||
- [ ] Determine indicator type (overlay or subplot)
|
||||
- [ ] Define required parameters
|
||||
- [ ] Choose default styling
|
||||
- [ ] Research calculation formula
|
||||
|
||||
### ✅ Step 2: Create Indicator Class
|
||||
|
||||
**File**: `components/charts/layers/indicators.py` (overlay) or `components/charts/layers/subplots.py` (subplot)
|
||||
|
||||
Create a class for your indicator that inherits from `IndicatorLayer`.
|
||||
|
||||
```python
|
||||
class StochasticLayer(IndicatorLayer):
|
||||
def __init__(self, config: Dict[str, Any]):
|
||||
super().__init__(config)
|
||||
self.name = "stochastic"
|
||||
self.display_type = "subplot"
|
||||
|
||||
def calculate_values(self, df: pd.DataFrame) -> Dict[str, pd.Series]:
|
||||
k_period = self.config.get('k_period', 14)
|
||||
d_period = self.config.get('d_period', 3)
|
||||
lowest_low = df['low'].rolling(window=k_period).min()
|
||||
highest_high = df['high'].rolling(window=k_period).max()
|
||||
k_percent = 100 * ((df['close'] - lowest_low) / (highest_high - lowest_low))
|
||||
d_percent = k_percent.rolling(window=d_period).mean()
|
||||
return {'k_percent': k_percent, 'd_percent': d_percent}
|
||||
|
||||
def create_traces(self, df: pd.DataFrame, values: Dict[str, pd.Series]) -> List[go.Scatter]:
|
||||
traces = []
|
||||
traces.append(go.Scatter(x=df.index, y=values['k_percent'], mode='lines', name=f"%K ({self.config.get('k_period', 14)})", line=dict(color=self.config.get('color', '#007bff'), width=self.config.get('line_width', 2))))
|
||||
traces.append(go.Scatter(x=df.index, y=values['d_percent'], mode='lines', name=f"%D ({self.config.get('d_period', 3)})", line=dict(color=self.config.get('secondary_color', '#ff6b35'), width=self.config.get('line_width', 2))))
|
||||
return traces
|
||||
```
|
||||
|
||||
### ✅ Step 3: Register Indicator
|
||||
|
||||
**File**: `components/charts/layers/__init__.py`
|
||||
|
||||
Register your new indicator class in the appropriate registry.
|
||||
|
||||
```python
|
||||
from .subplots import StochasticLayer
|
||||
|
||||
SUBPLOT_REGISTRY = {
|
||||
'rsi': RSILayer,
|
||||
'macd': MACDLayer,
|
||||
'stochastic': StochasticLayer,
|
||||
}
|
||||
|
||||
INDICATOR_REGISTRY = {
|
||||
'sma': SMALayer,
|
||||
'ema': EMALayer,
|
||||
'bollinger_bands': BollingerBandsLayer,
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ Step 4: Add UI Dropdown Option
|
||||
|
||||
**File**: `dashboard/components/indicator_modal.py`
|
||||
|
||||
Add your new indicator to the `indicator-type-dropdown` options.
|
||||
|
||||
```python
|
||||
dcc.Dropdown(
|
||||
id='indicator-type-dropdown',
|
||||
options=[
|
||||
{'label': 'Simple Moving Average (SMA)', 'value': 'sma'},
|
||||
{'label': 'Exponential Moving Average (EMA)', 'value': 'ema'},
|
||||
{'label': 'Relative Strength Index (RSI)', 'value': 'rsi'},
|
||||
{'label': 'MACD', 'value': 'macd'},
|
||||
{'label': 'Bollinger Bands', 'value': 'bollinger_bands'},
|
||||
{'label': 'Stochastic Oscillator', 'value': 'stochastic'},
|
||||
],
|
||||
placeholder='Select indicator type',
|
||||
)
|
||||
```
|
||||
|
||||
### ✅ Step 5: Add Parameter Fields to Modal
|
||||
|
||||
**File**: `dashboard/components/indicator_modal.py`
|
||||
|
||||
In `create_parameter_fields`, add the `dcc.Input` components for your indicator's parameters.
|
||||
|
||||
```python
|
||||
def create_parameter_fields():
|
||||
return html.Div([
|
||||
# ... existing parameter fields ...
|
||||
html.Div([
|
||||
dbc.Row([
|
||||
dbc.Col([dbc.Label("%K Period:"), dcc.Input(id='stochastic-k-period-input', type='number', value=14)], width=6),
|
||||
dbc.Col([dbc.Label("%D Period:"), dcc.Input(id='stochastic-d-period-input', type='number', value=3)], width=6),
|
||||
]),
|
||||
dbc.FormText("Stochastic oscillator periods for %K and %D lines")
|
||||
], id='stochastic-parameters', style={'display': 'none'}, className="mb-3")
|
||||
])
|
||||
```
|
||||
|
||||
### ✅ Step 6: Update Parameter Visibility Callback
|
||||
|
||||
**File**: `dashboard/callbacks/indicators.py`
|
||||
|
||||
In `update_parameter_fields`, add an `Output` and logic to show/hide your new parameter fields.
|
||||
|
||||
```python
|
||||
@app.callback(
|
||||
[Output('indicator-parameters-message', 'style'),
|
||||
Output('sma-parameters', 'style'),
|
||||
Output('ema-parameters', 'style'),
|
||||
Output('rsi-parameters', 'style'),
|
||||
Output('macd-parameters', 'style'),
|
||||
Output('bb-parameters', 'style'),
|
||||
Output('stochastic-parameters', 'style')],
|
||||
Input('indicator-type-dropdown', 'value'),
|
||||
)
|
||||
def update_parameter_fields(indicator_type):
|
||||
styles = { 'sma': {'display': 'none'}, 'ema': {'display': 'none'}, 'rsi': {'display': 'none'}, 'macd': {'display': 'none'}, 'bb': {'display': 'none'}, 'stochastic': {'display': 'none'} }
|
||||
message_style = {'display': 'block'} if not indicator_type else {'display': 'none'}
|
||||
if indicator_type:
|
||||
styles[indicator_type] = {'display': 'block'}
|
||||
return [message_style] + list(styles.values())
|
||||
```
|
||||
|
||||
### ✅ Step 7: Update Save Indicator Callback
|
||||
|
||||
**File**: `dashboard/callbacks/indicators.py`
|
||||
|
||||
In `save_new_indicator`, add `State` inputs for your parameters and logic to collect them.
|
||||
|
||||
```python
|
||||
@app.callback(
|
||||
# ... Outputs ...
|
||||
Input('save-indicator-btn', 'n_clicks'),
|
||||
[# ... States ...
|
||||
State('stochastic-k-period-input', 'value'),
|
||||
State('stochastic-d-period-input', 'value'),
|
||||
State('edit-indicator-store', 'data')],
|
||||
)
|
||||
def save_new_indicator(n_clicks, name, indicator_type, ..., stochastic_k, stochastic_d, edit_data):
|
||||
# ...
|
||||
elif indicator_type == 'stochastic':
|
||||
parameters = {'k_period': stochastic_k or 14, 'd_period': stochastic_d or 3}
|
||||
# ...
|
||||
```
|
||||
|
||||
### ✅ Step 8: Update Edit Callback Parameters
|
||||
|
||||
**File**: `dashboard/callbacks/indicators.py`
|
||||
|
||||
In `edit_indicator`, add `Output`s for your parameter fields and logic to load values.
|
||||
|
||||
```python
|
||||
@app.callback(
|
||||
[# ... Outputs ...
|
||||
Output('stochastic-k-period-input', 'value'),
|
||||
Output('stochastic-d-period-input', 'value')],
|
||||
Input({'type': 'edit-indicator-btn', 'index': dash.ALL}, 'n_clicks'),
|
||||
)
|
||||
def edit_indicator(edit_clicks, button_ids):
|
||||
# ...
|
||||
stochastic_k, stochastic_d = 14, 3
|
||||
if indicator:
|
||||
# ...
|
||||
elif indicator.type == 'stochastic':
|
||||
stochastic_k = params.get('k_period', 14)
|
||||
stochastic_d = params.get('d_period', 3)
|
||||
return (..., stochastic_k, stochastic_d)
|
||||
```
|
||||
|
||||
### ✅ Step 9: Update Reset Callback
|
||||
|
||||
**File**: `dashboard/callbacks/indicators.py`
|
||||
|
||||
In `reset_modal_form`, add `Output`s for your parameter fields and their default values.
|
||||
|
||||
```python
|
||||
@app.callback(
|
||||
[# ... Outputs ...
|
||||
Output('stochastic-k-period-input', 'value', allow_duplicate=True),
|
||||
Output('stochastic-d-period-input', 'value', allow_duplicate=True)],
|
||||
Input('cancel-indicator-btn', 'n_clicks'),
|
||||
)
|
||||
def reset_modal_form(cancel_clicks):
|
||||
# ...
|
||||
return ..., 14, 3
|
||||
```
|
||||
|
||||
### ✅ Step 10: Create Default Template
|
||||
|
||||
**File**: `components/charts/indicator_defaults.py`
|
||||
|
||||
Create a default template for your indicator.
|
||||
|
||||
```python
|
||||
def create_stochastic_template() -> UserIndicator:
|
||||
return UserIndicator(
|
||||
id=f"stochastic_{generate_short_id()}",
|
||||
name="Stochastic 14,3",
|
||||
type="stochastic",
|
||||
display_type="subplot",
|
||||
parameters={"k_period": 14, "d_period": 3},
|
||||
styling=IndicatorStyling(color="#9c27b0", line_width=2)
|
||||
)
|
||||
|
||||
DEFAULT_TEMPLATES = {
|
||||
# ...
|
||||
"stochastic": create_stochastic_template,
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ Step 11: Add Calculation Function (Optional)
|
||||
|
||||
**File**: `data/common/indicators.py`
|
||||
|
||||
Add a standalone calculation function.
|
||||
|
||||
```python
|
||||
def calculate_stochastic(df: pd.DataFrame, k_period: int = 14, d_period: int = 3) -> tuple:
|
||||
lowest_low = df['low'].rolling(window=k_period).min()
|
||||
highest_high = df['high'].rolling(window=k_period).max()
|
||||
k_percent = 100 * ((df['close'] - lowest_low) / (highest_high - lowest_low))
|
||||
d_percent = k_percent.rolling(window=d_period).mean()
|
||||
return k_percent, d_percent
|
||||
```
|
||||
|
||||
## File Change Summary
|
||||
|
||||
When adding a new indicator, you'll typically modify these files:
|
||||
1. **`components/charts/layers/indicators.py`** or **`subplots.py`**
|
||||
2. **`components/charts/layers/__init__.py`**
|
||||
3. **`dashboard/components/indicator_modal.py`**
|
||||
4. **`dashboard/callbacks/indicators.py`**
|
||||
5. **`components/charts/indicator_defaults.py`**
|
||||
6. **`data/common/indicators.py`** (optional)
|
||||
630
docs/modules/charts/bot-integration.md
Normal file
630
docs/modules/charts/bot-integration.md
Normal file
@@ -0,0 +1,630 @@
|
||||
# Bot Integration with Chart Signal Layers
|
||||
|
||||
> **⚠️ Feature Not Yet Implemented**
|
||||
>
|
||||
> The functionality described in this document for bot integration with chart layers is **planned for a future release**. It depends on the **Strategy Engine** and **Bot Manager**, which are not yet implemented. This document outlines the intended architecture and usage once these components are available.
|
||||
|
||||
The Chart Layers System provides seamless integration with the bot management system, allowing real-time visualization of bot signals, trades, and performance data directly on charts.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Architecture](#architecture)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Bot Data Service](#bot-data-service)
|
||||
- [Signal Layer Integration](#signal-layer-integration)
|
||||
- [Enhanced Bot Layers](#enhanced-bot-layers)
|
||||
- [Multi-Bot Visualization](#multi-bot-visualization)
|
||||
- [Configuration Options](#configuration-options)
|
||||
- [Examples](#examples)
|
||||
- [Best Practices](#best-practices)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Overview
|
||||
|
||||
The bot integration system provides automatic data fetching and visualization of:
|
||||
|
||||
- **Trading Signals**: Buy/sell/hold signals from active bots
|
||||
- **Trade Executions**: Entry/exit points with P&L information
|
||||
- **Bot Performance**: Real-time performance metrics and analytics
|
||||
- **Strategy Comparison**: Side-by-side strategy analysis
|
||||
- **Multi-Bot Views**: Aggregate views across multiple bots
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Automatic Data Fetching**: No manual data queries required
|
||||
- **Real-time Updates**: Charts update with live bot data
|
||||
- **Database Integration**: Direct connection to bot management system
|
||||
- **Advanced Filtering**: Filter by bot, strategy, symbol, timeframe
|
||||
- **Performance Analytics**: Built-in performance calculation
|
||||
- **Error Handling**: Graceful handling of database errors
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
components/charts/layers/
|
||||
├── bot_integration.py # Core bot data services
|
||||
├── bot_enhanced_layers.py # Enhanced chart layers with bot integration
|
||||
└── signals.py # Base signal layers
|
||||
|
||||
Bot Integration Components:
|
||||
├── BotFilterConfig # Configuration for bot filtering
|
||||
├── BotDataService # Database operations for bot data
|
||||
├── BotSignalLayerIntegration # Chart-specific integration utilities
|
||||
├── BotIntegratedSignalLayer # Auto-fetching signal layer
|
||||
├── BotIntegratedTradeLayer # Auto-fetching trade layer
|
||||
└── BotMultiLayerIntegration # Multi-bot layer management
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Bot Signal Visualization
|
||||
|
||||
```python
|
||||
from components.charts.layers import create_bot_signal_layer
|
||||
|
||||
# Create a bot-integrated signal layer for BTCUSDT
|
||||
signal_layer = create_bot_signal_layer(
|
||||
symbol='BTCUSDT',
|
||||
active_only=True,
|
||||
confidence_threshold=0.5,
|
||||
time_window_days=7
|
||||
)
|
||||
|
||||
# Add to chart
|
||||
fig = go.Figure()
|
||||
fig = signal_layer.render(fig, market_data, symbol='BTCUSDT')
|
||||
```
|
||||
|
||||
### Complete Bot Visualization Setup
|
||||
|
||||
```python
|
||||
from components.charts.layers import create_complete_bot_layers
|
||||
|
||||
# Create complete bot layer set for a symbol
|
||||
result = create_complete_bot_layers(
|
||||
symbol='BTCUSDT',
|
||||
timeframe='1h',
|
||||
active_only=True,
|
||||
time_window_days=7
|
||||
)
|
||||
|
||||
if result['success']:
|
||||
signal_layer = result['layers']['signals']
|
||||
trade_layer = result['layers']['trades']
|
||||
|
||||
# Add to chart
|
||||
fig = signal_layer.render(fig, market_data, symbol='BTCUSDT')
|
||||
fig = trade_layer.render(fig, market_data, symbol='BTCUSDT')
|
||||
```
|
||||
|
||||
## Bot Data Service
|
||||
|
||||
The `BotDataService` provides the core interface for fetching bot-related data from the database.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```python
|
||||
from components.charts.layers.bot_integration import BotDataService, BotFilterConfig
|
||||
|
||||
# Initialize service
|
||||
service = BotDataService()
|
||||
|
||||
# Create filter configuration
|
||||
bot_filter = BotFilterConfig(
|
||||
symbols=['BTCUSDT'],
|
||||
strategies=['momentum', 'ema_crossover'],
|
||||
active_only=True
|
||||
)
|
||||
|
||||
# Fetch bot data
|
||||
bots_df = service.get_bots(bot_filter)
|
||||
signals_df = service.get_signals_for_bots(
|
||||
bot_ids=bots_df['id'].tolist(),
|
||||
start_time=datetime.now() - timedelta(days=7),
|
||||
end_time=datetime.now(),
|
||||
min_confidence=0.3
|
||||
)
|
||||
```
|
||||
|
||||
### Available Methods
|
||||
|
||||
| Method | Description | Parameters |
|
||||
|--------|-------------|------------|
|
||||
| `get_bots()` | Fetch bot information | `filter_config: BotFilterConfig` |
|
||||
| `get_signals_for_bots()` | Fetch signals from bots | `bot_ids, start_time, end_time, signal_types, min_confidence` |
|
||||
| `get_trades_for_bots()` | Fetch trades from bots | `bot_ids, start_time, end_time, sides` |
|
||||
| `get_bot_performance()` | Fetch performance data | `bot_ids, start_time, end_time` |
|
||||
|
||||
### BotFilterConfig Options
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class BotFilterConfig:
|
||||
bot_ids: Optional[List[int]] = None # Specific bot IDs
|
||||
bot_names: Optional[List[str]] = None # Specific bot names
|
||||
strategies: Optional[List[str]] = None # Strategy filter
|
||||
symbols: Optional[List[str]] = None # Symbol filter
|
||||
statuses: Optional[List[str]] = None # Bot status filter
|
||||
date_range: Optional[Tuple[datetime, datetime]] = None
|
||||
active_only: bool = False # Only active bots
|
||||
```
|
||||
|
||||
## Signal Layer Integration
|
||||
|
||||
The `BotSignalLayerIntegration` provides chart-specific utilities for integrating bot data with chart layers.
|
||||
|
||||
### Chart-Specific Signal Fetching
|
||||
|
||||
```python
|
||||
from components.charts.layers.bot_integration import BotSignalLayerIntegration
|
||||
|
||||
integration = BotSignalLayerIntegration()
|
||||
|
||||
# Get signals for specific chart context
|
||||
signals_df = integration.get_signals_for_chart(
|
||||
symbol='BTCUSDT',
|
||||
timeframe='1h',
|
||||
bot_filter=BotFilterConfig(active_only=True),
|
||||
time_range=(start_time, end_time),
|
||||
signal_types=['buy', 'sell'],
|
||||
min_confidence=0.5
|
||||
)
|
||||
|
||||
# Get trades for chart context
|
||||
trades_df = integration.get_trades_for_chart(
|
||||
symbol='BTCUSDT',
|
||||
timeframe='1h',
|
||||
bot_filter=BotFilterConfig(strategies=['momentum']),
|
||||
time_range=(start_time, end_time)
|
||||
)
|
||||
|
||||
# Get bot summary statistics
|
||||
stats = integration.get_bot_summary_stats(bot_ids=[1, 2, 3])
|
||||
```
|
||||
|
||||
### Performance Analytics
|
||||
|
||||
```python
|
||||
# Get comprehensive performance summary
|
||||
performance = get_bot_performance_summary(
|
||||
bot_id=1, # Specific bot or None for all
|
||||
days_back=30
|
||||
)
|
||||
|
||||
print(f"Total trades: {performance['trade_count']}")
|
||||
print(f"Win rate: {performance['win_rate']:.1f}%")
|
||||
print(f"Total P&L: ${performance['bot_stats']['total_pnl']:.2f}")
|
||||
```
|
||||
|
||||
## Enhanced Bot Layers
|
||||
|
||||
Enhanced layers provide automatic data fetching and bot-specific visualization features.
|
||||
|
||||
### BotIntegratedSignalLayer
|
||||
|
||||
```python
|
||||
from components.charts.layers import BotIntegratedSignalLayer, BotSignalLayerConfig
|
||||
|
||||
# Configure bot-integrated signal layer
|
||||
config = BotSignalLayerConfig(
|
||||
name="BTCUSDT Bot Signals",
|
||||
auto_fetch_data=True, # Automatically fetch from database
|
||||
time_window_days=7, # Look back 7 days
|
||||
active_bots_only=True, # Only active bots
|
||||
include_bot_info=True, # Include bot info in hover
|
||||
group_by_strategy=True, # Group signals by strategy
|
||||
confidence_threshold=0.3, # Minimum confidence
|
||||
signal_types=['buy', 'sell'] # Signal types to show
|
||||
)
|
||||
|
||||
layer = BotIntegratedSignalLayer(config)
|
||||
|
||||
# Render automatically fetches data
|
||||
fig = layer.render(fig, market_data, symbol='BTCUSDT')
|
||||
```
|
||||
|
||||
### BotIntegratedTradeLayer
|
||||
|
||||
```python
|
||||
from components.charts.layers import BotIntegratedTradeLayer, BotTradeLayerConfig
|
||||
|
||||
config = BotTradeLayerConfig(
|
||||
name="BTCUSDT Bot Trades",
|
||||
auto_fetch_data=True,
|
||||
time_window_days=7,
|
||||
show_pnl=True, # Show profit/loss
|
||||
show_trade_lines=True, # Connect entry/exit
|
||||
include_bot_info=True, # Bot info in hover
|
||||
group_by_strategy=False
|
||||
)
|
||||
|
||||
layer = BotIntegratedTradeLayer(config)
|
||||
fig = layer.render(fig, market_data, symbol='BTCUSDT')
|
||||
```
|
||||
|
||||
## Multi-Bot Visualization
|
||||
|
||||
### Strategy Comparison
|
||||
|
||||
```python
|
||||
from components.charts.layers import bot_multi_layer
|
||||
|
||||
# Compare multiple strategies on the same symbol
|
||||
result = bot_multi_layer.create_strategy_comparison_layers(
|
||||
symbol='BTCUSDT',
|
||||
strategies=['momentum', 'ema_crossover', 'mean_reversion'],
|
||||
timeframe='1h',
|
||||
time_window_days=14
|
||||
)
|
||||
|
||||
if result['success']:
|
||||
for strategy in result['strategies']:
|
||||
signal_layer = result['layers'][f"{strategy}_signals"]
|
||||
trade_layer = result['layers'][f"{strategy}_trades"]
|
||||
|
||||
fig = signal_layer.render(fig, market_data, symbol='BTCUSDT')
|
||||
fig = trade_layer.render(fig, market_data, symbol='BTCUSDT')
|
||||
```
|
||||
|
||||
### Multi-Symbol Bot View
|
||||
|
||||
```python
|
||||
# Create bot layers for multiple symbols
|
||||
symbols = ['BTCUSDT', 'ETHUSDT', 'ADAUSDT']
|
||||
|
||||
for symbol in symbols:
|
||||
bot_layers = create_complete_bot_layers(
|
||||
symbol=symbol,
|
||||
active_only=True,
|
||||
time_window_days=7
|
||||
)
|
||||
|
||||
if bot_layers['success']:
|
||||
# Add layers to respective charts
|
||||
signal_layer = bot_layers['layers']['signals']
|
||||
# ... render on symbol-specific chart
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Auto-Fetch Configuration
|
||||
|
||||
```python
|
||||
# Disable auto-fetch for manual data control
|
||||
config = BotSignalLayerConfig(
|
||||
name="Manual Bot Signals",
|
||||
auto_fetch_data=False, # Disable auto-fetch
|
||||
active_bots_only=True
|
||||
)
|
||||
|
||||
layer = BotIntegratedSignalLayer(config)
|
||||
|
||||
# Manually provide signal data
|
||||
manual_signals = get_signals_from_api()
|
||||
fig = layer.render(fig, market_data, signals=manual_signals)
|
||||
```
|
||||
|
||||
### Time Window Management
|
||||
|
||||
```python
|
||||
# Custom time window
|
||||
config = BotSignalLayerConfig(
|
||||
name="Short Term Signals",
|
||||
time_window_days=1, # Last 24 hours only
|
||||
active_bots_only=True,
|
||||
confidence_threshold=0.7 # High confidence only
|
||||
)
|
||||
```
|
||||
|
||||
### Bot-Specific Filtering
|
||||
|
||||
```python
|
||||
# Filter for specific bots
|
||||
bot_filter = BotFilterConfig(
|
||||
bot_ids=[1, 2, 5], # Specific bot IDs
|
||||
symbols=['BTCUSDT'],
|
||||
active_only=True
|
||||
)
|
||||
|
||||
config = BotSignalLayerConfig(
|
||||
name="Selected Bots",
|
||||
bot_filter=bot_filter,
|
||||
include_bot_info=True
|
||||
)
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Dashboard Integration Example
|
||||
|
||||
```python
|
||||
# dashboard/callbacks/charts.py
|
||||
from components.charts.layers import (
|
||||
create_bot_signal_layer,
|
||||
create_bot_trade_layer,
|
||||
get_active_bot_signals
|
||||
)
|
||||
|
||||
@app.callback(
|
||||
Output('chart', 'figure'),
|
||||
[Input('symbol-dropdown', 'value'),
|
||||
Input('show-bot-signals', 'value')]
|
||||
)
|
||||
def update_chart_with_bots(symbol, show_bot_signals):
|
||||
fig = create_base_chart(symbol)
|
||||
|
||||
if 'bot-signals' in show_bot_signals:
|
||||
# Add bot signals
|
||||
signal_layer = create_bot_signal_layer(
|
||||
symbol=symbol,
|
||||
active_only=True,
|
||||
confidence_threshold=0.3
|
||||
)
|
||||
fig = signal_layer.render(fig, market_data, symbol=symbol)
|
||||
|
||||
# Add bot trades
|
||||
trade_layer = create_bot_trade_layer(
|
||||
symbol=symbol,
|
||||
active_only=True,
|
||||
show_pnl=True
|
||||
)
|
||||
fig = trade_layer.render(fig, market_data, symbol=symbol)
|
||||
|
||||
return fig
|
||||
```
|
||||
|
||||
### Custom Bot Analysis
|
||||
|
||||
```python
|
||||
# Custom analysis for specific strategy
|
||||
def analyze_momentum_strategy(symbol: str, days_back: int = 30):
|
||||
"""Analyze momentum strategy performance for a symbol."""
|
||||
|
||||
# Get momentum bot signals
|
||||
signals = get_bot_signals_by_strategy(
|
||||
strategy_name='momentum',
|
||||
symbol=symbol,
|
||||
days_back=days_back
|
||||
)
|
||||
|
||||
# Get performance summary
|
||||
performance = get_bot_performance_summary(days_back=days_back)
|
||||
|
||||
# Create visualizations
|
||||
signal_layer = create_bot_signal_layer(
|
||||
symbol=symbol,
|
||||
active_only=False, # Include all momentum bots
|
||||
time_window_days=days_back
|
||||
)
|
||||
|
||||
return {
|
||||
'signals': signals,
|
||||
'performance': performance,
|
||||
'layer': signal_layer
|
||||
}
|
||||
|
||||
# Usage
|
||||
analysis = analyze_momentum_strategy('BTCUSDT', days_back=14)
|
||||
```
|
||||
|
||||
### Real-time Monitoring Setup
|
||||
|
||||
```python
|
||||
# Real-time bot monitoring dashboard component
|
||||
def create_realtime_bot_monitor(symbols: List[str]):
|
||||
"""Create real-time bot monitoring charts."""
|
||||
|
||||
charts = {}
|
||||
|
||||
for symbol in symbols:
|
||||
# Get latest bot data
|
||||
active_signals = get_active_bot_signals(
|
||||
symbol=symbol,
|
||||
days_back=1, # Last 24 hours
|
||||
min_confidence=0.5
|
||||
)
|
||||
|
||||
# Create monitoring layers
|
||||
signal_layer = create_bot_signal_layer(
|
||||
symbol=symbol,
|
||||
active_only=True,
|
||||
time_window_days=1
|
||||
)
|
||||
|
||||
trade_layer = create_bot_trade_layer(
|
||||
symbol=symbol,
|
||||
active_only=True,
|
||||
show_pnl=True,
|
||||
time_window_days=1
|
||||
)
|
||||
|
||||
charts[symbol] = {
|
||||
'signal_layer': signal_layer,
|
||||
'trade_layer': trade_layer,
|
||||
'active_signals': len(active_signals)
|
||||
}
|
||||
|
||||
return charts
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
```python
|
||||
# 1. Use appropriate time windows
|
||||
config = BotSignalLayerConfig(
|
||||
time_window_days=7, # Don't fetch more data than needed
|
||||
confidence_threshold=0.3 # Filter low-confidence signals
|
||||
)
|
||||
|
||||
# 2. Filter by active bots only when possible
|
||||
bot_filter = BotFilterConfig(
|
||||
active_only=True, # Reduces database queries
|
||||
symbols=['BTCUSDT'] # Specific symbols only
|
||||
)
|
||||
|
||||
# 3. Reuse integration instances
|
||||
integration = BotSignalLayerIntegration() # Create once
|
||||
# Use multiple times for different symbols
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```python
|
||||
try:
|
||||
bot_layers = create_complete_bot_layers('BTCUSDT')
|
||||
|
||||
if not bot_layers['success']:
|
||||
logger.warning(f"Bot layer creation failed: {bot_layers.get('error')}")
|
||||
# Fallback to manual signal layer
|
||||
signal_layer = TradingSignalLayer()
|
||||
else:
|
||||
signal_layer = bot_layers['layers']['signals']
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Bot integration error: {e}")
|
||||
# Graceful degradation
|
||||
signal_layer = TradingSignalLayer()
|
||||
```
|
||||
|
||||
### Database Connection Management
|
||||
|
||||
```python
|
||||
# The bot integration handles database connections automatically
|
||||
# But for custom queries, follow these patterns:
|
||||
|
||||
from database.connection import get_session
|
||||
|
||||
def custom_bot_query():
|
||||
try:
|
||||
with get_session() as session:
|
||||
# Your database operations
|
||||
result = session.query(Bot).filter(...).all()
|
||||
return result
|
||||
except Exception as e:
|
||||
logger.error(f"Database query failed: {e}")
|
||||
return []
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **No signals showing on chart**
|
||||
```python
|
||||
# Check if bots exist for symbol
|
||||
service = BotDataService()
|
||||
bots = service.get_bots(BotFilterConfig(symbols=['BTCUSDT']))
|
||||
print(f"Found {len(bots)} bots for BTCUSDT")
|
||||
|
||||
# Check signal count
|
||||
signals = get_active_bot_signals('BTCUSDT', days_back=7)
|
||||
print(f"Found {len(signals)} signals in last 7 days")
|
||||
```
|
||||
|
||||
2. **Database connection errors**
|
||||
```python
|
||||
# Test database connection
|
||||
try:
|
||||
from database.connection import get_session
|
||||
with get_session() as session:
|
||||
print("Database connection successful")
|
||||
except Exception as e:
|
||||
print(f"Database connection failed: {e}")
|
||||
```
|
||||
|
||||
3. **Performance issues with large datasets**
|
||||
```python
|
||||
# Reduce time window
|
||||
config = BotSignalLayerConfig(
|
||||
time_window_days=3, # Reduced from 7
|
||||
confidence_threshold=0.5 # Higher threshold
|
||||
)
|
||||
|
||||
# Filter by specific strategies
|
||||
bot_filter = BotFilterConfig(
|
||||
strategies=['momentum'], # Specific strategy only
|
||||
active_only=True
|
||||
)
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
# Enable debug logging for bot integration
|
||||
logging.getLogger('bot_integration').setLevel(logging.DEBUG)
|
||||
logging.getLogger('bot_enhanced_layers').setLevel(logging.DEBUG)
|
||||
|
||||
# This will show detailed information about:
|
||||
# - Database queries
|
||||
# - Data fetching operations
|
||||
# - Filter applications
|
||||
# - Performance metrics
|
||||
```
|
||||
|
||||
### Testing Bot Integration
|
||||
|
||||
```python
|
||||
# Test bot integration components
|
||||
from tests.test_signal_layers import TestBotIntegration
|
||||
|
||||
# Run specific bot integration tests
|
||||
pytest.main(['-v', 'tests/test_signal_layers.py::TestBotIntegration'])
|
||||
|
||||
# Test with mock data
|
||||
def test_bot_integration():
|
||||
config = BotSignalLayerConfig(
|
||||
name="Test Bot Signals",
|
||||
auto_fetch_data=False # Use manual data for testing
|
||||
)
|
||||
|
||||
layer = BotIntegratedSignalLayer(config)
|
||||
|
||||
# Provide test data
|
||||
test_signals = pd.DataFrame({
|
||||
'timestamp': [datetime.now()],
|
||||
'signal_type': ['buy'],
|
||||
'price': [50000],
|
||||
'confidence': [0.8],
|
||||
'bot_name': ['Test Bot']
|
||||
})
|
||||
|
||||
fig = go.Figure()
|
||||
result = layer.render(fig, market_data, signals=test_signals)
|
||||
|
||||
assert len(result.data) > 0
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Core Classes
|
||||
|
||||
- **`BotDataService`** - Main service for database operations
|
||||
- **`BotSignalLayerIntegration`** - Chart-specific integration utilities
|
||||
- **`BotIntegratedSignalLayer`** - Auto-fetching signal layer
|
||||
- **`BotIntegratedTradeLayer`** - Auto-fetching trade layer
|
||||
- **`BotMultiLayerIntegration`** - Multi-bot layer management
|
||||
|
||||
### Configuration Classes
|
||||
|
||||
- **`BotFilterConfig`** - Bot filtering configuration
|
||||
- **`BotSignalLayerConfig`** - Signal layer configuration with bot options
|
||||
- **`BotTradeLayerConfig`** - Trade layer configuration with bot options
|
||||
|
||||
### Convenience Functions
|
||||
|
||||
- **`create_bot_signal_layer()`** - Quick bot signal layer creation
|
||||
- **`create_bot_trade_layer()`** - Quick bot trade layer creation
|
||||
- **`create_complete_bot_layers()`** - Complete bot layer set
|
||||
- **`get_active_bot_signals()`** - Get signals from active bots
|
||||
- **`get_active_bot_trades()`** - Get trades from active bots
|
||||
- **`get_bot_signals_by_strategy()`** - Get signals by strategy
|
||||
- **`get_bot_performance_summary()`** - Get performance analytics
|
||||
|
||||
For complete API documentation, see the module docstrings in:
|
||||
- `components/charts/layers/bot_integration.py`
|
||||
- `components/charts/layers/bot_enhanced_layers.py`
|
||||
754
docs/modules/charts/configuration.md
Normal file
754
docs/modules/charts/configuration.md
Normal file
@@ -0,0 +1,754 @@
|
||||
# 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:
|
||||
name: str
|
||||
indicator_type: str
|
||||
parameters: Dict[str, Any]
|
||||
display_type: str # 'overlay', 'subplot'
|
||||
color: str
|
||||
line_style: str = 'solid' # 'solid', 'dash', 'dot'
|
||||
line_width: int = 2
|
||||
opacity: float = 1.0
|
||||
visible: bool = True
|
||||
subplot_height_ratio: float = 0.3 # For subplot indicators
|
||||
```
|
||||
|
||||
#### 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
|
||||
default: Any = None
|
||||
min_value: Optional[Union[int, float]] = None
|
||||
max_value: Optional[Union[int, float]] = None
|
||||
description: str = ""
|
||||
```
|
||||
|
||||
#### `IndicatorSchema`
|
||||
|
||||
Complete schema for an indicator type:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class IndicatorSchema:
|
||||
indicator_type: IndicatorType
|
||||
display_type: DisplayType
|
||||
required_parameters: List[IndicatorParameterSchema]
|
||||
optional_parameters: List[IndicatorParameterSchema] = field(default_factory=list)
|
||||
min_data_points: int = 1
|
||||
description: str = ""
|
||||
```
|
||||
|
||||
### 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(
|
||||
name: str,
|
||||
indicator_type: str,
|
||||
parameters: Dict[str, Any],
|
||||
display_type: Optional[str] = None,
|
||||
color: str = "#007bff",
|
||||
**display_options
|
||||
) -> tuple[Optional[ChartIndicatorConfig], List[str]]
|
||||
|
||||
# Get schema for indicator type
|
||||
def get_indicator_schema(indicator_type: str) -> Optional[IndicatorSchema]
|
||||
|
||||
# Get available indicator types
|
||||
def get_available_indicator_types() -> List[str]
|
||||
|
||||
# Validate parameters for specific type
|
||||
def validate_parameters_for_type(
|
||||
indicator_type: str,
|
||||
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
|
||||
)
|
||||
|
||||
# Utility functions from indicator_defs
|
||||
from .indicator_defs import (
|
||||
create_indicator_config, get_indicator_schema, get_available_indicator_types
|
||||
)
|
||||
```
|
||||
|
||||
## 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(
|
||||
name="EMA 21",
|
||||
indicator_type=IndicatorType.EMA,
|
||||
parameters={"period": 21, "price_column": "close"},
|
||||
color="#2E86C1",
|
||||
line_width=2
|
||||
)
|
||||
|
||||
if config:
|
||||
print(f"Created: {config.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.
|
||||
313
docs/modules/charts/indicators.md
Normal file
313
docs/modules/charts/indicators.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# Indicator System Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The Crypto Trading Bot Dashboard features a comprehensive modular indicator system that allows users to create, customize, and manage technical indicators for chart analysis. The system supports both overlay indicators (displayed on the main price chart) and subplot indicators (displayed in separate panels below the main chart).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [System Architecture](#system-architecture)
|
||||
2. [Current Indicators](#current-indicators)
|
||||
3. [User Interface](#user-interface)
|
||||
4. [File Structure](#file-structure)
|
||||
5. [Adding New Indicators](#adding-new-indicators)
|
||||
6. [Configuration Format](#configuration-format)
|
||||
7. [API Reference](#api-reference)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
```
|
||||
components/charts/
|
||||
├── indicator_manager.py # Core indicator CRUD operations
|
||||
├── indicator_defaults.py # Default indicator templates
|
||||
├── layers/
|
||||
│ ├── indicators.py # Overlay indicator rendering
|
||||
│ └── subplots.py # Subplot indicator rendering
|
||||
└── config/
|
||||
└── indicator_defs.py # Indicator definitions and schemas
|
||||
|
||||
config/indicators/
|
||||
└── user_indicators/ # User-created indicators (JSON files)
|
||||
├── sma_abc123.json
|
||||
├── ema_def456.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Key Classes
|
||||
|
||||
- **`IndicatorManager`**: Handles CRUD operations for user indicators
|
||||
- **`UserIndicator`**: Data structure for indicator configuration
|
||||
- **`IndicatorStyling`**: Appearance and styling configuration
|
||||
- **Indicator Layers**: Rendering classes for different indicator types
|
||||
|
||||
## Current Indicators
|
||||
|
||||
### Overlay Indicators
|
||||
These indicators are displayed directly on the price chart:
|
||||
|
||||
| Indicator | Type | Parameters | Description |
|
||||
|-----------|------|------------|-------------|
|
||||
| **Simple Moving Average (SMA)** | `sma` | `period` (1-200) | Average price over N periods |
|
||||
| **Exponential Moving Average (EMA)** | `ema` | `period` (1-200) | Weighted average giving more weight to recent prices |
|
||||
| **Bollinger Bands** | `bollinger_bands` | `period` (5-100), `std_dev` (0.5-5.0) | Price channels based on standard deviation |
|
||||
|
||||
### Subplot Indicators
|
||||
These indicators are displayed in separate panels:
|
||||
|
||||
| Indicator | Type | Parameters | Description |
|
||||
|-----------|------|------------|-------------|
|
||||
| **Relative Strength Index (RSI)** | `rsi` | `period` (2-50) | Momentum oscillator (0-100 scale) |
|
||||
| **MACD** | `macd` | `fast_period` (2-50), `slow_period` (5-100), `signal_period` (2-30) | Moving average convergence divergence |
|
||||
|
||||
## User Interface
|
||||
|
||||
### Adding Indicators
|
||||
|
||||
1. **Click "➕ Add New Indicator"** button
|
||||
2. **Configure Basic Settings**:
|
||||
- Name: Custom name for the indicator
|
||||
- Type: Select from available indicator types
|
||||
- Description: Optional description
|
||||
3. **Set Parameters**: Type-specific parameters appear dynamically
|
||||
4. **Customize Styling**:
|
||||
- Color: Hex color code
|
||||
- Line Width: 1-5 pixels
|
||||
5. **Save**: Creates a new JSON file and updates the UI
|
||||
|
||||
### Managing Indicators
|
||||
|
||||
- **✅ Checkboxes**: Toggle indicator visibility on chart
|
||||
- **✏️ Edit Button**: Modify existing indicator settings
|
||||
- **🗑️ Delete Button**: Remove indicator permanently
|
||||
|
||||
### Real-time Updates
|
||||
|
||||
- Chart updates automatically when indicators are toggled
|
||||
- Changes are saved immediately to JSON files
|
||||
- No page refresh required
|
||||
|
||||
## File Structure
|
||||
|
||||
### Indicator JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "ema_ca5fd53d",
|
||||
"name": "EMA 10",
|
||||
"description": "10-period Exponential Moving Average for fast signals",
|
||||
"type": "ema",
|
||||
"display_type": "overlay",
|
||||
"parameters": {
|
||||
"period": 10
|
||||
},
|
||||
"styling": {
|
||||
"color": "#ff6b35",
|
||||
"line_width": 2,
|
||||
"opacity": 1.0,
|
||||
"line_style": "solid"
|
||||
},
|
||||
"visible": true,
|
||||
"created_date": "2025-06-04T04:16:35.455729+00:00",
|
||||
"modified_date": "2025-06-04T04:54:49.608549+00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
config/indicators/
|
||||
└── user_indicators/
|
||||
├── sma_abc123.json # Individual indicator files
|
||||
├── ema_def456.json
|
||||
├── rsi_ghi789.json
|
||||
└── macd_jkl012.json
|
||||
```
|
||||
|
||||
## Adding New Indicators
|
||||
|
||||
For developers who want to add new indicator types to the system, please refer to the comprehensive step-by-step guide:
|
||||
|
||||
**📋 [Quick Guide: Adding New Indicators (`adding-new-indicators.md`)](./adding-new-indicators.md)**
|
||||
|
||||
This guide covers:
|
||||
- ✅ Complete 11-step implementation checklist
|
||||
- ✅ Full code examples (Stochastic Oscillator implementation)
|
||||
- ✅ File modification requirements
|
||||
- ✅ Testing checklist and common patterns
|
||||
- ✅ Tips and best practices
|
||||
|
||||
## Configuration Format
|
||||
|
||||
### User Indicator Structure
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class UserIndicator:
|
||||
id: str # Unique identifier
|
||||
name: str # Display name
|
||||
description: str # User description
|
||||
type: str # Indicator type (sma, ema, etc.)
|
||||
display_type: str # "overlay" or "subplot"
|
||||
parameters: Dict[str, Any] # Type-specific parameters
|
||||
styling: IndicatorStyling # Appearance settings
|
||||
visible: bool = True # Default visibility
|
||||
created_date: datetime # Creation timestamp
|
||||
modified_date: datetime # Last modification timestamp
|
||||
```
|
||||
|
||||
### Styling Options
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class IndicatorStyling:
|
||||
color: str = "#007bff" # Hex color code
|
||||
line_width: int = 2 # Line thickness (1-5)
|
||||
opacity: float = 1.0 # Transparency (0.0-1.0)
|
||||
line_style: str = "solid" # Line style
|
||||
```
|
||||
|
||||
### Parameter Examples
|
||||
|
||||
```python
|
||||
# SMA/EMA Parameters
|
||||
{"period": 20}
|
||||
|
||||
# RSI Parameters
|
||||
{"period": 14}
|
||||
|
||||
# MACD Parameters
|
||||
{
|
||||
"fast_period": 12,
|
||||
"slow_period": 26,
|
||||
"signal_period": 9
|
||||
}
|
||||
|
||||
# Bollinger Bands Parameters
|
||||
{
|
||||
"period": 20,
|
||||
"std_dev": 2.0
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### IndicatorManager Class
|
||||
|
||||
```python
|
||||
class IndicatorManager:
|
||||
def create_indicator(self, name: str, indicator_type: str,
|
||||
parameters: Dict[str, Any], **kwargs) -> Optional[UserIndicator]
|
||||
|
||||
def load_indicator(self, indicator_id: str) -> Optional[UserIndicator]
|
||||
|
||||
def update_indicator(self, indicator_id: str, **kwargs) -> bool
|
||||
|
||||
def delete_indicator(self, indicator_id: str) -> bool
|
||||
|
||||
def list_indicators(self) -> List[UserIndicator]
|
||||
|
||||
def get_indicators_by_type(self, display_type: str) -> List[UserIndicator]
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
|
||||
```python
|
||||
# Get indicator manager
|
||||
manager = get_indicator_manager()
|
||||
|
||||
# Create new indicator
|
||||
indicator = manager.create_indicator(
|
||||
name="My SMA 50",
|
||||
indicator_type="sma",
|
||||
parameters={"period": 50},
|
||||
description="50-period Simple Moving Average",
|
||||
color="#ff0000"
|
||||
)
|
||||
|
||||
# Load indicator
|
||||
loaded = manager.load_indicator("sma_abc123")
|
||||
|
||||
# Update indicator
|
||||
success = manager.update_indicator(
|
||||
"sma_abc123",
|
||||
name="Updated SMA",
|
||||
parameters={"period": 30}
|
||||
)
|
||||
|
||||
# Delete indicator
|
||||
deleted = manager.delete_indicator("sma_abc123")
|
||||
|
||||
# List all indicators
|
||||
all_indicators = manager.list_indicators()
|
||||
|
||||
# Get by type
|
||||
overlay_indicators = manager.get_indicators_by_type("overlay")
|
||||
subplot_indicators = manager.get_indicators_by_type("subplot")
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Indicator not appearing in dropdown**
|
||||
- Check if registered in `INDICATOR_REGISTRY`
|
||||
- Verify the indicator type matches the class name
|
||||
|
||||
2. **Parameters not saving**
|
||||
- Ensure parameter fields are added to save callback
|
||||
- Check parameter collection logic in `save_new_indicator`
|
||||
|
||||
3. **Chart not updating**
|
||||
- Verify the indicator layer implements `calculate_values` and `create_traces`
|
||||
- Check if indicator is registered in the correct registry
|
||||
|
||||
4. **File permission errors**
|
||||
- Ensure `config/indicators/user_indicators/` directory is writable
|
||||
- Check file permissions on existing JSON files
|
||||
|
||||
### Debug Information
|
||||
|
||||
- Check browser console for JavaScript errors
|
||||
- Look at application logs for Python exceptions
|
||||
- Verify JSON file structure with a validator
|
||||
- Test indicator calculations with sample data
|
||||
|
||||
### Performance Considerations
|
||||
|
||||
- Indicators with large periods may take longer to calculate
|
||||
- Consider data availability when setting parameter limits
|
||||
- Subplot indicators require additional chart space
|
||||
- Real-time updates may impact performance with many indicators
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Naming Conventions**
|
||||
- Use descriptive names for indicators
|
||||
- Include parameter values in names (e.g., "SMA 20")
|
||||
- Use consistent naming patterns
|
||||
|
||||
2. **Parameter Validation**
|
||||
- Set appropriate min/max values for parameters
|
||||
- Provide helpful descriptions for parameters
|
||||
- Use sensible default values
|
||||
|
||||
3. **Error Handling**
|
||||
- Handle insufficient data gracefully
|
||||
- Provide meaningful error messages
|
||||
- Log errors for debugging
|
||||
|
||||
4. **Performance**
|
||||
- Cache calculated values when possible
|
||||
- Optimize calculation algorithms
|
||||
- Limit the number of active indicators
|
||||
|
||||
5. **User Experience**
|
||||
- Provide immediate visual feedback
|
||||
- Use intuitive color schemes
|
||||
- Group related indicators logically
|
||||
---
|
||||
|
||||
*Back to [Chart System Documentation (`README.md`)]*
|
||||
280
docs/modules/charts/quick-reference.md
Normal file
280
docs/modules/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
|
||||
pytest tests/test_*_strategies.py -v
|
||||
pytest tests/test_validation.py -v
|
||||
pytest tests/test_defaults.py -v
|
||||
|
||||
# Test specific component
|
||||
pytest tests/test_example_strategies.py::TestEMACrossoverStrategy -v
|
||||
```
|
||||
|
||||
## File Locations
|
||||
|
||||
- **Main config**: `components/charts/config/`
|
||||
- **Documentation**: `docs/modules/charts/`
|
||||
- **Tests**: `tests/test_*_strategies.py`
|
||||
- **Examples**: `components/charts/config/example_strategies.py`
|
||||
Reference in New Issue
Block a user