Vasily.onl 666a58e799 documentation update

2025-06-06 20:33:29 +08:00

21 KiB

Raw Permalink Blame History

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.

Overview
Architecture
Quick Start
Components
User Indicator Management
Configuration System
Example Strategies
Validation System
API Reference
Examples
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

# 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).

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) - Comprehensive guide to the indicator system
⚡ Quick Guide: Adding New Indicators (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

# 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

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

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:

Required Fields - Essential configuration validation
Height Ratios - Chart layout validation
Indicator Existence - Indicator availability check
Timeframe Format - Valid timeframe patterns
Chart Style - Color and styling validation
Subplot Config - Subplot compatibility check
Strategy Consistency - Strategy-timeframe alignment
Performance Impact - Resource usage warnings
Indicator Conflicts - Redundancy detection
Resource Usage - Memory and rendering estimates

Usage:

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:

EMA Crossover (Intermediate, Medium Risk)
- Classic trend-following with EMA crossovers
- Best for trending markets, 15m-4h timeframes
Momentum Breakout (Advanced, High Risk)
- Fast indicators for momentum capture
- Volume confirmation, best for volatile markets
Mean Reversion (Intermediate, Medium Risk)
- Oversold/overbought conditions
- Multiple RSI periods, best for ranging markets
Scalping (Advanced, High Risk)
- Ultra-fast indicators for 1m-5m trading
- Tight risk management, high frequency
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:

@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:

@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:

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

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

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

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

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

# 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

# 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

# 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

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

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

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

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

"Indicator not found in defaults"

# Check available indicators
from components.charts.config import get_all_default_indicators
available = get_all_default_indicators()
print(list(available.keys()))

"Total height exceeds 1.0"

# Adjust height ratios
config.main_chart_height = 0.7
for subplot in config.subplot_configs:
    subplot.height_ratio = 0.1

"Invalid timeframe format"

# 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:

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)
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) - Comprehensive documentation for integrating bot signals with charts

Support

For issues, questions, or contributions:

Check existing configurations in example_strategies.py
Review validation rules in validation.py
Test with comprehensive validation
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

21 KiB Raw Permalink Blame History Unescape Escape

Modular Chart Layers System

Table of Contents

Overview

Key Features

Supported Indicators

Architecture

Dashboard Integration

Modular Components

Key Features

Usage in Dashboard

User Indicator Management

Features

Quick Access

Current User Indicators

Usage Example

Quick Start

Basic Usage

Custom Strategy Creation

Components

1. Configuration System

2. Validation System

3. Example Strategies

Configuration System

Indicator Definitions

Strategy Configuration

Default Configurations

Example Strategies

EMA Crossover Strategy

Custom Strategy Creation

Validation System

Comprehensive Validation

Validation Rules Information

API Reference

Core Classes

StrategyChartConfig

StrategyExample

Utility Functions

Configuration Access

JSON Export/Import

Validation

Examples

Example 1: Using Pre-built Strategy

Example 2: Creating Custom Configuration

Example 3: Filtering Strategies

Example 4: Validation with Error Handling

Best Practices

1. Configuration Design

2. Indicator Selection

3. Strategy Development

4. Validation Usage

5. Performance Optimization

Error Handling

Common Issues and Solutions

Testing

Future Enhancements

Bot Integration

Support

The modular chart system is designed to be extensible and maintainable, providing a solid foundation for advanced trading chart functionality.

21 KiB

Raw Permalink Blame History

`StrategyChartConfig`

`StrategyExample`