TCPDashboard/docs/modules/charts/quick-reference.md

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